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

Avril 2024

Nous attirons votre attention qu'à partir de début Avril 2024,

tous les codes pannes 2023 ne sont plus utilisables.
il n’est plus nécessaire de créer une demande de soutien (Request), vous pouvez créer directement une demande de remboursement (Claim)

Versions déployées de l’API GesCo Fonds Réparations EEE
- PreProd = 1.4
- Prod = 1.3 attention la version 1.4 n’est pas encore déployée en Production

Historique des versions

VERSION 1.4 prod 2 avr. 2024 / preprod 18 mars 2024
- Création d’un dossier Claims (Demande de remboursement) sans création préalable d’un dossier Request (Demande de soutien)
  Pendant encore quelques mois, les anciennes méthodes liées aux Requests (Demande de soutien) sont utilisables pour faciliter la transition
- calculateecosupport :
  - support de la date de réparation pour valider la période de prise en charge
VERSION 1.3 11 déc. 2023
- Création ou mise à jour de Request sans usage du SMS => mode unique autorisé
VERSION 1.2 19 juil. 2023
- calculateecosupport :
  - support des marques inconnues
  - détection des équipements pris en charge dans le cas d’une marque inconnue par Ecologic ou Eco System
- CreateSupportRequest
  - support des marques inconnues
- CreateClaim / UpdateClaim
  - support des marques inconnues
VERSION 1.1 8 mai 2023
- printproducttypewithlabellist : ajout d’une méthode permettant d’obtenir les codes symptomes et réparations avec leur intitulé afin de faciliter la présentation dans l’interface utilisateur
- calculateecosupport : prise en compte du paramètre RepairCode pour définir la prise en charge de la panne si elle est identifiée à cette étape
- submitclaim : ajout de cette méthode pour déclencher la soumission d’un dossier de remboursement en utilisant uniquement l’ID du dossier. L’usage de UpdateClaim avec le paramètre “submit=true” est toujours possible
- Code HTTP 206 pour les réponses aux méthodes Create et Update pour les Request (dossier de demande soutien) et Claim (dossier de demande de remboursement)
VERSION 1.01 8 mars 2023
- getsupportrequestStatus = affichage des erreurs encore présentes (comme pour CreateSupportRequest ou UpdateSupportRequest)
- getclaimstatus= affichage des erreurs encore présentes dans la demande de remboursement (comme pour CreateClaim ou UpdateClaim)
- PostMan = mise à jour de la collection
VERSION 1.0 version initiale 1 mars 2023

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

Le diagramme ci-contre, est une proposition de scénario de séquence des appels vers les méthodes de l’API.

La phase initiale consiste à récupérer les informations de référence devant être utilisée par l’application cliente.
Il est recommandé de consolider les référentiels au moins 1 fois par jour.

Une fois les informations sur le produit et l’estimation / devis pour la panne réalisée, la première étape est de s’assurer que la réparation va bien être prise en charge par Ecologic avec “CalculateEcoSupport”.

Si la réponse est positive vous avez le montant du soutien allouable à l’acte de réparation.

La demande de remboursement se crée avec “CreateClaim” et la réponse vous indique s’il vous manque des informations pour pouvoir la soumettre à la vérification (et alors si tout est OK, au paiement).

Généralement, il manque initialement les documents de type, facture, plaque de numéro de série…
Ces documents peuvent être intégrés à la demande de remboursement avec “AttachFile”.
Il est aussi possible de compléter la demande avec “UpdateClaim”.

Si la vérification est OK avec “GetClaimStatus”, vous pouvez faire un “SubmitClaim” en demandant la soumission du dossier.

Le dossier de remboursement passe ensuite dans les étapes de contrôle chez Ecologic.

Gestion des marques inconnues (ou dites Orphelines) VERSION 1.2

L’API comme l’interface Web permet de gérer les dossiers de demandes de soutien (Request) ou de demandes de remboursement (Claim) en définissant pour un équipement donnée une marque inconnue.

Le mécanisme est testable en ligne sur le site Label QualiRepar = https://www.label-qualirepar.fr/remboursement-bonus/

Ecologic ou EcoSystems

Une marque est dites inconnue à partir du moment où elle n’est pas listée dans la réponse à la méthode printbrandlist.
Exemple :

produit smartphone avec le code EEE.M2.044
marque “SUPERPhone”

Ce couple n’est pas listé et doit être traité comme une marque inconnue.

Lorsqu’un produit est associé à une marque inconnue, pour savoir si Ecologic est en charge de celui-ci, il faut interroger la méthode calculateecosupport. La réponse peut être négative, dans ce cas, il faut faire appel à l’API d’EcoSystems.

Marques inconnues pour les Requests et les Claims

Cette définition de la marque inconnue peut être aussi appelée pour les Request et les Claims.
Voir plus en détails les ajouts spécifiques pour ces méthodes.

Environnement de développement (Pre Production)

Lexique

Request = demande de soutien
Claim =demande de remboursement

Accéder à l’environnement de développement

Pré requis

Le développement n’a de sens que s’il s’adresse à un réparateur qui dispose d’un compte sur le service e-reparateur.eco (https://www.e-reparateur.eco )

Le développeur doit contacter le support afin de se faire identifier : support@e-reparateur.eco

Procédure

contacter le support support@e-reparateur.eco en demandant à avoir accès à un environnement de pré-production
si votre demande est acceptée vous recevrez par email en réponse
1. une clé API de Pré-Production pour réaliser votre développement
2. un compte d’accès au service web e-reparateur de Pre-Production sur lequel vous pourrez gérer, vérifier, mettre à jour les différents objets du service
vous pouvez contacter le support par email sur support@e-reparateur.eco

Récupération de votre clé de Pre Production

Outils de tests

Une fois que vous avez vos accès vous pouvez tester les premiers éléments (notamment votre clé API) avec les outils suivants

SwaggerUI

SwaggerUI de l’API de Pre Production = https://preprod-apiecologic.e-reparateur.eco/apidoc/ui/index#/

Requis = disposer de votre clé d’autorisation d’usage de l’API (voir ci-dessu)

une fois votre clé entrée vous pourrez tester les méthodes de l’API

PostMan

Les informations contenus dans les structures JSON et les paramètres POSTMAN peuvent contenir des paramètres liés aux produits, aux code symptomes, aux code pannes qui ne sont plus valides au moment où vous réaliserez vos tests.
Donc veiller à vérifier ces paramètres notamment à partir des informations récupérées avec les méthodes d’interrogations du référentiel.

Postman est un outil standard dans le développement et la validation des API Rest.
Nous vous mettons à disposition une collection préparée pour pouvoir tester toutes les méthodes, mais il est recommandé de bien lire les informations fournies pour chacune d’entre elles.

Pour utiliser la collection disponible ci-contre, vous avez juste à réaliser l’importation du fichier json depuis l’interface de Postman.

Ensuite il vous reste à définir votre clé API de Pre Production pour réaliser les appels avec le niveau d’autorisation du site associé.
Pour cela ouvrez l’arborescence de la collection et sélectionnez “Pre Prod” et l’onglet “Authorization” pour y intégrer votre clé API

surtout pensez à sauvegarder à chaque fois l’onglet, sinon l’information ne sera pas utilisable dans les autres onglets que vous allez ouvrir

Pour utiliser une méthode sélectionnez là dans l’arborescence et adaptez les valeurs pour les paramètres et le contenu pour le body selon votre contexte

Collection PostMan à importer

version du 25 mars 2024

La collection regroupe les méthodes dans des dossiers permettant de plus facilement identifier un ordre type d’usage de celles-ci.
Ce n’est qu’un exemple, il vous est possible d’organiser les appels aux méthodes différemment et de n’utiliser que celles que vous identifiez utiles.

Environnement de Production

Récupération de votre clé de Production

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> (GUID ex : C8E88146-AF8D-4E95-9B76-8C8FFF5A2C9B)

<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.eco.
Attention à ne pas la divulguer. Si jamais vous aviez un doute n’hésitez pas à prévenir le support = support@e-reparateur.eco

Vérification des sites

Récupération des informations du site associé à la clé API - /GetRepairSitesByATS GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/getrepairsitesbyats

Fonctions

Permet de récupérer les ID des sites associés à la clé API utilisée.
Ce sera l’information qu’il faudra ensuite utiliser dans certaines méthodes dans le paramètre “RepairSiteId”

Ex réponse

{
    "ResponseData": [
        {
            "SiteId": "02c867c0-0000-0000-000-3cf8de2dc1c8",
            "Name": "Test Reparateur",
            "CommercialName": "ECO REPARE",
            "Zip": "78280",
            "City": "GUYANCOURT"
        }
    ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Réponse avec plusieurs sites

{
    "ResponseData": [
        {
            "SiteId": "9cc23555-0000-0000-0000-3279c2f57261",
            "Name": "Test Reparateur 1",
            "CommercialName": "ECO REPARE",
            "Zip": "12100",
            "City": "MILLAU"
        },
        {
            "SiteId": "0590e586-0000-0000-0000-f94f4e1cb199",
            "Name": "Test Reparateur 1",
            "CommercialName": "ECO REPARE",
            "Zip": "12850",
            "City": "ONET-LE-CHATEAU"
        },
        {
            "SiteId": "b14ca037-0000-0000-0000-54a3391ee624",
            "Name": "Test Reparateur 1",
            "CommercialName": "ECO REPARE",
            "Zip": "12200",
            "City": "VILLEFRANCHE-DE-ROUERGUE"
        }
    ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

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).

Prod vs PreProd

attention les ID des entrées ne sont pas identiques entre les référentiels récupérés par l’API de Pre-Production et l’API de Production, donc veillez à bien récupérer ces référentiels pour chacun des contextes et à utiliser les bonnes valeurs associées.

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

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/printbrandlist

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/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

Exemple de réponse

{
    "ResponseData": [
        {
            "BrandName": "Acer",
            "BrandId": "1689"
        },
        {
            "BrandName": "ADVANCE",
            "BrandId": "1922"
        },
        {
            "BrandName": "AEG",
            "BrandId": "1690"
        },
        ...
  ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

🆕 Récupérer la liste des types de produit - /PrintProductTypeListWithLabelList GET VERSION 1.1

Cette méthode est à préférer par rapport à la méthode /PrintProductTypeList, car elle permet de récupérer les intitulés des codes de symptomes et de pannes.

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/printproducttypewithlabellist

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/printproducttypewithlabellist

Fonctions

Permet de récupérer la liste des équipements avec

code unique de l'équipement
nom de l'équipement
date d'éligibilité au soutien
date de fin du soutien
Tableau des codes pannes
Tableau des codes symtomes

Exemple usage

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

sortie =

ProductId = Identifiant produit

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 = Tableau d’une liste des codes pannes IRIS pouvant être utilisés dans la demande de remboursement (Claim) avec leur libellé

IRISSymptoms = Tableau d’une liste des codes symptôme IRIS éligibles pour le type de produits et pour Ecologic à utiliser dans la demande de soutien (Request) avec leur libellé

vérifiez la date d'éligibilité afin de vous assurer de ne pas soumettre un dossier avec ce produit avant que celle-ci ne soit valide.

Exemple de réponse

{
    "ResponseData": [
        {
            "ProductId": "EEE.M1.010",
            "ProductName": "Cave à vin",
            "EligibilityStartDate": "2022-01-01T00:00:00",
            "EligibilityEndDate": "9999-12-31T00:00:00",
            "RepairCodes": [
                {
                    "Code": "XXX",
                    "Label": "Autre"
                },
                {
                    "Code": "PSP",
                    "Label": "Défaut d'alimentation"
                },
                {
                    "Code": "G12",
                    "Label": "Défaut de carte de commande"
                },
                {
                    "Code": "G13",
                    "Label": "Défaut de carte de puissance"
                },
                {
                    "Code": "C05",
                    "Label": "Fuite de fluide frigorigène"
                },
                {
                    "Code": "C01",
                    "Label": "Problème compresseur"
                },
                {
                    "Code": "C10",
                    "Label": "Problème de thermostat"
                }
            ],
            "IRISSymtoms": [
                {
                    "Code": "XX4",
                    "Label": "Devient très buyant"
                },
                {
                    "Code": "XX6",
                    "Label": "N'affiche plus"
                },
                {
                    "Code": "XX12",
                    "Label": "Ne refroidit plus"
                },
                {
                    "Code": "XX13",
                    "Label": "Ne s'allume plus"
                },
                {
                    "Code": "XX1",
                    "Label": "Autre"
                },
                {
                    "Code": "XX23",
                    "Label": "Problème de bouton / connecteur"
                }
            ]
        },
        ...
  ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

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

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/printproducttypelist

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/printproducttypelist

Fonctions

Permet de récupérer la liste des équipements avec

code unique de l'équipement
nom de l'équipement
date d'éligibilité au soutien
date de fin du soutien
Tableau des codes pannes
Tableau des codes symtomes

.

Exemple usage

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

sortie =

ProductId = Identifiant produit

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 = Tableau des codes pannes IRIS pouvant être utilisés dans la demande de remboursement (Claim)

IRISSymptoms[] = Liste des codes symptôme IRIS éligibles pour le type de produits et pour Ecologic à utiliser dans la demande de soutien (Request)

vérifiez la date d'éligibilité afin de vous assurer de ne pas soumettre un dossier avec ce produit avant que celle-ci ne soit valide.

Exemple de réponse

{
    "ResponseData": [
        {
            "ProductId": "EEE.M1.010",
            "ProductName": "Cave à vin",
            "EligibilityStartDate": "2022-01-01T00:00:00",
            "EligibilityEndDate": "9999-12-31T00:00:00",
            "RepairCodes": [
                "XXX",
                "PSP",
                "G12",
                "G13",
                "C05",
                "C01",
                "C10",
                "SFT"
            ],
            "IRISSymtoms": [
                "004",
                "006",
                "012",
                "013",
                "001",
                "023"
            ]
        },
        ...
  ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Demandes de soutien

Plusieurs méthodes sont disponibles pour gérer la construction 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 GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/calculateccosupport

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/calculateccosupport

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 section 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

{
    "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)
au choix
- IRISSymptom : une des valeurs possibles du code symptome pour le produit issu du référentiel
- repairCode : une des valeurs possibles du code panne pour le produit issu du référentiel
optionnel VERSION 1.4
- repairEndDate : Date de référence de la fin de réparation (ISO8601)

le paramètre repairEndDate est intéressant à utliiser lorsque vous avez potentiellement des codes pannes qui arrivent en fin de validité afin de ne pas vous emmêler entre ceux valides à la date et ceux qui ne le seront plus.

Données en sortie

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

Exemple de paramètre en entrée

Exemple de réponse

{
    "ResponseData": [
        {
            "EcoOrganizationId": 44,
            "SupportAmount": 15.00
        }
    ],
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Gestion des erreurs

Si le produit ou la marque n’est pas connu vous aurez une réponse similaire à

{
    "ResponseData": null,
    "ResponseStatus": "W",
    "IsValid": false,
    "ResponseMessage": "Produit pas valide",
    "ResponseErrorMessage": null
}

Si le symptôme ne correspond pas au code IRIS du produit l’erreur sera

{
    "ResponseData": null,
    "ResponseStatus": "W",
    "IsValid": false,
    "ResponseMessage": "Symptôme pas valide",
    "ResponseErrorMessage": null
}

Si la fiche de compétence (ou fiche métier) associée au produit soumis, issue de la labellisation, n’est pas associée au site faisant la demande un refus sera retourné.

  {
    "ResponseData": null,
    "ResponseStatus": "W",
    "IsValid": false,
    "ResponseMessage": "Votre compte n'est pas autorisé à effectuer une demande de soutien pour ce type de produit.",
    "ResponseErrorMessage": null
}

Si la date de réparation repairEndDate ne correspond plus à la panne demandée

{
    "ResponseData": null,
    "ResponseStatus": "W",
    "IsValid": false,
    "ResponseMessage": "La panne sélectionnée n'est pas éligible pour ce type de produit.",
    "ResponseErrorMessage": null
}

Si le produit demandé n’existe pas

{
    "ResponseData": null,
    "ResponseStatus": "W",
    "IsValid": false,
    "ResponseMessage": "Invalid product",
    "ResponseErrorMessage": null
}

CalculateEcoSupport - Usage des marques inconnues VERSION 1.2

le mode marque inconnue est utilisable en utilisant les paramètres

BrandId = 0 (ce qui force le mode marque inconnue)
BrandName = nom_de_la_marque (champ qui devient obligatoire si BrandId = 0)

Ce qui donne par exemple les paramètres suivants

Si jamais le produit n’est pas pris en charge pour une marque inconnue par Ecologic, la réponse indique une erreur "ResponseMessage": "Invalid organization"

exemple

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 POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/createclaim

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/createclaim

Fonctions

Permet d'effectuer la demande de remboursement (Claim) en convertissant une demande de soutien (Request)

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.

Informations du consommateur obligatoires

Données	Champs	Remarque
Civilité	Title	1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Société
Nom	LastName
Prénom	FirstName
Code postal	Zip
Ville	City
E-mail	Email
N° de téléphone	Phone
Pays	Country	code 250 pour la France ISO 3166

Informations du Produit obligatoires

Données	Champs	Remarque
Marque	BrandId	issu du référentiel
Type de produit	ProductId	issu du référentiel
Code Panne	IRISSection	issu du référentiel

Informations du Produit facultatives

Données	Champs	Remarque
Référence commerciale	CommercialRef
N° de série / ID	SerialNumber	attention champ obligatoire si produit lié à la Fiche métier 7 EI&T

Données en entrée

Dans les paramètres
ex : /createclaim?repairEndDate=2024-03-25T09:00:00Z&repairSiteId=02c867c0-3cef-454d-9a04-3cf8de2dc1c8&consumerInvoiceNumber=FACT_20240325-1&quoteNumber=REF_INT_20240325-1

RequestId = date de référence du dossier de demande de soutien, issue 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
quoteNumber OPTIONNEL = numéro de référence interne chez le réparateur

Dans le body

Vérifiez bien la liste des champs obligatoires dans le Swagger évoqué au début du document.
C’est la source la plus sûr pour la structure des données à transmettre dans les méthodes.

IRISSection = il faut intégrer le code panne IRIS parmi ceux associés au produit dans le référentiel

Données en sortie

IsValid : indique si la création du Claim s’est passée correctement. L’erreur est généralement liée à l’usage d’un mauvais RequestId
ResponseMessage / ResponseErrorMessage : indique la nature de l’erreur si la création du Claim n’est pas possible
ResponseData : informations liée au Claim qui vient d'être créé
- ClaimId : Identifiant du dossier de remboursement
- IsValid : indique si les données du dossier de remboursement sont complètes et valide (true ou false)
- ValidationErrors : tableau des erreurs détectées si IsValid = false

VERSION 1.1

Http Status

A la demande de plusieurs développeurs, l’API différencie dans le statut de réponse HTTP le fait que celle-ci le soit en réponse à une requête

avec toute les informations attendues = 200
avec des informations manquantes = 206

Exemple de réponse

{
    "ResponseData": {
        "ClaimId": 5338937,
        "IsValid": false,
        "ValidationErrors": [
            {
                "Field": "Plaque signalétique",
                "ErrorMessage": "Des pièces jointes sont requises : Plaque signalétique",
                "MessageType": "E"
            },
            {
                "Field": "Facture",
                "ErrorMessage": "Des pièces jointes sont requises : Facture",
                "MessageType": "E"
            },
            {
                "Field": "Panne ou code IRIS",
                "ErrorMessage": "Cette valeur est obligatoire",
                "MessageType": "E"
            },
            {
                "Field": "Validation manuelle du consommateur",
                "ErrorMessage": "Des pièces jointes sont requises : Validation manuscrite",
                "MessageType": "E"
            },
            {
                "Field": "Montant de remboursement / Soutien",
                "ErrorMessage": "Code panne non valide, demande de remboursement / soutien non valide",
                "MessageType": "E"
            },
            {
                "Field": "Numéro de série",
                "ErrorMessage": "Le numéro de série / IMEI saisi a déjà fait l’objet d’une demande de soutien. Merci de vérifier cet élément avant de soumettre votre dossier.",
                "MessageType": "W"
            }
        ]
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": null,
    "ResponseErrorMessage": null
}

exemple pour une prise en charge d’un fer à repasser

{
  "Consumer": {
    "Title": 1,
    "LastName": "Test_ECL_SR_LN 20240325-1",
    "FirstName": "Test_ECL_SR_FN",
    "StreetNumber": "15",
    "Address1": "Avenue du Centre",
    "Address2": "",
    "Address3": "",
    "Zip": "78280",
    "City": "GUYANCOURT",
    "Country": "250",
    "Phone": "0612112105",
    "Email": "dsi-lab-test@ecologic-france.com"  
},
  "Product": {
    "ProductId": "EEE.M5.024",
    "BrandId": "2194",
    "CommercialRef": "Repasse Plus bis",
    "SerialNumber": "ABCDE20",
    "PurchaseDate": "2020-10-06",
    "IRISCondition": "",
    "IRISConditionEX": "",
    "IRISSymptom": "",
    "IRISSection": "LOG",
    "IRISDefault": "",
    "IRISRepair": "",
    "FailureDescription": "Plus affichage",
    "DefectCode": ""  
},
  "Quote": {
    "LaborCost": {
      "Amount": 20.00,
      "Currency": "EUR"
    },
    "SparePartsCost": {
      "Amount": 10.00,
      "Currency": "EUR"
    },
    "TravelCost": {
      "Amount": 0.00,
      "Currency": "EUR"
    },
    "TotalAmountExclVAT": {
      "Amount": 100.00,
      "Currency": "EUR"
    },
    "TotalAmountInclVAT": {
      "Amount": 106.00,
      "Currency": "EUR"
    },
    "SupportAmount": {
      "Amount": 15.00,
      "Currency": "EUR"
    }
  },
  "SpareParts": [
    {
      "Partref": "",
      "Quantity": 0,
      "Status": ""
    }
  ]
}

Ajouter une pièce jointe à la demande de remboursement - /AttachFile POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/AttachFile

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/AttachFile

Fonctions

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

Formats supportés en entrée

jpg
jpeg
png
pdf

Un dossier de remboursement peut contenir plusieurs types de fichiers

Les types de fichiers qui peuvent être joints à une demande :

facture = INVOICE
plaque signalétique ou numéro d’identification = NAMEPLATE
photo de l’appareil = PRODUCTPICTURE
l'élément de preuve = CONSUMERVALIDATION

Les pièces jointes obligatoires sont :

la facture
l'élément de preuve
pour les produits liés à la Fiche Métier 7 EI&T = la photo du numéro d’identification

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

Données à transmettre

exemple

{
  "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 (sans l’extension)
FileExtension = extension du fichier (voir ci contre)
- permet de définir le type
- extension sans le point “.”
DocumentType = type de document transmis à intégrer dans la demande (voir les codes identifiants ci contre)

Dans le body

FileContent = contenu du fichier en Base64

pour test exemple d’encodeur Base64 en ligne

https://base64.guru/converter/encode/file

Données en sortie

"Code 200 -> OK"

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 la demande de remboursement - /UpdateClaim POST

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/updateclaim

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/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 (les données ci-dessous de l’exemple sont à mettre à jour; en effet des champs sont obsolètes)

{
  "Consumer": {
    "Title": 1,
    "LastName": "Test Nom",
    "FirstName": "Test prénom",
    "StreetNumber": "15",
    "Address1": "Avenue du Centre",
    "Address2": "",
    "Address3": "",
    "Zip": "78280",
    "City": "GUYANCOURT",
    "Country": "250",
    "Phone": "0600000000",
    "Email": "test@egmail.com",
    "AutoValidation": false  
},
  "Product": {
    "ProductId": "EEE.M5.024",
    "BrandId": "2194",
    "CommercialRef": "Repasse Plus",
    "SerialNumber": "ABCDE",
    "PurchaseDate": "2020-10-06",
    "IRISCondition": "",
    "IRISConditionEX": "",
    "IRISSymptom": "",
    "IRISSection": "G18",
    "IRISDefault": "",
    "IRISRepair": "",
    "FailureDescription": "Code IRIS Symptome 013",
    "DefectCode": ""  
},
  "Quote": {
    "LaborCost": {
      "Amount": 20.00,
      "Currency": "EUR"
    },
    "SparePartsCost": {
      "Amount": 10.00,
      "Currency": "EUR"
    },
    "TravelCost": {
      "Amount": 0.00,
      "Currency": "EUR"
    },
    "TotalAmountExclVAT": {
      "Amount": 100.00,
      "Currency": "EUR"
    },
    "TotalAmountInclVAT": {
      "Amount": 106.00,
      "Currency": "EUR"
    },
    "SupportAmount": {
      "Amount": 10.00,
      "Currency": "EUR"
    }
  },
  "SpareParts": [
    {
      "Partref": "",
      "Quantity": 0,
      "Status": ""
    }
  ]
}

Données en entrée

Dans les paramètres
ex : /UpdateClaim?ClaimId=5310865&repairEndDate=2023-02-24T11:00:00Z&RepairSiteId=02c867c0-3cef-454d-9a04-3cf8de2dc1c8&consumerInvoiceNumber=FACT_20230301-1&quoteNumber=REF_INT_20230301-1&Submit=false

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
ConsumerInvoiceNumber = numéro de référence de votre facture cliente
quoteNumber OPTIONNEL = numéro de référence interne chez le réparateur

VERSION 1.1 Le paramètre suivant reste fonctionnel et peut être utilisé, mais il peut être plus pratique d’utiliser la méthode /submitclaim pour déclencher la soumission

Submit = 💡 indique si la mise à jour déclenche ou non la soumission
- false = la mise à jour n’est pas suivi d’une tentative de soumission
- true = la mise à jour entraine une tentative de soumission

Dans le body

VVérifiez bien la liste des champs obligatoires dans le Swagger évoqué au début du document.
C’est la source la plus sûr pour la structure des données à transmettre dans les méthodes.

Données en sortie

ClaimId : Identifiant du dossier de remboursement en cours
IsValid : indique si le dossier de remboursement est valide (true ou false)
ValidationErrors : tableau des erreurs détectées si IsValid = false

VERSION 1.1

Http Status

A la demande de plusieurs développeurs, l’API différencie dans le statut de réponse HTTP le fait que celle-ci le soit en réponse à une requête

avec toute les informations attendues = 200
avec des informations manquantes = 206

Exemple de réponse

{
    "ResponseData": {
        "ClaimId": 5275562,
        "IsValid": false,
        "ValidationErrors": [
            {
                "Field": "Plaque signalétique",
                "ErrorMessage": "Des pièces jointes sont requises : Plaque signalétique",
                "MessageType": "E"
            },
            {
                "Field": "Facture",
                "ErrorMessage": "Des pièces jointes sont requises : Facture",
                "MessageType": "E"
            },
            {
                "Field": "Panne ou code IRIS",
                "ErrorMessage": "Cette valeur est obligatoire",
                "MessageType": "E"
            }
        ],
        "ErrorMessage": "Validation Errors"
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Si la soumission est OK

{
    "ResponseData": {
        "ClaimId": 5310865,
        "IsValid": true
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Facture non conforme à la soumission

Exemple de facture non liée à l’utilisateur

{
    "ResponseData": {
        "ClaimId": 5310865,
        "IsValid": false,
        "ValidationErrors": [
            {
                "Field": "OCR facture",
                "ErrorMessage": "La facture n'est pas conforme (Nom du consommateur)",
                "MessageType": "E"
            }
        ],
        "ErrorMessage": "Validation Errors"
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Suivre le statut de la demande de remboursement - /GetClaimStatus GET

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/getclaimstatus

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/getclaimstatus

Fonctions

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

Données à transmettre

Exemple

/GetClaimStatus?ClaimId=5312276

Données en entrée

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

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

Données en sortie

ValidationErrors : liste des erreurs encore présentes dans le dossier empêchant sa soumission
LastStatus : Dernier statut de la demande de soutien
- “Dossier incomplet” : des pièces ou des informations doivent être ajoutées au dossier de demande de remboursement (Claim) avant de tenter de le soumettre

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.

Exemple de réponse

{
    "ResponseData": {
        "ValidationErrors": [
            {
                "Field": "Plaque signalétique",
                "ErrorMessage": "Des pièces jointes sont requises : Plaque signalétique",
                "MessageType": "E"
            },
            {
                "Field": "Facture",
                "ErrorMessage": "Des pièces jointes sont requises : Facture",
                "MessageType": "E"
            },
            {
                "Field": "Validation manuelle du consommateur",
                "ErrorMessage": "Des pièces jointes sont requises : Validation manuscrite",
                "MessageType": "E"
            },
            {
                "Field": "Montant de remboursement / Soutien",
                "ErrorMessage": "Le seuil n'est pas dépassé, demande de remboursement / soutien non valide",
                "MessageType": "E"
            },
            {
                "Field": "Numéro de série",
                "ErrorMessage": "Une réparation a déjà été effectuée il y a moins de 6 mois sur cet appareil. Cette réparation est donc couverte par votre garantie.",
                "MessageType": "E"
            }
        ],
        "ClaimId": 5312276,
        "LastStatus": "Dossier incomplet",
        "Comment": "Code IRIS Symptome 013",
        "CreateDate": "2023-05-05T15:15:50.953"
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

🆕 Soumettre la demande de remboursement - /submitclaim POST VERSION 1.1

URL Preprod = https://preprod-apiecologic.e-reparateur.eco/api/v1/ecosupport/submitclaim

URL Prod = https://apiecologic.e-reparateur.eco/api/v1/ecosupport/submitclaim

Fonctions

Permet de soumettre simplement un dossier

Données à transmettre

Exemple

/submitclaim?claimId=5275562

Données en entrée

Dans les paramètres
ex : /submitclaim?claimId=5275562

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

Données en sortie

ResponseData : détails sur le traitement
- IsValid : indique si la soumission a été validée
- ValidationErrors : liste des erreurs encore présentes dans le dossier empêchant sa soumission

Exemple de réponse

si la soumission contient des erreurs :

{
    "ResponseData": {
        "ClaimId": 5312276,
        "LastStatus": "Dossier incomplet",
        "Comment": "Code IRIS Symptome 013",
        "CreateDate": "2023-05-05T15:15:50.953"
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Si la soumission est OK

{
    "ResponseData": {
        "ClaimId": 5310865,
        "IsValid": true
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Guide développeur - API GesCo Fonds Réparations EEE

Historique des versions

Objectifs

Diagramme de séquence

Gestion des marques inconnues (ou dites Orphelines) VERSION 1.2

Ecologic ou EcoSystems

Marques inconnues pour les Requests et les Claims

Environnement de développement (Pre Production)

Lexique

Accéder à l’environnement de développement

Pré requis

Procédure

Récupération de votre clé de Pre Production

Outils de tests

SwaggerUI

PostMan

Environnement de Production

Récupération de votre clé de Production

Spécifications de l’API

Authentification

Vérification des sites

Récupération des informations du site associé à la clé API - /GetRepairSitesByATS GET

Fonctions

Référentiels des données

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

Fonctions

Usage

Exemple de réponse

🆕 Récupérer la liste des types de produit - /PrintProductTypeListWithLabelList GET VERSION 1.1

Fonctions

Exemple usage

Exemple de réponse

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

Fonctions

Exemple usage

Exemple de réponse

Demandes de soutien

Calculer le montant du soutien - /CalculateEcoSupport GET

Fonctions

Données à transmettre

Données en entrée

Données en sortie

Exemple de réponse

Gestion des erreurs

CalculateEcoSupport - Usage des marques inconnues VERSION 1.2

Gestion des demandes de remboursement

Créer une demande de remboursement - /CreateClaim POST

Fonctions

Informations du consommateur obligatoires

Informations du Produit obligatoires

Informations du Produit facultatives

Données en entrée

Données en sortie

Exemple de réponse

Ajouter une pièce jointe à la demande de remboursement - /AttachFile POST

Fonctions

Données à transmettre

Données en entrée

Données en sortie

Mettre à jour, corriger la demande de remboursement - /UpdateClaim POST

Fonctions

Données à transmettre

Données en entrée

Données en sortie

Exemple de réponse

Facture non conforme à la soumission

Suivre le statut de la demande de remboursement - /GetClaimStatus GET

Fonctions

Données à transmettre

Données en entrée

Données en sortie

Exemple de réponse

🆕 Soumettre la demande de remboursement - /submitclaim POST VERSION 1.1

Fonctions

Données à transmettre

Données en entrée

Données en sortie

Exemple de réponse