Documentation à l’adresse des développeurs pour l’utilisation de l’API de pilotage des données et des traitements pour le Fond Réparations EEE.

Sommaire

minLevel	1
maxLevel	3

Objectifs

Cette API permet l’intégration des étapes de traitements et l'échange des données entre les applications métiers de réparateur et le système d’information gérant les données de soutien pour le Fond Réparations EEE.
Basée sur les standards JSON Rest, elle s’adresse aux intégrateurs et développeurs.

Diagramme de séquence

Drawio

mVer	2
zoom	1
simple	0
inComment	0
pageId	3629121571
custContentId	3629121595
lbox	1
diagramDisplayName	diag_sequence_api_ecl.drawio
contentVer	3
revision	3
baseUrl	https://ecologic-france.atlassian.net/wiki
diagramName	diag_sequence_api_ecl.drawio
pCenter	0
width	696
links
tbstyle
height	1281

Spécifications de l’API

Authentification

Appeler l’API depuis une service nécessite de disposer d’une clé d’authentification à passer dans l'entête HTTP de chacune des requêtes.

Nom de la clé d’entête = api_key

Valeur de la clé = <votre_clé_api>

Info

<votre_clé_api> existe

soit en version de PreProduction à utiliser lors des développements et des tests
soit en version de Production et les appels à l’API déclencheront des actions concrètes et réelles auprès du Fond Réparation EEE.

Cette clé est unique pour chaque compte e-reparateur.co.
Attention à ne pas la divulguer. Si jamais vous aviez un doute n’hésitez pas à prévenir le support = support@e-reparateur.eco

Récupération de votre clé d’authentification

Connectez vous à votre compte e-reparateur et allez dans les propriétés de votre compte.
Vous trouverez 2 clés associées à votre compte

une clé d’API de Pré Production
une clé d’API de Production

TODO = capture de l’interface e-reparateur

Référentiels des données

Les créations de dossier de demande de soutien et de remboursement nécessitent de s’appuyer sur des données de références utilisées par l’API.
Celle-ci permet par contre de récupérer ces référentiels mis à jour régulièrement (au moins 1 fois toutes les 24h)

Récupération de la liste des marques - /PrintBrandList
État
colour Green
title GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/PrintBrandList

URL Prod = https://apiecologic.e-reparateur.eco/PrintBrandList

Fonctions

permet de récupérer la liste des marques supportées par Ecologic.
Appeler cette API vous permettra de disposer d'un code marque unique et de l'associer à votre référentiel.

usage

entrée = pas de paramètre spécifique

example de réponse

Bloc de code

language	json

{
  "ResponseData": [
    {
      "BrandName": "string",
      "BrandId": "string"
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

Récupérer la liste des types de produit - /PrintProductTypeList
État
colour Green
title GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/PrintProductTypeList

URL Prod = https://apiecologic.e-reparateur.eco/PrintProductTypeList

Fonctions

permet de récupérer la liste des types de produit supportés par Ecologic.

Appeler cette API vous permettra de disposer d'un code unique pour chaque type de produit afin de l'associer à votre référentiel. Cette API restitue également pour chaque type de produit les symptômes et les codes réparation éligibles au soutien.

Example usage

entrée = pas de paramètre spécifique

sortie =

ProductId = Identifiant unifié Ecologic et Ecosystem du type de produit (ex: 3015)

ProductName =Désignation du type de produit (ex: Four (hors micro-ondes et mini-four))

EligibilityStartDate = Date de début d'éligibilité

EligibilityEndDate = Date de fin d'éligibilité

RepairCodes[] = Liste des codes réparation éligibles pour le type de produits et pour Ecosystem

IRISSymptoms[] = Liste des codes symptome IRIS éligibles pour le type de produits et pour Ecologic

example de réponse

Bloc de code

language	json

{
  "ResponseData": [
    {
      "ProductId": "string",
      "ProductName": "string",
      "EligibilityStartDate": "2022-06-27",
      "EligibilityEndDate": "2022-06-27",
      "RepairCodes": [
        {
          "RepairCode": "string"
        }
      ],
      "IRISSymtoms": [
        {
          "IRISSymtom": "string"
        }
      ]
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

Demandes de soutien

Plusieurs méthodes sont disponibles pour gérer la contruction et la soumission d’une demande de soutien, tout en s’assurant que les équipements concernés y seront éligibles.

Calculer le montant du soutien - /CalculateEcoSupport
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/CalculateEcoSupport

URL Prod = https://apiecologic.e-reparateur.eco/CalculateEcoSupport

Fonctions

permet de connaître l'éligibilité, l'éco-organisme et le montant du soutien pour un type de produit donné, en fonction du symptôme ou du code réparation fourni. Cette API n'a pour seul but que de simuler la demande de soutien.

Elle n'effectue aucune demande réelle auprès d'Ecologic.

Données à transmettre

exemple

Bloc de code

language	json

{
    "TotalAmountExclVAT": 120.00,
    "TotalAmountExclVAT_Currency": "EUR",
    "BrandId": 8055,
    "ProductId": 3032,
    "IRISSymtom": "001" 
 }

données en entrée

TotalAmountExclVAT : Montant total HT de la réparation
TotalAmountExclVAT_Currency : Devise
BrandId: Code de la marque (retourné préalablement par l'API /PrintBrandList)
ProductId : Code du type de produit (retourné préalablement par l'API /PrintProductTypeList)
RepairCode : Liste des codes réparation éligibles pour le type de produits et pour Ecosystem
IRISSymptom : Liste des codes symptome IRIS éligibles pour le type de produits et pour Ecologic

données en sortie

EcoOrganizationId: Identifiant AgoraPlus de l'éco-organisme (44=Ecologic, 45=Ecosystem)
SupportAmount: Montant TTC du soutien

example de réponse

Bloc de code

language	json

{
 "ResponseData": [
    {
      "EcoOrganizationId": 44,
      "SupportAmount": {
        "Amount": "50.00",
        "Currency": "EUR"
      }
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

Effectuer la demande de soutien - /CreateSupportRequest
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/CreateSupportRequest

URL Prod = https://apiecologic.e-reparateur.eco/CreateSupportRequest

Fonctions

permet de soumettre la demande de soutien en vu d'obtenir la vérification du consommateur. Bien que non obligatoire pour Ecosystem, nous avons souhaité harmoniser le process pour faciliter l'implémentation.

Remarque
Cette étape est donc obligatoire, car l'Id de la demande sera demandé lors de la demande de remboursement.

Données à transmettre

exemple

Bloc de code

language	json

{
  "Consumer": {
    "Title": 1,
    "LastName": "Doe",
    "FirstName": "John",
    "StreetNumber": "121",
    "Address1": "Allée des roses",
    "Address2": "",
    "Address3": "",
    "Zip": "75010",
    "City": "Paris",
    "Country": "250",
    "Phone": "",
    "Email": "john.doe@agoraplus.com"
  },
  "Product": {
    "ProductId": "3065",
    "BrandId": "5098",
    "CommercialRef": "AR8395C",
    "SerialNumber": "4546545445646",
    "PurchaseDate": "2016-04-13",
    "IRISCondition": "6",
    "IRISConditionEX": "X47",
    "IRISSymptom": "A53",
    "IRISSection": "W10",
    "IRISDefault": "Q",
    "IRISRepair": "A",
    "FailureDescription": "formation de mousse",
    "DefectCode": ""
  },
  "Quote": {
    "LaborCost": {
      "Amount": 70.00,
      "Currency": "EUR"
    },
    "SparePartsCost": {
      "Amount": 180.00,
      "Currency": "EUR"
    },
    "TravelCost": {
      "Amount": 0.00,
      "Currency": "EUR"
    },
    "TotalAmountExclVAT": {
      "Amount": 208.34,
      "Currency": "EUR"
    },
    "TotalAmountInclVAT": {
      "Amount": 250.00,
      "Currency": "EUR"
    },
    "SupportAmount": {
      "Amount": 50.00,
      "Currency": "EUR"
    }
  },
  "SpareParts": [
    {
      "Partref": "407142415/6",
      "Quantity": 1,
      "Status": "New"
    }
  ]
}

données en entrée

Dans les paramètres

CallDate= date de référence de l’appel à l’API
RepairSiteId= ID de votre compte e-reparateur.eco
QuoteNumber= numéro du devis

Dans le body

Title -> 1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Société
Country: 250 pour la France (List of ISO 3166 country codes - Wikipedia )

données en sortie

RequestId: Identifiant de la demande de soutien

example de réponse

Bloc de code

language	json

{
  "ResponseData": {
    "EcoOrganizationId": 44,
    "RequestId": 1564,
    "IsValid": true,
    "ErrorMessage": ""
  },
  "ResponseStatus": "",
  "IsValid": true,
  "ResponseMessage": "",
  "ResponseErrorMessage": ""
}

Suivre le statut de la demande de soutien - /GetSupportRequestStatus
État
colour Green
title GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/GetSupportRequestStatus

URL Prod = https://apiecologic.e-reparateur.eco/GetSupportRequestStatus

Fonctions

permet de savoir si le consommateur a donné sa validation pour une demande de soutien donnée.

données en entrée

Dans les paramètres

RequestId = Id de votre dossier issu de la réponse à CreateSupportRequest
Ex : /GetSupportRequestStatus?RequestId=1564

données en sortie

LastStatus: Dernier statut de la demande de soutien
- Waiting: en attente,
- Accepted: Acceptée,
- Refused: Refusée
- …
  État
  colour Purple
  title TODO

example de réponse

Bloc de code

language	json

{
  "ResponseData": [
    {
      "RequestId": 1564,
      "LastStatus": "Waiting",
      "Comment": "",
      "CreateDate": "2022-06-24T15:16:22.110Z"
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

Gestion des demandes de remboursement

une fois le dossier de soutien accepté et validé par le consommateur, la demande de remboursement peut être créée et gérée.

Créer une demande de remboursement - /CreateClaim
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/CreateClaim

URL Prod = https://apiecologic.e-reparateur.eco/CreateClaim

Fonctions

permet d'effectuer la demande de remboursement.

En retour de cet appel, vous obtiendrez l'ID de votre demande de remboursement (ClaimId), qu'il vous faudra utiliser pour corriger les erreurs de validation, pour ajouter les pièces jointes requises et finalement soumettre votre demande.

Données à transmettre

exemple

Bloc de code

language	json

{
  "Consumer": {
    "Title": 1,
    "LastName": "Doe",
    "FirstName": "John",
    "StreetNumber": "121",
    "Address1": "Allée des roses",
    "Address2": "",
    "Address3": "",
    "Zip": "75010",
    "City": "Paris",
    "Country": "250",
    "Phone": "",
    "Email": "john.doe@agoraplus.com"
  },
  "Product": {
    "ProductId": "3065",
    "BrandId": "5098",
    "CommercialRef": "AR8395C",
    "SerialNumber": "4546545445646",
    "PurchaseDate": "2016-04-13",
    "IRISCondition": "6",
    "IRISConditionEX": "X47",
    "IRISSymptom": "A53",
    "IRISSection": "W10",
    "IRISDefault": "Q",
    "IRISRepair": "A",
    "FailureDescription": "formation de mousse",
    "DefectCode": ""
  },
  "Quote": {
    "LaborCost": {
      "Amount": 70.00,
      "Currency": "EUR"
    },
    "SparePartsCost": {
      "Amount": 180.00,
      "Currency": "EUR"
    },
    "TravelCost": {
      "Amount": 0,
      "Currency": "EUR"
    },
    "TotalAmountExclVAT": {
      "Amount": 208.34,
      "Currency": "EUR"
    },
    "TotalAmountInclVAT": {
      "Amount": 250,
      "Currency": "EUR"
    },
    "SupportAmount": {
      "Amount": 50.00,
      "Currency": "EUR"
    }
  },
  "SpareParts": [
    {
      "Partref": "407142415/6",
      "Quantity": 1,
      "Status": "New"
    }
  ]
}

données en entrée

Dans les paramètres
ex : /CreateClaim?RequestId=1564&RepairEndDate=2022-06-27T11:50:37.913Z&RepairSiteId=54654&ConsumerInvoiceNumber=132564

RequestId = date de référence du dossier de demande de soutien, issu de la réponse à CreateSupportRequest
RepairEndDate = Date de référence de la fin de réparation (ISO8601)
RepairSiteId = ID de votre compte e-reparateur.eco
ConsumerInvoiceNumber = numéro de référence de votre facture cliente

Dans le body

Remarque
Vérifiez bien la liste des champs obligatoires dans le Swagger et dans le fichier YAML ou JSON de l’API

données en sortie

ClaimId : Identifiant du dossier de remboursement

example de réponse

Bloc de code

language	json

{
  "ResponseData": {
    "ClaimId": 16466,
    "IsValid": false,
    "ValidationErrors": [
      {
        "Field": "Consumer.LastName",
        "ErrorMessage": "Mandatory",
        "MessageType": "E"
      },
	  {
        "Field": "Consumer.Email",
        "ErrorMessage": "Bad email format",
        "MessageType": "E"
      }
    ],
    "ErrorMessage": "Validation Errors"
  },
  "ResponseStatus": "S",
  "IsValid": true,
  "ResponseMessage": "",
  "ResponseErrorMessage": ""
}

Ajouter une pièce jointe à la demande de remboursement - /CreateClaim
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/CreateSupportRequest

URL Prod = https://apiecologic.e-reparateur.eco/CreateSupportRequest

Fonctions

permet d'ajouter un document à une demande de remboursement.

Un dossier de remboursement peut contenir plusieurs types de fichiers

Il existe 4 types de fichiers qui peuvent être joints à une demande :

Numéro de série: SerialNumber
Facture: Invoice
Photo: Picture
Bon de dépose: ClaimRequest

Info

Les pièces jointes obligatoires sont :

la facture,
1 photo minimum du produit,
la photo de la plaque signalétique.

Toute demande de remboursement qui ne disposerait pas de ces documents sera "non valide" et ne pourra être soumise.

Données à transmettre

exemple

Bloc de code

language	json

{
  "FileContent": "KJQFKJSQKJDKJQSJDKLFDSGDGDG5F4D65HG46G4D5FSG456FD4G4SG64FSDG5FD5G46DS5G456FD4G56FDSG654FDS56G4F6DG54FDS6G5FD6SG45FS4D6G4F56D4SG654S6G4F5D4G6S45FD4G45SFD4G65FD4SG65DF46S4"
 }

données en entrée

Dans les paramètres
ex : /AttachFile?ClaimId=16466&FileName=Facture797&FileExtension=pdf&DocumentType=Invoice

ClaimId = date de référence du dossier de demande de remboursement, issu de la réponse à CreateClaim
FileName = nom du fichier transmis
FileExtension = extension du fichier
- permet de définir le type
- extension sans le point “.”
DocumentType = type de document transmis à intégrer dans la demande

Dans le body

FileContent = contenu du fichier en Base64

données en sortie

aucune

Le statut de sortie est géré par le statut de la réponse HTTP

Code 200 -> OK
Code 400 -> Bad request
Code 500 -> Internal Error

Mettre à jour, corriger et soumettre la demande de remboursement - /UpdateClaim
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/UpdateClaim

URL Prod = https://apiecologic.e-reparateur.eco/UpdateClaim

Fonctions

permet de mettre à jour, de corriger et de soumettre la demande de remboursement. La mise à jour n'est plus possible après la soumission de la demande.

Données à transmettre

exemple

Bloc de code

language	json

{
  "Consumer": {
    "Title": 1,
    "LastName": "Doe",
    "FirstName": "John",
    "StreetNumber": "121",
    "Address1": "Allée des roses",
    "Address2": "",
    "Address3": "",
    "Zip": "75010",
    "City": "Paris",
    "Country": "250",
    "Phone": "",
    "Email": "john.doe@agoraplus.com"
  },
  "Product": {
    "ProductId": "3065",
    "BrandId": "5098",
    "CommercialRef": "AR8395C",
    "SerialNumber": "4546545445646",
    "PurchaseDate": "2016-04-13",
    "IRISCondition": "6",
    "IRISConditionEX": "X47",
    "IRISSymptom": "A53",
    "IRISSection": "W10",
    "IRISDefault": "Q",
    "IRISRepair": "A",
    "FailureDescription": "formation de mousse",
    "DefectCode": ""
  },
  "Quote": {
    "LaborCost": {
      "Amount": 70.00,
      "Currency": "EUR"
    },
    "SparePartsCost": {
      "Amount": 180.00,
      "Currency": "EUR"
    },
    "TravelCost": {
      "Amount": 0.00,
      "Currency": "EUR"
    },
    "TotalAmountExclVAT": {
      "Amount": 208.34,
      "Currency": "EUR"
    },
    "TotalAmountInclVAT": {
      "Amount": 250,
      "Currency": "EUR"
    },
    "SupportAmount": {
      "Amount": 50.00,
      "Currency": "EUR"
    }
  },
  "SpareParts": [
    {
      "Partref": "407142415/6",
      "Quantity": 1,
      "Status": "New"
    }
  ]
}

données en entrée

Dans les paramètres
ex : ClaimId=1564&RepairEndDate=2022-06-27T11:50:37.913Z&RepairSiteId=54654&Submit=false&ConsumerInvoiceNumber=132564

ClaimId = date de référence du dossier de demande de soutien, issu de la réponse à CreateSupportRequest
RepairEndDate = Date de référence de la fin de réparation (ISO8601)
RepairSiteId = ID de votre compte e-reparateur.eco
Submit = 💡 indique si la mise à jour déclenche ou non la soumission
ConsumerInvoiceNumber = numéro de référence de votre facture cliente

Dans le body

Remarque
Vérifiez bien la liste des champs obligatoires dans le Swagger et dans le fichier YAML ou JSON de l’API

données en sortie

ClaimId = Identifiant du dossier de remboursement
ErrorMessage = indique si des erreurs sont présentes dans la demande de remboursement empêchant la soumission
ValidationErrors = tableau des champs en erreur et information sur les erreurs
- Field = code du champ concerné
- ErrorMessage = erreur sur le champ concerné

example de réponse

Bloc de code

language	json

{
  "ResponseData": {
    "ClaimId": 16466,
    "IsValid": false,
    "ValidationErrors": [
      {
        "Field": "Consumer.LastName",
        "ErrorMessage": "Mandatory",
        "MessageType": "E"
      },
	  {
        "Field": "Consumer.Email",
        "ErrorMessage": "Bad email format",
        "MessageType": "E"
      }
    ],
    "ErrorMessage": "Validation Errors"
  },
  "ResponseStatus": "S",
  "IsValid": true,
  "ResponseMessage": "",
  "ResponseErrorMessage": ""
}

Suivre le statut de la demande de remboursement - /GetClaimStatus
État
colour Yellow
title POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/GetClaimStatus

URL Prod = https://apiecologic.e-reparateur.eco/GetClaimStatus

Fonctions

permet de connaitre le statut d'une demande de remboursement qui a été soumise.

Données à transmettre

exemple

/GetClaimStatus?ClaimId=16466

données en entrée

Dans les paramètres
ex : /GetClaimStatus?ClaimId=16466

ClaimId = date de référence du dossier de demande de soutien, issu de la réponse à CreateSupportRequest

données en sortie

LastStatus : Dernier statut de la demande de soutien
- Waiting: en attente,
- Accepted: Acceptée,
- Refused: Refusée,
- NotConform: Non conforme
- …
  État
  colour Purple
  title TODO

Info
Le statut "NotConform" indique qu'une action de correction est requise par Ecologic. Ce statut permet de visualiser la demande dans le champ "Comment" et de mettre à jour la demande de remboursement puis finalement de la soumettre à nouveau.

example de réponse

Bloc de code

language	json

{
  "ResponseData": [
    {
      "ClaimId": 16466,
      "LastStatus": "Waiting",
      "Comment": "",
      "CreateDate": "2022-06-24T15:16:22.110Z"
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

Version	Ancienne version 2	Nouvelle version 3
Modifications effectuées par	Sylvain Roberdeau	Sylvain Roberdeau
Sauvegardée le	janv. 25, 2023	janv. 25, 2023

Comparaison de pages

Comparaison des versions

Légende

Objectifs

Diagramme de séquence

Spécifications de l’API

Authentification

Récupération de votre clé d’authentification

Référentiels des données

Récupération de la liste des marques - /PrintBrandList ÉtatcolourGreentitleGET

Fonctions

usage

example de réponse

Récupérer la liste des types de produit - /PrintProductTypeList ÉtatcolourGreentitleGET

Fonctions

Example usage

example de réponse

Demandes de soutien

Calculer le montant du soutien - /CalculateEcoSupport ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

example de réponse

Effectuer la demande de soutien - /CreateSupportRequest ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

example de réponse

Suivre le statut de la demande de soutien - /GetSupportRequestStatus ÉtatcolourGreentitleGET

Fonctions

données en entrée

données en sortie

example de réponse

Gestion des demandes de remboursement

Créer une demande de remboursement - /CreateClaim ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

example de réponse

Ajouter une pièce jointe à la demande de remboursement - /CreateClaim ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

Mettre à jour, corriger et soumettre la demande de remboursement - /UpdateClaim ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

example de réponse

Suivre le statut de la demande de remboursement - /GetClaimStatus ÉtatcolourYellowtitlePOST

Fonctions

Données à transmettre

données en entrée

données en sortie

example de réponse

Récupération de la liste des marques - /PrintBrandList
État
colour Green
title GET

Récupérer la liste des types de produit - /PrintProductTypeList
État
colour Green
title GET

Calculer le montant du soutien - /CalculateEcoSupport
État
colour Yellow
title POST

Effectuer la demande de soutien - /CreateSupportRequest
État
colour Yellow
title POST

Suivre le statut de la demande de soutien - /GetSupportRequestStatus
État
colour Green
title GET

Créer une demande de remboursement - /CreateClaim
État
colour Yellow
title POST

Ajouter une pièce jointe à la demande de remboursement - /CreateClaim
État
colour Yellow
title POST

Mettre à jour, corriger et soumettre la demande de remboursement - /UpdateClaim
État
colour Yellow
title POST

Suivre le statut de la demande de remboursement - /GetClaimStatus
État
colour Yellow
title POST