Aller directement à la fin des métadonnées
Aller au début des métadonnées

Vous regardez une version antérieure (v. /wiki/spaces/FondsRepPublic/pages/3629121571/Guide+d+veloppeur+-+API+GesCo+Fonds+R+parations+EEE) de cette page.

afficher les différences afficher l'historique de la page

« Afficher la version précédente Vous regardez la version actuelle de cette page. (v. 21) afficher la version suivante »

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.

Version = 0.0

Historique des versions

  • VERSION 1.0 version initiale (à déployer)

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

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

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

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

Fonctions

permet de récupérer la liste des types de produits 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.

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/v3/ecosupport/calculateccosupport

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

  • IRISSymptom : Liste des codes symptôme IRIS éligibles pour le type de produits et pour Ecologic

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": 10.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 labélisation, 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
}

Fonctions

Permet de soumettre la demande de soutien en vue d'obtenir la vérification du consommateur.

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

Données à transmettre

exemple

{
  "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": true
},
  "Product": {
    "ProductId": "EEE.M5.024",
    "BrandId": "2194",
    "CommercialRef": "Repasse Plus",
    "SerialNumber": "ABCDE",
    "PurchaseDate": "2020-10-06",
    "IRISCondition": "",
    "IRISConditionEX": "",
    "IRISSymptom": "013",
    "IRISSection": "",
    "IRISDefault": "",
    "IRISRepair": "",
    "FailureDescription": "Symptome code IRIS 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

  • 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

il y a 3 sections importantes

  • Consumer : fourni

    • identité

      • Title -> 1 : Mrs. ; 2 : Ms. ; 3 : Mr. ; 4 : Société

    • adresse

    • téléphone = très important en cas de mode de vérification par SMS

    • email

  • Product : défini tous les paramètres du produit en réparation

    • ProductID = code du produit du référentiel

    • BrandID = code de la marque

    • SerialNumber = numéro de série

    • IRISSymptom = code IRIS de symptôme retenu associé au produit (doit correspondre à une entrée du référentiel retourné par PrintProductTypeList

    • FailureDescription = description des symptômes de la panne (ou de la panne)

  • Quote : défini les montants du devis associé à la demande

Données en sortie

  • RequestId: Identifiant de la demande de soutien
    Cet ID unique sera à fournir pour toute référence à la demande de soutien qui vient d'être créée.

Exemple de réponse

{
    "ResponseData": {
        "EcoOrganizationId": 44,
        "RequestId": 5310857,
        "IsValid": true
    },
    "ResponseStatus": "S",
    "IsValid": true,
    "ResponseMessage": "",
    "ResponseErrorMessage": ""
}

Gestion des modes SMS ou Offline

il est possible de déclencher une demande de soutien en utilisant 2 modes différents

  • mode SMS = le consommateur se verra envoyé un SMS avec un lien vers une page web lui permettant de valider la demande créée par le réparateur afin de s’assurer de la légitimité de la procédure en cours

  • mode Offline = le consommateur n’est pas sollicité par SMS. Cela permet de traiter les cas où ce dernier n’est pas en situation de traiter un SMS (téléphone en panne, manque de pratique…)
    Le consommateur doit alors signer un document qui devra être transmis avec la demande de remboursement.

si le mode Offline est utilisé, toute demande de remboursement à laquelle ne sera pas joint le document signé par le consommateur ne sera pas validable pour être traitée par Ecologic.

le mode Offline est déclenché en ajoutant le paramètre "AutoValidation": true dans la structure des informations pour "Consumer"

{
  "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": true
},

💡 Ne rien mettre ou mettre "AutoValidation": false sont équivalents

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

    • TODO

Exemple de réponse

{
  "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 POST

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

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

{
  "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@ecologic-france.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, 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

Dans le body

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

Exemple de réponse

{
  "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 - /AttachFile POST

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

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

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

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.

  • Éventuellement le bordereau de validation du conso peut-être exigé dans certains cas de figure.

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

  • 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 POST

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

URL Prod = https://apiecologic.e-reparateur.eco/api/v3/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": "Doe",
    "FirstName": "John",
    "StreetNumber": "121",
    "Address1": "Allée des roses",
    "Address2": "",
    "Address3": "",
    "Zip": "75010",
    "City": "Paris",
    "Country": "250",
    "Phone": "",
    "Email": "john.doe@a@ecologic-france.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

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é

Exemple de réponse

{
  "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": ""
}

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

    • TODO

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": [
    {
      "ClaimId": 16466,
      "LastStatus": "Waiting",
      "Comment": "",
      "CreateDate": "2022-06-24T15:16:22.110Z"
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

SwaggerUI (en rédaction)

Les éléments présentés ci-dessous ne sont pas fonctionnels et en cours de déploiement.

  • Aucune étiquette