The purpose of this document is to describe how to integrate with AgoraPlus services for the purpose of repair management and spare part ordering process by external third-party applications. The document is intended for third- party developers to support them with a trouble-free development of integration services / APIs required by AgoraPlus solution. 

The document mainly focusses on the repair process and will give the third-party developers an understanding of the AgoraPlus Architecture, middleware involved and different touchpoints catering to complete the Repair starting from request raised by a Consumer for repair until the Claims submitted for the repair performed. 

AgoraPlus has exposed a set of REST APIs that the third-party application needs to consume to send the data/submit claims to OEMs. 

Each of the touchpoints with third party applications are further detailed in the documentation for reference during the development

The repair process involves the following entities:

• Consumer
• Service center
• AgoraPlus
• The OEM

and could include the following phases:

• Workorder
• Repair management
• Claim report (for reimbursement)
• PEX
• Invoicing management

2.1 Workorder management

There are 2 main starting points for a repair: Directly at the workshop, mainly for SDAs (Small Household Appliances) or via a call center when the consumer calls mainly for MDAs (Large Household Appliances).

In this second scenario, when the consumer calls the OEM's call center, a ticket is created by the customer service agent in the OEM CRM and is assigned to the service partner. This last action will send a work order assigned to the technician to AgoraPlus.

To get the list of workorder freshly sent to AgoraPlus, we provide 2 web APIs:

• [GET] /Repair/GetNewMandates:
  Returns the list of work orders with a "NEW" status. If you set the "AUTOACCEPTED" parameter to TRUE, the Web API will automatically change the status of the work order to "ACCPETED" and create the corresponding repair file.
  
   
• [GET] /Repair/GetAcceptedMandates:
   Returns the list of work orders with an "ACCEPTED" status. Some companies will prefer to retrieve only the work orders that they have previously accepted manually in AgoraPlus.

Important: A work order is unalterable. For each work order with an "ACCEPTED" status, there is an associated repair file. This repair file will need to be updated throughout the repair.

2.1.1 Output

The main object is the following. It will contain a list of “NEW” or “ACCEPTED” work orders depending on the web API you called (see above)

AgoraWebServices.Models.Response.GetNewMandatesResponse {

ResponseData (Array[AgoraWebServices.Models.Response.NewMandateResponseData], optional): Response data ,

ResponseStatus (string, optional): Response status ("S" : Sucess, "E": Error, "W":Warning) ,

IsValid (boolean, optional): Response validity ,

ResponseMessage (string, optional): Response message ,

ResponseErrorMessage (string, optional): Response Error Message

}

The “NewMandateResponseData” object contains a work order (called a mandate) and its corresponding repair file if it has previously been “ACCEPTED” (InterventionId). The "IsValid, ResponseStatus, ResponseMessage" fields are returned and will be populated in case you called the "GetNewMandates" web API with the "Autoaccept" parameter set to "true". These fields will inform you of the correct creation of the repair file associated with the work order (InterventionId)

AgoraWebServices.Models.Response.NewMandateResponseData {

IsValid (boolean, optional): Response validity ,

ResponseStatus (string, optional): Response status ("S" : Sucess, "E": Error, "W":Warning) ,

ResponseMessage (string, optional): Response message ,

ResponseErrorMessage (string, optional): Response Error Message ,

Mandate (AgoraWebServices.Models.Return.MandateLightResponse, optional): Mandate data ,

InterventionId (integer, optional): Associated intervention identifier when auto accept parameter is activated

}

The "MandateLightResponse" contains all the information provided by the end consumer regarding the failure. It embeds (Device, symptom, consumer information, retailer information, etc.)

AgoraWebServices.Models.Return.MandateLightResponse {

MandateId (integer, optional): Mandate identifier in Agora ,

ManufacturerId (integer, optional): Originator identifier ,

OEMId (integer, optional): Manufacturer identifier ,

ClientCode (string, optional): Client code ,

OrderMission (string, optional): Mission order ,

InterventionTypeId (integer, optional): Intervention type identifier ,

...

}

The "InterventionTypeLight» object provaides information about the type of repair (see repair type list)

AgoraWebServices.Models.Return.InterventionTypeLight {

InterventionTypeId (integer, optional): Intervention type identifier ,

Label (string, optional): Label ,

ShortDescription (string, optional): Description ,

IsUnderWarranty (boolean, optional): Is product under warranty

}

The "ResellerLight" object contains information about the reseller from which the device was purchased.

AgoraWebServices.Models.Return.ResellerLight {

ResellerId (integer, optional): Reseller identifier ,

ResellerCode (string, optional): Reseller code ,

ResellerFileNumber (string, optional): Associated file number ,

ResellerAddress1 (string, optional): Reseller address 1 ,

...

}

The "ConsumerLight" object contains information about the end consumer

AgoraWebServices.Models.Return.ConsumerLight {

Title (string, optional): Consumer Title 1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Company ,

LastName (string, optional): Consumer last name ,

FirstName (string, optional): Consumer first name ,

Address1 (string, optional): Address first line ,

...

}

The "SuggestedPartLight" object contains a list a suggested part needed for the repair. This service s not provided by all OEMs

AgoraWebServices.Models.Return.SuggestedPartLight {

SuggestedPartRef (string, optional): Reference ,

Quantity (integer, optional): Quantity ,

Comment (string, optional): Comment ,

Label (string, optional): Label

} 

2.2 Repair management

To follow the work in progress, AgoraPlus provides a list of Web APIs dedicated to the repair workflow.

• [POST] Repair/CreateRepair:

if the repair is directly taken care of by the service partner, without a work order sent beforehand, then this API should be called to create the repair file in AgoraPlus (ISO to this present in the repairer's after-sales service software)
  

• [POST] /Repair/UpdateRepair
   The work in progress can be done in real time and should be updated at each step of the repair. The web API allows to update the entire repair file (Appliance information, consumer information, retailer, diagnosis, spare parts…)

The update of the repair is organized in 2 parts:

• The update of repair information
• The update of the repair statuses 

2.2.1 Update of repair information

At any step of the repair, you can update the repair global information:

1/ update the appliance information:

AgoraWebServices.Models.Agora.CompleteRepairState {

Brand (string, optional): Product brand ,

Family (string, optional): Product family (e.g. Coffee machine) ,

CommercialRef (string): Product commercial reference ,

TechnicalRef (string, optional): Product technical reference ,

ManufacturingCode (string): Manufacturing date ,

SerialNumber (string, optional): Product serial number ,

PurchaseDate (string, optional): Product purchase date (UTC Format if timeZoneId is specified) ,

ConsumerContract (string, optional): Consumer warranty contract number ,

GCPlusContract (string, optional): Indicates if the warranty extension is a GCPlus contract ,

...

} 

2/ Update the consumer information

AgoraWebServices.Models.Agora.Consumer {

ConsumerId (string, optional): Consumer ID (unique identifier of the consumer mainly used in countries like Chile, Peru...),

Title (integer): Consumer Title 1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Company ,

LastName (string): Consumer last name ,

FirstName (string): Consumer first name ,

Address1 (string): Consumer address 1 ,

Address2 (string, optional): Consumer address 2 ,

Address3 (string, optional): Consumer address 3 ,

Zip (string): Consumer zip code ,

Town (string): Consumer town ,

State (string, optional): Consumer state (Mainly used for United States) ,

Country (integer): Consumer country (ISO 3 digits) ,

Phone (string): Consumer Phone number ,

PhoneType (string, optional): Information concerning the phone (e.g. phone of Madame) ,

SMSCode (string, optional): Phone number with SMS capabilities (mobile) ,

ProPhone (string, optional): Business phone number ,

Email (string, optional): Email of the consumer ,

Remarks (string, optional): Remark given by the consumer ,

OptInSurvey (boolean, optional): Consumer satisfaction survey Opt in ,

LngId (integer, optional): Consumer Language Id (ex: 1036 for French)

ConsumerInvoice (integer, optional): Flag indication if the repair should be invoiced to the consumer 0 : no / 1: Yes ,

}

3/ Retailler information

AgoraWebServices.Models.Agora.Reseller {

Name (string, optional): Reseller name ,

Email (string, optional): Reseller email ,

Phone (string, optional): Reseller phone number

Address1 (string, optional): Reseller address 1 ,

Address2 (string, optional): Reseller address 2 ,

Address3 (string, optional): Reseller address 3 ,

Zip (string, optional): Reseller zip code, 

Town (string, optional): Reseller town ,

State (string, optional): Reseller state (Mainly used for United States) ,

Country (integer, optional): Reseller country (ISO 3 digits)  

}

4/ Repair information

AgoraWebServices.Models.Agora.Intervention {

InterventionType (integer): Type of intervention (see the list below)

RepairOriginCode (string): Repair origin code. Possible values: "CONSUMER" or "RESELLER" ,

FailureDescription (string, optional): Failure description ,

FIdent (string, optional): Failure spare part reference, 

InterventionStartDate (string, optional): Repair start date (UTC Format if timeZoneId is specified) ,

InterventionEndDate (string, optional): Repair end date (UTC Format if timeZoneId is specified) ,

ProductReturnDate (string, optional): Date of return of the device (UTC Format if timeZoneId is specified)

IRISCondition (string, optional): IRIS Condition ,

IRISConditionEX (string, optional): IRIS Condition EX ,

IRISSymptom (string, optional): IRIS Symptom ,

IRISSection (string, optional): IRIS Section ,

IRISDefault (string, optional): IRIS Defect code. ,

IRISRepair (string, optional): IRIS Repair code. ,

DefaultCode (string, optional): Default code (NON-IRIS). ,

...

}

5/ Spare part information

Spare parts can be added at several steps of the repair and in 2 different sections.

The first section is the repair itself, in which all the spare parts the service partner we’ll need to do the repair:

AgoraWebServices.Models.Agora.CompleteRepairState {

...

Parts (Array[AgoraWebServices.Models.Agora.Part], optional): List of spareparts needed for the repair ,

...

}

AgoraWebServices.Models.Agora.Part {

Reference (string, optional): Spare part reference. ,

Quantity (integer, optional): Quantity ordered. ,

Note (string, optional): Comment. ,

OrderNumber (string, optional): Spare part order number. ,

ToBeOrdered (boolean, optional): To be ordered?

}

For each spare part, it is possible to set the “order number” when it has already been ordered. It is also possible to set the attribute “ToBeOrdered” to TRUE. This will allow you to directly order the spare part for that single repair calling the /Repair/PlaceRepairSparepartOrder web API.

The second section is available in the status update.   It allows to notify the OEM about an issue or simply update the OEM about the in progress about a spare part order.

See the below section “Update of the work in progress, using status code”.

2.2.2 Update of the work in progress, using status code

The work in progress of the repair should be done by mapping the state of your internal service software with that of AgoraPlus.

The life cycle of a repair cannot be fixed, but the diagram below describes one of the most common workflows:

To report the work in progress, you will have to use the object “StateNature” which can cover 7 different types of use cases.

AgoraWebServices.Models.Agora.StateNature {

Code (string, optional): Status code,

Comment (string, optional): Comment. ,

AppointmentNumber (integer, optional): Rank of the appointment (1st appointment, 2nd appointment…) ,

AppointmentDate (string, optional): Start date of the appointment (UTC Format if timeZoneId is specified in associated word order). ,

AppointmentEndDate (string, optional): End date of the appointment (UTC Format if timeZoneId is specified in associated word order). ,

Parts (Array[AgoraWebServices.Models.Agora.Part], optional): Spare parts concerned by the status code (e.g code 200,201,202,204, 205)

}

The “StateNature” should be set in the global “CompleteRepairState” object, which can contain a list of “StateNature”

 AgoraWebServices.Models.Agora.CompleteRepairState {

...

StateNatures (Array[AgoraWebServices.Models.Agora.StateNature], optional): Repair file status (see state nature list) ,

...

}

1/ Update with appointments status

...

  "StateNatures": [

  {

    "Code": "102",

    "Comment": "Appointment confirmed 2022-04-02 ",

    "AppointmentNumber": 1,

    "AppointmentDate": "2022-05-02T08:00:00.000Z",

    "AppointmentEndDate": "2022-05-02T09:00:00.000Z",

  }

], ...

The list of appointment status

2/ Update with spare part information

...

   "StateNatures": [

     {

       "Code": "205",

       "Comment": "Spare part Ordered",

       "Parts": [

        {

          "Reference": "0070817965D",

          "Quantity": 1,

          "Note": "Key spare part for the repair",

          "ToBeOrdered": true

        }

      ]

    }

  ], ...

Other use case to inform about a broken spare part received
 ...

  "StateNatures": [

    {

      "Code": "204",

      "Comment": "cracked spare part. Repair blocked",

      "Parts": [

        {

          "Reference": "0070817965D",

          "Quantity": 1,

          "Note": "cracked spare part"

        }

      ]

    }

  ], ...

List of spare part status code

3/ Update with global repair information

...

   "StateNatures": [

     {

       "Code": "305",

       "Comment": "Repair completed"

   ], ...

List of global repair status

4/ Update with appliance situation

...

   "StateNatures": [

     {

       "Code": "406",

       "Comment": "Diagnosis in progress"

  ], ...

List of appliance situation status

5/ Update with consumer related status

...

   "StateNatures": [

     {

       "Code": "501",

      "Comment": "Waiting for approval of the quotation N125559"

   ], ...
 
 

List of consumer related status

6/ Update with repair not possible or out of warranty repair status

...

  "StateNatures": [

    {

      "Code": "901",

      "Comment": "Consumer’s just called. Appliance works as new"

   ], ...
 

NB: After the creation of the Claim report, Agora automatically updates the status of the related Repair file to the 601 "Closed with warranty intervention" 

2.3 Order spare parts for a repair

To order the spare parts needed for a repair, the service partner can create a dedicated order. For this, Agoraplus provides a web API which, once called, will automatically generate a single spare part order linked to the repair and transmit it to the OEM.

To track the logistic information, Agoraplus provides the following web API 

List of Logistic status returned back by the OEM

When repair is not possible, the service partner must request an after-sales solution. This process must be done directly in AgoraPlus because now AgoraPlus does not provide any web API.

2.5 Claim report

At the end of the repair, if the repair is supported by the OEM (even partially), the service partner must request reimbursement for the repair carried out.

To do so, AgoraPlus provides the following web APIs:

• [POST] /Repair/CreateWarrantyClaims
   That web API is used to create the claim 
• [POST] /Repair/UpdateWarrantyClaim
   That web API is used to update claim information and fix errors

2.5.1 Inputs

These 2 web APIs contains the same following objects:

The main object is the “WarrantyClaim” object:
 

AgoraWebServices.Models.Agora.WarrantyClaim {

ClaimType (AgoraWebServices.Models.Agora.WarrantyClaimType, optional): Report containing device and folder informations ,

ClaimDeliv (AgoraWebServices.Models.Agora.WarrantyClaimDeliv, optional): Exceptional delivery address for parts ordered under warranty ,

ClaimResal (AgoraWebServices.Models.Agora.WarrantyClaimResal, optional): Dealer contact information for the finished product ,

ClaimConso (AgoraWebServices.Models.Agora.WarrantyClaimConso, optional): Address and contact details of the consumer ,

ClaimInfos (AgoraWebServices.Models.Agora.WarrantyClaimInfos, optional): Intervention description ,

ClaimLab (AgoraWebServices.Models.Agora.WarrantyClaimLab, optional): This section is used to indicate the manufacturer participation, as the case may be, in the form of a package, labor or travel expenses. ,

ClaimParts (Array[AgoraWebServices.Models.Agora.WarrantyClaimPart], optional): List of parts ordered under warranty or whose refund is requested

}

The “WarrantyClaimType” object contains all information related to the appliance and define the type of repair:

AgoraWebServices.Models.Agora.WarrantyClaimType {

ManufacturerId (integer): Manufacturer Id ,

CommercialRef (string, optional): Commercial reference ,

TechnicalRef (string, optional): Technical reference ,

SerialNumber (string, optional): Serial number ,

...

}

The “WarrantyClaimResal” object contains all information about the retailer

AgoraWebServices.Models.Agora.WarrantyClaimResal {

CompanyName (string, optional): Company name ,

Zip (string, optional): Zip code ,

City (string, optional): City ,

State (string, optional): State ,

Country (integer, optional): Consumer country (ISO 3 digits) ,

DistributorFileNumber (string, optional): Work order number at the retailer level

}

The “WarrantyClaimConso” object contains all information about the consumer

AgoraWebServices.Models.Agora.WarrantyClaimConso {

Title (integer, optional): Consumer Title 1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Company ,

LastName (string, optional): Consumer last name ,

FirstName (string, optional): Consumer first name ,

StreetNumber (string, optional): Consumer street number ,

Address1 (string, optional): Consumer address 1 ,

Address2 (string, optional): Consumer address 2 ,

...

}

The “WarrantyClaimInfos” object contains all information about repair

AgoraWebServices.Models.Agora.WarrantyClaimInfos {

CallDate (string, optional): Product call date ,

InterventionStartDateTime (string, optional): First RDV start time ,

InterventionEndDateTime (string, optional): First RDV end time ,

DefaultPartRef (string, optional): Origin part reference ,

IRISCondition (string, optional): IRIS condition. ,

IRISConditionEX (string, optional): IRIS extended condition. ,

IRISSymptom (string, optional): IRIS symptom. ,

IRISSection (string, optional): IRIS section. ,

...

}

The “WarrantyClaimLab” object contains all information about the labor and other fees used to calculate the cost of the reimbursement 

AgoraWebServices.Models.Agora.WarrantyClaimLab {

OriginCode (string, optional): This code corresponds to the code of the repayment plan or identifies the conditions of intervention. ,

LaborHours (integer, optional): Number of hours spent in labor ,

LaborMinutes (integer, optional): Number of minutes spent in labor ,

LaborCost (number, optional): Cost of labor valued by the repairer ,

TravelKilometers (integer, optional): Number of kilometers to travel ,

...

}

The “WarrantyClaimParts” object contains all the spare part used to repair the appliance in order to calculate the cost of the reimbursement 

AgoraWebServices.Models.Agora.WarrantyClaimPart {

PartReference (string, optional): Part reference used for the intervention ,

Quantity (integer, optional): Quantity used ,

Comments (string, optional): Comment or countermark at the line ,

BillNumber (string, optional): This information should be specified only for the parts of a report under warranty with request to have. Field must not be specified for warranty orders

}

These 2 APIs takes 2 important parameters as:

• The “language” in which you expect the error and warning messages (See LCID list)
• The “transferIsValid” parameter to indicate if you want to automatically transfer the claim when the status of the claim is “VALID” 

2.5.2 Outputs

When a claim is created, the AgoraPlus business rule engine is going to control the content of each claim and will return a list of errors and/or warnings detected. These rules are specific to each OEM.

The returned message is composed of the following embedded objects:

AgoraWebServices.Models.Response.CreateWarrantyClaimsResponse {

ResponseData (Array[AgoraWebServices.Models.Return.WarrantyClaimResult], optional): Response data ,

ResponseStatus (string, optional): Response status ("S" : Sucess, "E": Error, "W":Warning) ,

IsValid (boolean, optional): Response validity ,

ResponseMessage (string, optional): Response message ,

ResponseErrorMessage (string, optional): Response Error Message

}

AgoraWebServices.Models.Return.WarrantyClaimResult {

ReportNumber (string, optional): Associated report number ,

ClaimID (integer, optional): Claim identifier in Agora ,

IsValid (boolean, optional): Validity ,

ValidationErrors (Array[AgoraWebServices.Models.Return.ValidationResult], optional): Validation errors ,

ErrorMessage (string, optional): Error message

}

AgoraWebServices.Models.Return.ValidationResult {

Field (string, optional): Field associated to the error ,

ErrorMessage (string, optional): Error message ,

MessageType (string, optional): Type of the error message :

E : Error

W : Warning

}

Sample of JSON response:

{

  "ResponseStatus": "S",

  "IsValid": true,

  "ResponseMessage": null,

  "ResponseErrorMessage": "",

  "ResponseData": {

    "ReportNumber": null,

    "ClaimID": 5272901,

    "IsValid": false,

    "ValidationErrors": [

      {

        "Field": "Serial Number",

        "ErrorMessage": "The size of the field should be 19 character(s)",

        "MessageType": "E"

      },

      {

        "Field": "Call date",

        "ErrorMessage": "Data is mandatory",

        "MessageType": "E"

      },

      {

        "Field": "ConsumerDto.LastName",

        "ErrorMessage": "Data is mandatory",

        "MessageType": "E"

      },

      {

        "Field": "ConsumerDto.Address1",

        "ErrorMessage": "Data is mandatory",

        "MessageType": "E"

      },

      {

        "Field": "ConsumerDto.Zip",

        "ErrorMessage": "Data is mandatory",

        "MessageType": "E"

      },

      {

        "Field": "ConsumerDto.MobilePhone",

        "ErrorMessage": "Data is mandatory",

        "MessageType": "E"

      }

    ],

    "ErrorMessage": null

  }

}

NB: As the business rules are specific to each OEM, we highly recommend displaying the error message as they are provided by AgoraPlus and avoid any kind of automatic processing as rules can change at any time.

2.5.2 OEM Tracking response

Once the claim has been transferred to the OEM, you’ll have to wait for the approval of the OEM.

To track the approval, AgoraPlus provides the following web API:

List of the “LastStatus” codes 

At the end of the of the month, depending on the invoicing method, the OEM will send via Agoraplus to the service partner a draft invoice by email. In such a case, the service partner is expected to return to AgoraPlus the invoice number linked to this draft invoice. This action will trigger the payment.

The service center receives an email with the authorization, in PDF format, and the list, in CSV format, of all approved claim reports in the previous month. The service center, after creating the invoice in its aftersales software, sends the invoice reference to Agora.

To communicate the details of the invoice to Agora, you need to: 

• call the appropriate API by sending the invoice number and the draft invoice number
  • [POST] Repair/CreateeInvoice

AgoraPlus provides the following web APIs to update you after sales software repository.

To update your spare part repository, AgoraPlus provides the following web API:

Parameters:

    The “ManufacturerId”: The Agoraplus unique OEM identifier (see the OEM List)

    The “Date”: The date of the last call you did as AgoraPlus will send only the delta.

    The “Language”  (See LCID list)