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. 20) 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": "string",
      "BrandId": "string"
    }
  ],
  "ResponseStatus": "string",
  "IsValid": true,
  "ResponseMessage": "string",
  "ResponseErrorMessage": "string"
}

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

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

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

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

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

Exemple de réponse

{
  "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 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 réponse

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

Effectuer la demande de soutien - /CreateSupportRequestPOST

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

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

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 demande de remboursement.

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

Données en sortie

  • RequestId: Identifiant de la demande de soutien

Exemple de réponse

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

Suivre le statut de la demande de soutien - /GetSupportRequestStatus GET

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

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

    • … 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": ""
}

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

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

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

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