Informations techniques
Cette section présente des informations techniques de base sur les API DCP pour vous aider à démarrer votre développement.
Environnements
Il existe deux environnements disponibles pour appeler les API DCP : test et production.
L'URL de base sélectionne l'environnement pour appeler une API DCP.
Test | https://qa-cloud-api.brp.com/dcp |
|---|---|
Production | https://cloud-api.brp.com/dcp |
Informations importantes :
- Les deux environnements utilisent des ensembles de credentials différents
- L'environnement de test a parfois des données limitées ou anciennes, mais cela n'affecte pas le comportement de l'API.
- L'environnement de production ne doit être utilisé que pour la phase pilote du concessionnaire de certification et une fois que l'API est certifiée.
Une fois que vous avez vos credentials, l'environnement de test peut être utilisé pendant vos activités de développement pour valider l'intégration de l'API DCP dans votre DSP.
L'environnement de test est également utilisé pendant les activités de certification décrites dans le Processus de Certification section.
Informations Générales
Cette section présente des informations générales sur les API DCP.
Format de charge utile de requête
Toutes les API DCP utilisent une charge utile JSON pour les requêtes et les réponses.
Lors de l'appel d'une API DCP pour envoyer des données au BRP, la charge utile reçue par l'API DCP est validée par rapport à une Spécification OpenAPI (OAS).
Si la charge utile reçue par l'API DCP ne correspond pas à l'OAS, l'API DCP renvoie une erreur 400 Bad Request.
Lors de l'appel d'une API DCP pour envoyer des données au BRP, la charge utile reçue par l'API DCP est validée par rapport à une Spécification OpenAPI (OAS).
Si la charge utile reçue par l'API DCP ne correspond pas à l'OAS, l'API DCP renvoie une erreur 400 Bad Request.
La propriété de l'objet JSON en erreur est fournie dans la charge utile de réponse d'erreur.
Par exemple, si la charge utile contient une propriété de date et que le format de date est invalide, la réponse d'erreur suivante est reçue.
{
"status": 400,
"id": "rrt-07783bca845d5f9ca-d-ea-4205-62358060-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "[Path '/date_of_repair'] String \"20223-01-10T14:10:09Z\" is invalid against requested date format(s) [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,12}Z]: []"
}
]
}
}
}Cette erreur est généralement observée lors de l'intégration de l'API DCP dans le DSP et est constatée lors des phases de tests et de certification.
Format de la charge utile de réponse
La charge utile de réponse renvoyée par les API DCP est généralement préparée à l'aide des données reçues des systèmes backend. Dans certains cas, une correspondance est effectuée entre la valeur renvoyée par le backend et la valeur renvoyée dans la charge utile de réponse.
Il peut arriver que les valeurs d'un champ dans la charge utile de réponse ne soient pas disponibles, par exemple, si une valeur renvoyée par le backend est manquante dans la correspondance des champs.
Cette situation est gérée en utilisant les règles suivantes.
- Tous les champs sont toujours présents dans la charge utile.
- Si le champ est un chaîne et qu'il n'y a pas de valeur à renvoyer, le champ est défini sur une chaîne vide (“”).
- Si aucune valeur n'est renvoyée pour tous les autres types de champs, le champ est défini sur la null valeur. Par exemple, si un champ est un nombre ou une date et que la valeur est manquante, la null valeur est renvoyée
- Si le champ est un tableau sans valeur à renvoyer, la charge utile contient un tableau vide. Par exemple : "pricings": [ ]
Chemin : Singulier contre Pluriel
Les chemins de l'API DCP utilisent la convention singulier/pluriel.
- Lorsque le point de terminaison fonctionne sur un seul objet, le chemin utilise le singulier.
- Par exemple, le chemin est comme ceci lors de l'appel à l'Parts API pour rechercher une pièce
- Le pluriel est utilisé lorsque le point de terminaison fonctionne sur une collection d'objets.
- Par exemple, lors de l'appel à l'Parts API pour obtenir tous les changements depuis une date spécifique, le chemin est comme ceci :
Assurez-vous de vérifier le chemin du point de terminaison de l'API dans le Catalogue API.
Séparateur décimal
Tous les champs numériques avec des décimales utilisent le point (.) comme séparateur décimal. La virgule (,) n'est PAS prise en charge comme séparateur décimal.
Pagination
Certaines API DCP renvoient une liste d'objets. Par exemple, l'API des pièces renvoie un catalogue de pièces, et l'API de commande de pièces Obtenir le service peut renvoyer une liste de commandes de pièces.
Dans ce cas, les données sont trop volumineuses pour être renvoyées dans une seule charge utile de réponse, donc la pagination est utilisée pour diviser la réponse en plusieurs charges utiles.
Un mécanisme est fourni pour que l'appelant puisse naviguer entre les pages. La réponse contient la liens propriété, qui contient les précédent et suivant propriétés pour naviguer entre les pages.
,
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/parts?language=en-US&last_changed_date=1900-01-01&sales_org=3020¤cy=USD&limit=200&page=2"
}Si précédent est nul, vous êtes à la première page.
Si suivant est nul, vous êtes à la dernière page.
Certaines API renvoient également une méta propriété qui fournit des informations sur la quantité de données renvoyées, le nombre de pages, etc.
"meta": {
"total_records": 72062,
"total_pages": 361,
"current_page": 1,
"limit": 200
}Catalogue API
Les références techniques de l'API DCP sont disponibles dans la Catalogue API section.
Pour chaque API DCP, les sections suivantes fournissent toutes les informations nécessaires sur l'API.
- Commencer : une introduction à l'API, y compris le contexte technique et commercial.
- Informations techniques : authentification, résumé des ressources, limites et contraintes, etc.
- La référence API : les services disponibles avec leurs paramètres, charge utile, etc.
- Comment faire : exemples d'utilisation de l'API DCP pour accomplir une fonction.
- Gestion des erreurs : informations sur la manière de gérer les erreurs les plus courantes.
- Exigences DSP : exigences obligatoires et facultatives sur la manière d'implémenter une fonction en utilisant l'API DCP. Cela contient également les activités de certification.
- Postman : une description des ressources disponibles pour valider l'intégration de l'API DCP en utilisant Postman.
Caractéristiques de l'API
La section Caractéristiques de chaque API Démarrer section présente les caractéristiques générales de l'API, comme indiqué ci-dessous.
Les deux caractéristiques les plus importantes sont :
- Type DSP : indique si un DMS, un CRM, ou les deux utilisent l'API DCP.
- Version DCP : indique quelles versions DCP de l'API sont compatibles.
Type d'API | Type de DSP | Version DCP | Complexité |
|---|---|---|---|
Obtenez des données du BRP | Système de gestion de documents | V3 - International | Faible |
Envoyer des données au BRP | CRM | V4 - Amérique du Nord | Un peu plus |
Transaction avec BRP | | | Un peu plus |
Version DCP
Pour la plupart des API DCP, vous ne verrez pas de différences dans la charge utile et les appels entre les versions 3 et 4. Pour ces API DCP, les différences se trouvent dans les systèmes backend, c'est pourquoi les versions de l'API sont documentées dans la même section. La Caractéristiques section de la Premiers Pas section indique quelles versions DCP de l'API sont compatibles.
S'il y a des différences dans la charge utile et/ou les appels entre les versions DCP pour une API DCP, les différentes versions sont documentées dans des sections spécifiques du Catalogue API.
Par exemple, l'API de commande de pièces pourrait avoir une charge utile légèrement différente entre les V3 - International et V4 - Amérique du Nord versions.
Dans ce cas, il y aurait deux sections dans le Catalogue API:
- API de commande de pièces V3
- API de commande de pièces V4
Exigences DSP
L'équipe DCP peut définir des exigences fonctionnelles pour votre DSP afin de s'assurer que l'intégration de l'API DCP répond aux objectifs commerciaux.
Il existe deux types d'exigences fonctionnelles qui peuvent être définies : obligatoires et optionnelles.
Exigences Obligatoires
Une exigence obligatoire est une exigence fonctionnelle qui doit être mise en œuvre par votre DSP.
La mise en œuvre de l'exigence est validée et vérifiée lors du processus de certification.
Si une exigence obligatoire n'est pas correctement mise en œuvre, l'API DCP ne peut pas être certifiée.
Un exemple d'exigence obligatoire est qu'une API DCP doit être appelée automatiquement chaque jour pour récupérer la dernière mise à jour du catalogue de pièces.
Exigence Optionnelle
Une exigence optionnelle est une exigence fonctionnelle que l'équipe DCP vous suggère fortement de mettre en œuvre dans votre DSP.
Ces exigences ajoutent de la valeur commerciale à l'intégration de l'API DCP dans le DSP. Cependant, l'équipe DCP est consciente que le DSP peut avoir des limitations qui empêchent la mise en œuvre de ces exigences, c'est pourquoi elles sont optionnelles.
Postman
La plupart des informations techniques des API DCP incluent un ensemble d'objets Postman : environnement et collections.
Pour utiliser ces objets, vous devez les exporter depuis l'espace de travail Postman partagé et les importer dans votre environnement d'équipe Postman.
Avant d'utiliser les collections et la requête, vous devez changer les variables d'environnement pour utiliser vos informations.
Vous devez changer toutes les valeurs qui commencent par "YOUR_"
Aperçu de la gestion des erreurs
La gestion des erreurs est un aspect important des API DCP. Les DSP utilisant les API DCP doivent mettre en œuvre une gestion des erreurs solide pour fournir au concessionnaire des informations significatives.
Le catalogue API fournit la liste des codes d'état spécifiques qui peuvent être renvoyés par une API et les étapes à suivre lorsque le code d'état est reçu.
Codes d'état de réponse
Les API DCP utilisent la plage de codes d'état standard RFC 9110 :
- 2xx (Réussi) : La demande a été reçue, comprise et acceptée avec succès
- 4xx (Erreur Client) : La demande contient une mauvaise syntaxe ou ne peut pas être satisfaite
- 5xx (Erreur Serveur) : Le serveur n'a pas réussi à satisfaire une demande apparemment valide
Les API DCP renvoient les codes d'état suivants.
Code d'état | Description |
|---|---|
200 OK | Indique que la demande a réussi. Le contenu envoyé dans une réponse 200 dépend de la méthode de demande. |
400 Mauvaise Demande | Indique que le serveur ne peut pas ou ne veut pas traiter la demande en raison de quelque chose qui est perçu comme une erreur du client (par exemple, une syntaxe de demande malformée, un encadrement de message de demande invalide ou un routage de demande trompeur). IMPORTANT: le Charge utile de réponse indique les champs de charge utile de la requête ou les paramètres de requête en erreur. S'il y a de nombreux champs ou paramètres invalides, tous doivent être listés. |
401 Non autorisé | Indique que la demande n'a pas été appliquée car elle manque de justificatifs d'authentification valides. |
403 Interdit | Indique que le serveur a compris la demande mais a refusé de l'exécuter. Par exemple, la méthode PUT peut être utilisée pour mettre à jour un objet qui ne peut pas être mis à jour. |
404 Non Trouvé | Indique que le serveur n'a pas trouvé les objets demandés. |
413 Contenu trop volumineux | Indique que le serveur refuse de traiter une demande parce que le contenu demandé est plus grand que ce que le serveur est disposé ou capable de traiter. |
Erreur interne du serveur 500 | Indique que le serveur est conscient qu'il a commis une erreur ou qu'il est incapable d'exécuter la méthode demandée. |
502 Mauvaise passerelle | Indique que l'API a reçu une réponse invalide d'un serveur en amont auquel elle a accédé en essayant de satisfaire la demande. |
Erreur 504 : Délai d'attente de la passerelle | Cela indique que l'API n'a pas reçu de réponse en temps voulu d'un serveur en amont qu'elle devait accéder pour compléter la demande. |
La section Comment Gérer les Erreurs fournit une gestion des erreurs générique pour chaque code d'état utilisé 4xx et 5xx. Les spécifications détaillées de l'API DCP dans le Catalogue API fournit une gestion des erreurs spécifique à chaque code d'état.
Charge utile de réponse
Pour la plage de codes d'état d'erreur 4xx et 5xx, une charge utile de réponse est renvoyée pour fournir des informations sur l'erreur. La charge utile de réponse utilise une structure basée sur le spécification JSON API pour les erreurs spécifications, comme indiqué dans le tableau ci-dessous.
❗❗ Le code d'état 504 Gateway Timeout renvoie une charge utile de réponse de base puisque l'API DCP ne peut pas intercepter l'erreur ❗❗
{ "fault": { "faultstring": "Délai d'attente de la passerelle", "detail": { "errorcode": "messaging.adaptors.http.flow.GatewayTimeout" } } }
Propriété | Type | Définition |
|---|---|---|
statut | chaîne | Le code d'état HTTP applicable à ce problème est exprimé sous forme de valeur chaîne. |
id | chaîne | Une chaîne unique qui identifie la demande, générée par Apigee |
titre | chaîne | Code qui identifie l'erreur ou la phrase de raison Un de
|
méta | objet | |
métadonnées.service | chaîne | Le code de service où l'erreur a été générée. C'est une référence interne de l'API DCP qui identifie l'API DCP. |
métadonnées.détail | chaîne | Détails sur la cause de l'erreur |
méta.poids | objet | La réponse brute du service qui cause l'erreur (facultatif) |
Par exemple, un appel à une méthode GET pour obtenir un numéro de concessionnaire inexistant renverrait la réponse suivante.
{
"status": "400",
"id": "rrt-05cc5cef09974c73d-d-ea-11235-10626775-11.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Backend error",
"payload": {
"status": 400,
"errors": [
{
"code": "Vintage",
"title": "PAA Order Validate (API/Method)",
"detail": "Please contact Vintage Parts. See bulletin 123981 or www.vpartsinc.com",
"meta": {
"product_code": "080037100",
"item_id": "2833e5ad-ff54-44c1-9058-af64c955faa9",
"message": "015 - Warning -Please contact Vintage Parts. See bulletin 123981 for item_id = 2833e5ad-ff54-44c1-9058-af64c955faa9 product_code = 080037100 (/BRP/PART_ORDER/062)"
}
}
]
}
}
}Comment gérer les erreurs
400 Mauvaise requête
Le code d'état 400 Mauvaise requête est principalement observé lors de l'intégration et des tests d'une API DCP.
Le code d'état est renvoyé lorsque quelque chose dans la requête est soit manquant, soit a une valeur invalide. Par exemple :
- Un paramètre de requête requis est manquant
- Un paramètre de requête a une valeur invalide
- Une propriété obligatoire du payload est manquante
- Une propriété du payload a une valeur invalide
Par exemple, si l'API DCP nécessite le numéro de concessionnaire dans le payload et que la propriété est manquante, ce qui suit est envoyé :
{
"status": 400,
"id": "rrt-06edc2039f6ce7033-b-ea-23590-61122983-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "Object has missing required properties ([\"dealer_no\"]): []"
}
]
}
}
}Si la propriété du numéro de concessionnaire contient une valeur invalide, ce qui suit est envoyé :
{
"status": 400,
"id": "rrt-0570f8640a6f6ee97-d-ea-31505-59966586-1.1",
"title": "not_found",
"meta": {
"service": "07",
"payload": {
"errors": "Dealer number 12345678 is invalid."
}
}
}Ces erreurs doivent être corrigées pendant les phases d'intégration et de test.
❗❗ Ne tentez pas de renvoyer la charge utile après un statut 400 à moins que vous ne puissiez corriger automatiquement le problème ❗❗
Si la même charge utile est envoyée sans modification, le même statut 400 sera retourné.
Cependant, si l'utilisateur DSP fournit une valeur de propriété ou une valeur de requête, l'erreur doit être convertie en quelque chose de significatif pour l'utilisateur.
Notez que pour de nombreuses API DCP, le code d'état 404 Non trouvé est retourné lorsqu'un objet n'est pas trouvé.
401 Non autorisé
C'est simple : vous avez appelé une API DCP avec un jeton d'accès incorrect ou expiré.
{
"status": 401,
"id": "rrt-0debaee1f7de5da53-c-ea-8481-2988956-1",
"title": "unauthorized",
"meta": {
"service": "05",
"detail": "Please verify your credentials or the Bearer token you provided. Contact the DCP team if you need further assistance."
}
}Pour résoudre cette erreur :
- Assurez-vous d'utiliser les bonnes informations d'identification définies pour l'environnement (test ou production)
- Assurez-vous que votre jeton d'accès est régulièrement actualisé.
Vérifiez la section Authentification et informations d’identification pour des informations sur les informations d'identification.
403 Interdit
Cette erreur se trouve généralement uniquement lors de l'intégration et des tests d'une API DCP.
Le 403 Interdit est renvoyé lorsque vous essayez d'appeler une API BRP interne directement sans passer par l'URL appropriée de l'API DCP.
{
"error": {
"id": "rrt-0b8f470f8a6f5fd93-d-ea-17530-62132303-1",
"status": 403,
"code": "Not Allowed",
"title": "Not Allowed to call the API from this origin"
}
}La solution à cette erreur est de mettre à jour l'URL que vous utilisez pour appeler l'API DCP.
404 Non trouvé
Une API DCP qui utilise un paramètre de requête pour trouver un objet, tel qu'un numéro de concessionnaire, un numéro de pièce ou un VIN, renvoie le statut 404 Non trouvé.
{
"status": 404,
"id": "rrt-06edc2039f6ce7033-b-ea-23589-61142930-1.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Product code 0126488 not found."
}
}En général, l'erreur doit être signalée à l'utilisateur DSP.
413 Contenu trop volumineux
Les API DCP sont déployées sur APIGee, qui a une limite de charge utile de 10 Mo. Si la charge utile que vous envoyez est supérieure à 10 Mo, vous recevrez le code d'état 413.
Le seul moyen de résoudre cette erreur est de s'assurer que la taille de la charge utile envoyée lors de l'intégration d'une API DCP est inférieure à 10 Mo en la divisant en plusieurs messages.
Notez que les API DCP les plus susceptibles de rencontrer cette erreur sont les API d'inventaire des pièces de concessionnaires et les API de données des transactions de vente au détail.
500 Erreur interne du serveur
Un système backend renvoie le statut d'erreur interne du serveur 500 pour de nombreuses raisons, donc aucun traitement spécifique n'est possible.
Si possible, la meilleure façon de gérer l'erreur est d'attendre un moment (30 à 60 secondes) et d'appeler à nouveau l'API DCP.
Cela fonctionnera généralement. Mais si cela ne fonctionne pas, vous pouvez réessayer plusieurs fois (3 à 5 fois).
Si cela ne fonctionne toujours pas après plusieurs tentatives, vous devez renvoyer un message d'erreur à l'utilisateur et contacter l'équipe DCP pour signaler l'erreur avec le plus d'informations possible. Voir la section Obtenir de l'aide pour des informations sur la façon de signaler des problèmes.
502 Mauvaise Passerelle
La 502 Mauvaise Passerelle peut se produire lorsque l'API DCP appelle une API interne BRP, qu'ils appellent un système backend.
Si possible, la meilleure façon de gérer l'erreur est d'attendre un moment (30 à 60 secondes) et d'appeler à nouveau l'API DCP.
Cela fonctionnera généralement. Mais si cela ne fonctionne pas, vous pouvez réessayer quelques fois (3 à 5 fois).
Si cela ne fonctionne toujours pas après de nombreux essais, vous devez renvoyer un message d'erreur à l'utilisateur et contacter l'équipe DCP pour signaler l'erreur avec autant d'informations que possible. Voir la section Obtenir de l'aide pour des informations sur la façon de signaler des problèmes.
504 Délai d'Attente de Passerelle
APIGee a un délai d'attente fixe de 55 secondes. Si le système backend met environ ±50 secondes à renvoyer une réponse, APIGee renvoie un code d'état 504 Délai d'Attente de Passerelle au DSP appelant.
Il existe deux façons générales de gérer cette erreur
Attendre et Réessayer
La charge du système backend peut provoquer le délai d'attente. Donc, attendez un moment (30 à 60 secondes) et appelez à nouveau l'API DCP.
Cela fonctionnera généralement. Mais si cela ne fonctionne pas, vous pouvez réessayer quelques fois (3 à 5 fois).
Si cela ne fonctionne toujours pas après de nombreuses tentatives, vous devez renvoyer un message d'erreur à l'utilisateur.
Attendre la Complétion
Pour les transactions DCP APIs, comme la Commande de Pièces, ne pas réessayer la transaction !
Le délai d'attente s'est produit car le système backend prend plus de ±50 secondes pour finaliser la transaction, mais la transaction est toujours en cours de traitement.
Les APIs de transaction DCP fournissent un service pour obtenir le statut de la transaction.
Attendez un moment (60 à 90 secondes) et appelez le service API DCP pour obtenir le statut de la transaction.
Si elle est toujours en cours de traitement, attendez à nouveau et appelez le service API DCP jusqu'à ce que la transaction soit terminée.
Pour être prudent, vous pouvez limiter le nombre de tentatives à 5 à 10 tentatives.