The purpose of this document is to provide support for quickly getting started with the tool for developers wishing to use the APIs set up by AGORA. 

It is not intended to replace the various help and support portals set up by AGORA SAS. For more information and assistance, please contact support directly at [email protected]

If your organization allows you to install an application on your desktop, you can directly install the application by clicking: https://agorav3.agoraplus.com/solmis.client.agora.application

If your organization doesn't allow you to download the app this way, you can save the following zip file:

http://agorav3.agoraplus.com/zippedinstall/install.zip

Then, simply extract the files from this archive and then click setup to launch the application.

The URL of our test API is: https://preprod-api.agoraplus.com

You will be able to use the Pre-production version of AGORA to carry out your tests.

Download link for the Pre-production version: http://preprod3.solmis.agoraplus.com/

You will need to contact us so that we can send you a key in order to access the API.

We'll give you the URL of the production API once your tests are successful.

The repair process involves the following actors:

• Customer
• Approved service partners (SP)
• AGORA
• Manufacturers

And provides for the following steps:

1. Repair management

2. Warranty management

3. Invoicing management

2.1 Repair Management

When SP receives a repair request for a product, it must keep track of the relevant "repair status" changes in its information system and transmit this information to Agora. In Agora, the repair activity is represented by the entity called Work Order.

    2.1.1 Functional analysis of the life cycle of an SP repair

The treatment cycle of a SP repair is represented by the following statuses:

2.1.1.1 Opening

This is the initial status of the repair process and represents the insertion phase of a new request for repair in the SP information system.

2.1.1.2 Acceptance

This is the status after the opening of the work order, in which the SP records the receipt of the request for repair.

A repair file is created and will allow you to enter the details of the repair.

2.1.1.3 Processing

This is the post-acceptance status in which the SP is analyzing the products to be repaired.

2.1.1.4 Waiting for parts

If spare parts are needed, this is the status in which the SP waits to receive the spare parts to carry out the repair.

2.1.1.5 Documents received

This is the status in which the SP receives the ordered spare parts and executes the repair.

2.1.1.6 Closing

It is due to the status after the repair activity in which the SP indicates that it has completed the repair.

2.1.1.7 Delivered products

This is the final status of the process and represents the delivery of the repaired product to the consumer.

    2.1.2 Functional analysis of the life cycle of a repair file in Agora

The processing cycle of a repair file is represented by the following states:

2.1.2.1 Repair accepted (code 100)

This is the initial state automatically assigned by Agora when creating the Work Order.

2.1.2.2 Product received (code 405)

This is the status that must be sent to Agora when you receive the product from the customer. (cf. 2. 1.1.2. Acceptance).

2.1.2.3 In treatment (code 406)

This is the state that must be sent when the repair is in progress. (See 2.1.1.3.  Processing).

2.1.2.4 Parts ordered (code 205)

This is the state that must be sent when waiting for parts. (cf. 2. 1.1.4. Pending documents).

2.1.2.5 Parts received (code 201)

This is the status to be sent when the ordered spare parts are available (see 2.1.1. 5.  Documents received) .

2.1.2.6 Repair performed (code 305)

This is the state that needs to be sent once the repair is complete. (See 2.1.1. 6.  Closing).

2.1.2.7 Closed with WR (code 601)

This is the state automatically assigned by Agora when creating the warranty report (report of the repair)." This entity will be dealt with in the paragraph on the management of warranty repairs. (cf.  2.2.2 Creation of the Warranty Claim).

2.1.2.8 Delivered product (code 602)

This is the status that must be sent when the station delivers the product to the customer. (cf.  2.1.1.7.  Delivered Product).

SUMMARY TABLE

2.1.3 Creation of the repair file

When the SP inserts a new repair into its information system, it is necessary to create the repair file in Agora.

NOTE

When creating the repair file, Agora automatically assigns the status "WO accepted" (code 100) to the repair file.

2.1.4 Update of the repair file

It is necessary to transmit each modification of the status of the repair: update the information of the repair file in Agora by transmitting its status 

At the end of the repair, if the product is under warranty, the SP transfers through Agora to the manufacturer the Warranty Report containing information on the repair, labor costs and spare parts used. In Agora, the warranty report is represented by the entity named Warranty Claim.

2.2.1 Warranty Claim Lifecycle Analysis

The statutes of the Warranty Claim are as follows:

2.2.1.1 Not valid (not transmitted)

Indicates that the Warranty Claim is not considered valid by Agora because one or more data is missing and/or incorrect. The Warranty Claim in this status must be updated to be formally valid for Agora (with validations rules of the manufacturer) and to be transferred to the manufacturer.

2.2.1.2 Valid (not transmitted)

Indicates that the Warranty Claim is considered formally valid by Agora. The warranty claim that is in this state can be transferred to the manufacturer.

2.2.1.3 Not conform

Indicates that the Warranty Claim has been transferred and is not considered valid by the manufacturer because one or more data is missing and/or incorrect. The warranty claim in this status must be updated in order to be transferred back to the manufacturer.

2.2.1.4 Accepted / Closed and accepted

Indicates that the Warranty Claim has been transferred and deemed valid by the manufacturer.

2.2.2 Creation of the Warranty Claim

After completing the repair of a product under warranty, the following steps must be performed in order:

• Update the Work Order to the "Repair Completed" state (code 305)
  • web API [ /api/repair/updaterepair ]
• Create the Warranty Claim
  • web API [ /api/repair/createwarrantyclaim ]

NOTE

At the same time as the Warranty Claim is created, Agora automatically modifies the status of the repair file concerned and puts it in a "Closed with WR" state (code 601) (see 1.1.2.7 "Closed with WR" (code 601)).

2.2.3 Transfer of the Warranty Claim to the manufacturer

When SP considers that all the information contained in the repair file is complete, and that the repair can be transferred to the manufacturer for the creation of the warranty report, it is necessary:

• To update the Warranty Claim by changing the value of the transferIfValid parameter to "true"

1. web API [ /api/repair/updatewarrantyclaim ]

NOTE

All Warranty Claims in Agora that have this attribute to "true" have been deemed valid by the SP to be transferred to the manufacturer, are sent by Agora to the manufacturer by a daily "job".

2.2.4 Checking of the Warranty Claim status

To check the status of the Warranty Claim:

2.2.5 Warranty Claim Update

It is necessary to update the Warranty Claim when it is in status:

• Not valid (not transmitted): this is the case where there are anomalies found by Agora during creation (in the response of Agora there is the message with the error found)."
• Not conform: is the case where the warranty report has not been accepted by the manufacturer for incorrect or missing data.

In these cases, the Warranty Claim must be corrected by the SP in order to be sent to the manufacturer.

To correct the error, it is necessary to:

• Update the Warranty Claim with appropriate changes
  • web API [ /api/repair/updatewarrantyclaim ]
• Update the associated repair file by ensuring that the correct status is passed, 601 
  • web API [ /api/repair/updaterepair ]

NOTE

After the creation of the Warranty Claim, Agora automatically changed the status of the repair file corresponding to "Repair completed" (code 305), the last report sent by the SP, to "Closed with WR" (code 601).

• Update the repair file to the state 602 "Delivered product"
  • web API [ /api/repair/updaterepair ]

2.3 Invoicing Management

(Especially for some manufacturers)

At the beginning of the month, SP sends Agora the reference of its invoice for the previous month's warranty repairs. Agora will send this information to the manufacturer for payment of the services.

2.3.1 Integration with AGORA

The SP receives an email with the authorization, in PDF format, and the list, in CSV format, of all warranty reports, received and accepted by the manufacturer, relating to the past month.  The SP, after creating the invoice, sends the reference to Agora.

2.3.2 Sending the invoice reference

To communicate to Agora the details of your invoice, you must:

• Call the appropriate API with your invoice number and authorization code.
  • web API [/api/repair/createeinvoice ].

AGORA APIs are a set of RESTful APIs designed to integrate AGORA's functionality with other IT systems.

Access to the AGORA API is authorized by authentication. To authenticate, you must enter the API keys as a parameter in the request to the web service. The CAT must request the KEY API at the email address [email protected].

There are two different environments, one dedicated to development and testing called "pre-production" and the other representing the "production" environment. 

The two environments differ for the access url and the KEY service access API which are different.

Pre-production environment URL :

 https://preprod-api.agoraplus.com

Production environment URL :

 https://api.agoraplus.com

This is the setting used for web services authentication. 

The parameter name is apikey and the value is different between the test environment and production.

3.3.2 Accept

This is the parameter used to indicate the type of MIME media that the client is able to recognize and accept. 

The parameter name is Accept and its value is application/json.

3.3.3 Content type

This is the parameter used to specify the type of MIME media used for the content of the request. Used for POST and PUT methods.

The parameter name is Content-Type and its value is application/json.

3.3.4 Example

GET /api/product/printmanufacturerproducts/19/01-01-2020/English HTTP/1.1

Host: api.agoraplus.com

api_key: xxxxxxxxxxxxxxxxxxxxxxx

Accept: application/json

Content-Type: application/json

3.4 Service Response

3.4.1 Media type

The MIME media type used for the response content is the application/json and the encoding used is UTF-8.

3.4.2 Date / Timestamp

The standard used to indicate dates and time is ISO 8601 and the format is YYYY-MM-DDThh:mm:ssZ

3.4.3 HTTP Header - Status codes

3.4.4 Message body - Structure

{

    "ResponseStatus": {},

    "IsValid": {},

    "ResponseMessage": {},

    "ResponseErrorMessage": {},

    "ResponseData": {}

}

3.4.4.1 Response status

An alphanumeric value indicating the status of the response.

Allowed values:

• S : Success
• E : Error
• W : Warning

3.4.4.2 IsValid

A Boolean value indicating the validity of the response. 

Allowed values:

• True : The message contains no errors 
• False : Message contains errors

3.4.4.3 ResponseMessage

An alphanumeric value indicating a message related to the response

ResponseErrormessage

An alphanumeric value indicating the error message if the response is invalid.

ResponseData

Table containing the objects of the response

3.4.5 Example

{

    "ResponseStatus": "S",

    "IsValid": true,

    "ResponseMessage": "19656 created or updated products found since 01/01/2020",

    "ResponseErrorMessage": null,

    "ResponseData": [  {}, {}, {}, ...]

}

The technical documentation for the REST API to be used is available on the Swagger interface.

For the preproduction environment, you can find it at [https://preprod-api.agoraplus.com].

For the production environment, at [https://api.agoraplus.com].

4.2 Repair file

4.2.1 POST - Creation of the repair file

The following service allows you to create the repair file. 

Service: /api/repair/createrepair?language={language}

Documentation : https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_CreateRepair

4.2.1.1 Data structure

The fields to be filled in are highlighted in red and blue.

AgoraWebServices.Models.Agora.Repair

{

  "ActivationDate": "datetime", (es. " 2020-01-24T14:41:16.093Z") (Acceptance date UTC Europe Rome) 

  "Brand": "string", ( Text description of the mark )

  "CallDate": "datetime”, ( Date d’acceptation UTC  Europe Rome )  

  "ClientNumber": "string", (Service Center Agora Code)

  "CommercialRef": "string", (Commercial reference of the product to be repaired)

  "Consumer": {

                    "ConsumerInvoice": "integer", [0 - No, 1 - Yes] (Indicates whether the repair is invoiced to the consumer)

                    "Title": "integer", [ 1 - Mrs, 2 - Miss, 3 - Mr., 4 - Sté] (title)

                    "LastName": "string",

                    "FirstName": "string",

                    "Address1": "string",

                    "Address2": "string",

                    "Address3": "string",

                    "Zip": "string",

                    "Town": "string",

                    "Country": "integer", [380 - Italia] ( Code ISO 3 caractères)

                    "Phone": "string",

                    "PhoneType": "string",

                    "SMSCode": "string", (mobile)

                    "ProPhone": "string",

                   "Email": "string",

                    "Remarks": "string"

  },

  "ConsumerContract": "string",

  "Family": "string",

  "GCPlusContract": "string",

"Intervention": {

                 "InterventionType": "integer", [1 – Warranty repair] ( Type of repair ) 

                    "FailureDescription": "string", (Fault Description)

                    "IRISCondition": "string",

                   "IRISConditionEX": "string",

                    "IRISSymptom": "string",

                    "IRISSection": "string",

                    "IRISDefault": "string",

                    "ReplaceRef": "string"

  },

  "ManufacturerId": "integer", [19 - DèLonghi] ( Manufacturer code),

   "MissionOrder": "string", (Unique repair identifier for a CTA) 

  "OutOfWarAgreementNumber": "string",

  "PurchaseDate": "datetime", Purchase Date UTC Europe Rome)

  "ResellerCountry": “integer”,

  "ResellerName": "string",

  "ResellerTown": "string",

  "ResellerZip": "string",

  "SerialNumber": "string", (Serial Number)

  "TechnicalRef": "string", (Technical reference of the product to be repaired)

  "TimeZoneId": "string" (Time zone to identify and convert dates, Europa/Rome ISO code) 

4.2.2 POST - Update of the repair file

The following service allows the repair file to be updated.

Service : /api/repair/updaterepair

Documentation : https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_UpdateRepair

4.2.2.1 Data structure

The fields to be filled in are highlighted in red and blue.

Array[AgoraWebServices.Models.Agora.MandateState {

{

 "ManufacturerId": "integer", [19 - DèLonghi] Manufacturer code),

 "MissionOrder": "string", (Unique Repair Identifier for STA)

 "NewConsumer": 

{

                               "BusinessPhoneNumber": "string",

                               "Civility": "string", [ 1 - Mrs, 2 - Miss, 3 - Mr., 4 - Sté] (Civility)

                               "Email": "string",

                               "FirstName": "string",

                               "LastName": "string",

                "PhoneNumber": "string", (Fixed or possibly mobile phone of the consumer)

                         "PhoneType": "string",

                         "PostalAddress": {

                                              "AddressLines": [ "string" ],

                                              "City": "string",

                 "CountryIsoCode": "string", [250 - France] (ISO code 3 characters)

                                              "Zip": "string"

                               },

                               "SmsCode": "string" (Consumer mobile)

    },

    "NewProductReference": {

                   "CommercialReference": "string", Commercial reference of the product to be repaired)

                               "TechnicalReference": "string" (Technical reference)

    },

    "StateNatures":

    [

                      {

                                 "Code": "string", Agora status code )

                                 "Comment": "string",

                                 "AppointmentNumber": "integer" "1", fixed to 1

                    "AppointmentDate": "datetime", date of change of state

                    "AppointmentEndDate": "datetime", date of change of

                    "Parts":

                       [ ( List of states, e.g. "pending" (201) )         

                                              {

"Note": "string",

"OrderNumber": "string", (Cf internal order number or DèLonghi)

"Quantity": “number”,

"Reference": "string" (part reference)

                                                }

                                  ]

                     }

    ],

    "StatusCode": "string",

    "Parts":

                  [ (List of parts used for repair)

                               {

      "Note": "string",

      "OrderNumber": "string",

      "Quantity": “interger”,

      "Reference": "string" (part reference)

                               }

                  ]

  }

4.3 WarrantyClaim (WR)

4.3.1 POST - Creation of the Warranty Claim

The following service allows the creation of the Warranty Claim 

Service : /api/repair/createwarrantyclaims?language={language}

Documentation : https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_CreateWarrantyClaims

4.3.1.1 Data structure

The fields to be filled in are highlighted in red and blue.

Array[AgoraWebServices.Models.Agora.WarrantyClaim

{

      "ClaimType":

      {

      "ManufacturerId": "integer", [19 - DèLonghi] Manufacturer Code),

      "CommercialRef": "string", (Commercial reference of the product to be repaired)

"TechnicalRef": "string", (Technical reference  of the product to be repaired)

      "SerialNumber": "string", Serial number of the product to be repaired)

      "PurchaseDate": "datetime", (Date of purchase of the product)

      "Name": "string", (Name of thetechnicianwho carried out the repair)

      "ReportNumber": "string", identifier of the CTA repair report

      "ProductStatus": "string", [S = under warranty]

      "OutOfWarAgreementNumber": "string",

      "ConsumerContractNumber": "string",

      "MissionOrderNumber": "string", (unique repair identifier for the STA) 

      "ExchangeAgreementNumber": "string",

      "AgoraRegistrationNumber": "string",

      "CounterOne": "integer",

      "CounterTwo": "integer"

      },

                          "ClaimDeliv": (Application Data)

      {  

                                           "DeliveryMode": "integer",

                                           "CustomerDeliveredCode": "string",

      "Company": "string",

      "Name": "string",

      "Address1": "string",

      "Address2": "string",

      "Address3": "string",

      "Zip": "string",

      "City": "string",

      "Country": "integer"

      },

                         "ClaimResal": 

                     {

                                           "CompanyName": "string",

                                           "Zip": "string",

                                          "City": "string",

                                           "Country": "integer",

                                           "DistributorFileNumber": "string"

                        },

                         "ClaimConso": (Consumer Data)

                    {

      "Title": "integer",  [ 1 - Mrs, 2 - Ms, 3 - Mr, 4 - Company]

      "LastName": "string",

      "FirstName": "string",

      "StreetNumber": "string",

      "Address1": "string",

      "Address2": "string",

      "Address3": "string",

      "Zip": "string",

      "City": "string",

      "Country": "integer", ( Code ISO 3 chiffres )

      "Phone": "string",

      "Mobile": "string",

      "Email": "string",

      "ConsumerKey": "string" (Customer code in the center registry)

                        },

            "ClaimInfos": Repair Data)

    { 

      "IsInterventionAt48h": "boolean", (Indicates if the repair took place more than 48 hours after the consumer request)

      "CallDate": "datetime", (Date of acceptance)

      "InterventionStartDateTime": "datetime",  Repair Start Date)

      "InterventionEndDateTime": "datetime",  (End date of repair)

      "DefaultPartRef": "string",

      "IRISCondition": "string",

      "IRISConditionEX": "string",

      "IRISSymptom": "string",

      "IRISSection": "string",

      "IRISDefault": "string",

      "IRISRepair": "string",

      "FailureDescription": "string", (Fault Description)

  "InterventionDescription": "string", (Description of the repair, once the repair is completed)

      "ActionCode": "string",

      "ActionPattern": "integer",

      "DefaultCode": "string" (Default Code)

                      },

                        "ClaimLab": (Repair data)

                   {

      "OriginCode": "string", (Code repair)

      "LaborHours": "integer",

      "LaborMinutes": "integer",

      "LaborCost": "number",

      "TravelKilometers": "integer",

      "TravelCost": "number",

      "OtherCosts": "number",

      "OtherCostsDescription": "string",

      "Currency": "string", [ EUR ]

      "Redirection": true

                         },

                           "ClaimParts": (parts)

                     [

                     {

        "PartReference": "string",  (Parts References)

        "Quantity": "integer", 

        "Comments": "string",

        "BillNumber": "string"

                     }

     ]

}

4.3.2 POST - Warranty Claim Update

The following service allows the warranty claim to be updated

Service : /api/repair/updatewarrantyclaim?warrantyClaimId={warrantyClaimId}&language={language}

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_UpdateWarrantyClaim

4.3.2.1 Data structure

See section 4.3.1.1. Data structure

4.3.3 GET - List of Warranty Claims

The next service returns the Warranty Claims.

Service : /api/repair/getwarrantyclaims

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_GetWarrantyClaims

4.4 Invoice

4.4.1 POST - Sending Invoice

The following service allows you to send the invoice number and the corresponding authorization number.

Service: /api/repair/createeinvoice?preInvoiceNumber=&customerInvoiceNumber=

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_CreateEInvoice

Below are the REST API services to download the basic data, to be used in your management, of products, spare parts, labor rates, error codes and BOMs.

The following service returns the list of products.

Service : api/product/printmanufacturerproducts/{ManufacturerId}/{date}/{language}

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/Product/Product_PrintProductsByManufacturer

5.1.1 Response data structure

ManufacturerProductResponseData

{

BrandCode,

BrandLabel,

CommercialReference,

Country,

Family,

Label,

TechnicalReference

}

The following service returns the list of parts.

Service : api/product/printmanufacturerspareparts/{ManufacturerId}/{date}/{language}

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/SparePart/SparePart_PrintSparePartsByManufacturer

The {date} parameter is used to indicate the search start date and the format is MM-DD-YYYY

5.2.1 Response data structure

ManufacturerSparePartResponseData

{

CanBeOrdered, (non-valued field)

Currency, 

ExpiryDate,

Label,

PartReference,

PartType,

Price,

PriceGroupCode, (unvalued field)

ReplaceReference, (unvalued field)

Status (unvalued field)  

}

The following service returns the list of labor packages.

Service : /api/repair/getwarrantylabourcost/{ManufacturerId}

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_GetWarrantyLabourCost

5.3.1 Response data structure

WarrantyLaborCost

{

                                Brand,

                                CommercialReference,

                                Cost,

                                Currency,

                                Family,

                                IsForProductExchange,

                                LaborCode

}

5.4 List of error codes

The following service returns the list of error codes.

Service : /api/repair/printdefectcodes?manufacturerID={ManufacturerId} &language={language}

Documentation : 

http://preprod-api.agoraplus.com/apidoc/ui/index#!/Repair/Repair_PrintDefectCodes

5.4.1 Response data structure

DefectCodes

{

                                DefectCode,

                Description,

                FamilyCode

}

5.5 BOM - Part 1

The following service returns the key (AGORAProductKey) to use as a parameter in the service to download the bill of materials for the end item.

Service : /api/repair/searchproductref/{ManufacturerId}/{keyword}/{countrycode}

The {keyword} parameter is used to specify the reference to the code of the model or end item to be searched.

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/...

5.5.1 Response data structure

SearchProductRef

{

ManufacturerId,

BrandLabel,

Description,

Refcom,

Reftech,

AGORAProductKey

}

5.6 BOM - Part 2

The following service returns the bill of materials of the end item using the key (AGORAProductKey) obtained with the previous paragraph

Service : api/product/printbomdata? AGORAProductKey={AGORAProductKey}

The {keyword} parameter is used to specify the reference to the code of the model or end item to be searched.

Documentation : 

https://preprod-api.agoraplus.com/apidoc/ui/index#!/...

5.6.1 Response data structure

SearchProductRef

PrintBomData

{                              

                                {

                                PartRef,

                                Description,

                                Quantity

                                },{...}
 }

Below is the list of information contained in the csv file sent monthly to the SP.

Important : The warranty report may contain multiple replacement parts used for repair. 

Therefore, the excel file will contain as many lines as the warranty report.