API de garantie
Commencer
L’objectif de l’API de réclamation de garantie est d’améliorer l’expérience utilisateur pour la soumission des réclamations de garantie dans BOSSWeb. Le but est de réduire le temps requis et le nombre de saisies manuelles nécessaires pour remplir les formulaires en préremplissant la réclamation brouillon avec les informations provenant d’un ordre de réparation. Le concessionnaire se rend ensuite sur BOSSWeb pour compléter la réclamation.
Seules les réclamations de garantie de type brouillon peuvent être créées via l’API, ce qui correspond aux réclamations liées à des problèmes de véhicule couverts par une garantie.
Par où commencer ? Lisez ceci en premier !
Avant de commencer à travailler sur cette API, vous devez lire les sections suivantes si vous ne les avez pas déjà consultées :
- Informations techniques pour des informations techniques générales sur l’API et les environnements.
- Authentification et informations d’identification pour plus de détails sur l’authentification et les identifiants.
Informations Techniques
Caractéristiques
Type d'API | Type DSP | Version DCP | Complexité |
|---|---|---|---|
Obtenir des données de BRP | DMS | V3 - International | Faible |
Envoyer des données à BRP | CRM | V4 - Amérique du Nord | Un peu plus |
Transaction avec BRP | | | Quelque peu plus |
Authentification
L'API utilise Authentification de l'application.
Vous avez besoin d’un jeton d’accès valide avant d’appeler cette API ou vous devez appeler l’API d'authentification d'application pour en obtenir un.
Le jeton d’accès est valable pendant 30 minutes ! (1799 secondes)
URL de base
Test | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Production | https://cloud-api.brp.com/dcp/v4 |
Ressource : Réclamation
Cette ressource est utilisée pour travailler avec une réclamation de garantie.
Représentation JSON
{
"dealer_no": "0000694307",
"vin": "2BPSMBMB2MV000203",
"odometer": "1050.5",
"rro_creation_date": "2022-01-10T08:20:50Z",
"date_of_repair": "2022-01-10T14:10:09Z",
"causal_part": "415129449",
"system_code": "1-Engine",
"work_order_no": "4334-01",
"symptom_description": "The part broke. Customer heard noise.",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "415129449",
"quantity": 1
}
]
}Propriétés
Property | Type | Definition | Notes |
|---|---|---|---|
dealer_no * | string | Code that uniquely identifies a dealer. It must be 10 characters. If less than 10 characters, add '0' at the beginning. | Length: 10 |
vin * | string | The Vehicle Identification Number (VIN). | Max Length: 18 |
odometer * | number | Unit odometer value (Km or miles) from the repair order. | Precision: 0.1 Max Length: 18 |
rro_creation_date * | string | The last date and time at which this resource has changed, in ISO 8601 format | yyyy-mm-ddThh:mm:ssZ |
date_of_repair* | string | Date of Repair, in ISO 8601 format | yyyy-mm-ddThh:mm:ssZ |
system_code* | string | One of: "1-Engine", "2-Fuel System", "3-Ignition", "4-Starting", "5-Transmission / Propulsion", "6-Braking", "7-Steering / Suspension / Front Drive System", "8-Suspension / Rear Drive System", "9-Body", "10-Electrical", "11-Accessories, Special Tools, Others", "12-Hull Structure", "13-CARB and EPA Regulations", "14-CARB Regulations", "15-Battery and Tyres" | |
casual_part* | string | The part number of the part that is defective. | Max Length: 18 |
symptom_description* | string | The description of the symptoms that prompted the customer to investigate. | Max Length: 512 |
remedy_description* | string | The solution description of the dealer to fix the problem. | Max Length: 512 |
defect_description* | string | The description of the issue provided by the dealer | Max Length: 512 |
work_order_number* | string | Work order number (document identifier) + Job number 👉 The value in the work_order_number field must be unique. | Max Length: 15 <work_order>-<job code> |
installed_parts | array | The list of parts to be installed on the vehicle. |
|
installed_parts.item_id | string | The ID of each part to be installed. | Max Length: 18 |
installed_parts.quantity | integer | The quantity of the part to be installed. |
|
* Ces champs sont obligatoires.
Ressource : Travail
Cette ressource est utilisée pour récupérer l’état de création de la réclamation brouillon pour un travail.
Représentation JSON
{
"job_id": "DMS-20221219007781",
"claim_status": "failed",
"failure_reason": "Unit is out of Warranty",
"claim_number": null
}Propriétés
Propriété | Type | Définition |
|---|---|---|
job_id | chaîne de caractères | L'identifiant du job traitant la création du brouillon de réclamation de garantie. |
claim_status | chaîne de caractères | Le statut de la création du brouillon de réclamation de garantie. |
failure_reason | chaîne de caractères | La raison pour laquelle un brouillon de réclamation de garantie n’a pas été créé. Par exemple : "L’unité n’est plus sous garantie". |
claim_number | chaîne de caractères | Le champ contient le numéro de réclamation lorsque le brouillon de réclamation de garantie est créé. |
Ressource : Emplois
Cette ressource est utilisée pour récupérer l’état de création d’une demande préliminaire pour une liste d’emplois.
Il est renvoyé lors de l’appel du service Get avec une liste de tâches.
Représentation JSON
{
"items": [
{
"job_id": "DMS-20230420009063",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010469"
},
{
"job_id": "DMS-20230420009064",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010470"
},
{
"job_id": "DMS-20221104000204",
"claim_status": "failed",
"failure_reason": "Part Price API is not responding",
"claim_number": null
},
{
"job_id": "DMS-20230710032398",
"claim_status": "failed",
"failure_reason": "Unit claims are disabled on this unit due to campaign inclusion. At least one outstanding campaign repair has to be completed before unit claims will be enabled. Campaign claims need to be fulfilled directly in Tavant.",
"claim_number": null
}
]
}Propriétés
Propriété | Type | Définition |
|---|---|---|
éléments | Liste d’objets | |
job_id | chaîne | L’identifiant du travail traitant la création d’une réclamation de garantie brouillon. |
claim_status | chaîne | Le statut de la création de la réclamation de garantie brouillon. |
failure_reason | chaîne | La raison pour laquelle une réclamation de garantie brouillon n’a pas été créée. Par exemple : « L’unité n’est plus sous garantie ». |
claim_number | chaîne | Ce champ contient le numéro de réclamation lorsque la réclamation de garantie brouillon est créée. |
Limitations et contraintes
Types de réclamation
Cette API est limitée à la création de brouillons de réclamations d’unité. Les réclamations de pièces et les réclamations de campagne ne sont pas prises en charge.
Comprendre la garantie
Cette section fait suite aux informations fournies dans la section précédente Commencer et examine plus en détail les différents services de l'API de garantie.
Vue du processus à un niveau élevé
L'image ci-dessous présente une vue à haut niveau du processus de réclamation de garantie en brouillon.
Le concessionnaire sélectionne un ordre de réparation clôturé dans le DMS et lance la fonction de création d’une demande de garantie brouillon.
Le DMS affiche une fenêtre permettant au concessionnaire de saisir les informations requises qui ne figurent pas dans l’ordre de réparation :
- Le code système.
- Le numéro de pièce causale.
- Les descriptions du symptôme, du remède et du défaut.
Après avoir fourni les informations requises, le concessionnaire soumet la demande de garantie brouillon.
Les informations de la demande de garantie brouillon sont envoyées à l’API Warranty, qui les transmet à l’API de Tavant.
Tavant crée un travail contenant les informations de la demande de garantie brouillon et l’ajoute à la file de traitement.
L’identifiant du travail est renvoyé au DMS via l’API Warranty.
Tavant traite le travail dans la file et la demande de garantie brouillon est créée après un moment.
La demande de garantie brouillon est alors disponible sur BOSSWeb pour être complétée.
Le concessionnaire se rend sur BOSSweb, complète et soumet la demande de garantie.
Pendant que Tavant traite les travaux, votre DMS doit interroger l’API Warranty pour obtenir l’état du travail. Une fois le travail terminé et la demande de garantie brouillon créée, le numéro de réclamation renvoyé doit être enregistré et affiché au concessionnaire.
De cette manière, le concessionnaire sait quand il peut aller sur BOSSWeb pour compléter la réclamation.
Statut de création dans BOSSWeb
Dans BOSSWeb, le concessionnaire a accès aux Transferts DMS dans le module de gestion de garantie, qui affiche les demandes de réclamation de garantie brouillon envoyées par le DMS.
Brouillon
La vue affiche par défaut les réclamations de garantie en brouillon. La Numéro d’accusé de réception montre l’ID du travail que l’API Garantie renvoie à votre DMS dans la charge utile de la réponse Create.
Le menu d’état permet au concessionnaire de modifier le filtre.
Réussi
La vue Réussi affiche les réclamations de garantie en brouillon créées par le processus de Tavant. Le bouton Aller à la réclamation permet au concessionnaire d’accéder à la réclamation en brouillon pour la compléter et la soumettre.
Échoué
La vue Échoués affiche les demandes de réclamation de garantie brouillon qui ont échoué. Le concessionnaire peut cliquer sur le bouton Afficher les erreurs pour obtenir les détails de l’erreur.
Lorsque vous appelez pour obtenir le statut du travail, vous recevrez généralement la même erreur via l’API Warranty.
En cours
La vue En cours affiche les demandes de réclamation de garantie brouillon qui sont encore dans la file d’attente de Tavant et en attente de traitement.
La plupart du temps, cette vue est vide.
Erreurs possibles
La création d’une réclamation de garantie brouillon est rejetée si :
- Le numéro de concessionnaire n’est pas valide.
- Le VIN n’est pas valide.
- Le numéro de pièce causale n’est pas valide.
- Un champ obligatoire autre que la description du symptôme est vide.
- Le code système est invalide ou vide.
- Un champ de date utilise un format invalide.
- Le numéro d’ordre de travail ne comporte pas le numéro de tâche.
- Une demande de garantie brouillon a déjà été soumise pour le poste de l’ordre de réparation.
Si un numéro de pièce installée n'est pas une pièce BRP, la pièce est exclue de la création de la réclamation.
Référence API
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 20OZBLG4sVhTtmfEexlUQEw9OFiY' \
--data '{
"dealer_no": "0000691888",
"vin": "2BPSGDNA1NV000302",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "3001-02",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20230705032364' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs?jobs_id=DMS-20221104000204,DMS-20230710032398,DMS-20230420009063,DMS-20230420009064' \
--header 'Dealer-Number: 0000691695' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Comment faire
Cette section fournit des informations sur la manière d’obtenir des résultats spécifiques avec l’API.
Créer une réclamation de garantie brouillon
La réponse est un exemple rapide de la façon de créer une réclamation de garantie brouillon pour un numéro de VIN spécifique.
Modifiez le numéro du concessionnaire ou le VIN pour créer différentes réclamations pour différentes gammes de produits.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"dealer_no": "0000691888",
"vin": "3JBUKAP46NK000775",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "200-10",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'Obtenir le statut d’une tâche de réclamation de garantie brouillon
Obtient le statut d’une création de réclamation de garantie brouillon soumise.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20221219007781' \
--header 'Authorization: Bearer 6dVfKN4VFqsl0DMDRfHPLUOunwBx'Gestion des erreurs
Cette section présente divers scénarios d’appels incorrects ou erronés, qui entraînent des messages d’erreur et des résultats incorrects.
Erreur 400 (Mauvaise requête)
Le code d’état 400 apparaît généralement lors du développement et de l’intégration et ne devrait pas se produire lors des opérations normales. La réponse renvoyée contient les informations nécessaires pour corriger le problème.
De nombreux problèmes peuvent provoquer un code d’état 400 ; les plus courants sont répertoriés dans le tableau ci-dessous.
Poste
Réponse | Résolution |
|---|---|
Retourné si le numéro de concessionnaire n’est pas saisi, trop court ou trop long {
"status": "400",
"id": "rrt-07545d3b30b8d2411-b-ea-6909-1591317-1",
"title": "mauvaise_requête",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "Le paramètre 'Dealer-Number' est requis mais manquant."
},
{
"message": "[Chemin '/dealer_no'] La chaîne \"12345678\" est trop courte (longueur : 8, minimum requis : 10): []"
}
]
}
}
}
| Pour produire une réponse correcte, un numéro de concessionnaire valide contenant uniquement 10 chiffres doit être saisi. Il ne peut pas être plus long ou plus court. |
Retourné si la pièce causale n’est pas saisie ou n’est pas valide. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1695836-1.1",
"title": "mauvaise_requête",
"meta": {
"service": "15",
"detail": "Numéro de pièce causale invalide ABC."
}
}
--------------------------------------
{
"status": "400",
"id": "rrt-0e20a46609994a8ad-c-ea-22696-1603343-1",
"title": "mauvaise_requête",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "L’objet présente des propriétés requises manquantes ([\"causal_part\"]): []"
}
]
}
}
}
| Une pièce causale valide doit être saisie pour produire une réponse correcte. |
Retourné lorsqu’un code système n’est pas saisi ou n’est pas valide. {
"status": "400",
"id": "rrt-007c58ce55d14f4ff-d-ea-23462-1707968-1",
"title": "mauvaise_requête",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "[Chemin '/system_code'] Valeur d’instance (\"16-ABCD\") non trouvée dans l’énumération (valeurs possibles : [\"1-Moteur\",\"2-Système de carburant\",\"3- Allumage\",\"4-Démarrage\",\"5-Transmission / Propulsion\",\"6-Freinage\",\"7-Direction / Suspension / Système d’entraînement avant\",\"8-Suspension / Système d’entraînement arrière\",\"9-Carrosserie\",\"10-Électrique\",\"11-Accessoires, Outils spéciaux, Autres\",\"12-Structure de coque\",\"13-Réglementations CARB et EPA\",\"14-Réglementations CARB\",\"15-Batterie et pneus\"]): []"
}
]
}
}
}
| Un code système valide doit être saisi pour produire une réponse correcte. L’un des codes système ci-dessous doit être saisi. "1-Moteur" "2-Système de carburant" "3-Allumage" "4-Démarrage" "5-Transmission / Propulsion" "6-Freinage" "7-Direction / Suspension / Système d’entraînement avant" "8-Suspension / Système d’entraînement arrière" "9-Carrosserie" "10-Électrique" "11-Accessoires, Outils spéciaux, Autres" "12-Structure de coque" "13-Réglementations CARB et EPA" "14-Réglementations CARB" "15-Batterie et pneus" |
Obtenir
Réponse | Résolution |
|---|---|
Renvoyé lorsque l’ID du travail n’est pas saisi dans l’URL. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22529-1664059-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "Le paramètre de requête 'jobs_id' est requis sur le chemin '/warranties/jobs' mais n’a pas été trouvé dans la requête.: []"
}
]
}
}
} | Un ID de travail valide doit être saisi dans l’URL pour vérifier le statut d’une réclamation. Voici un exemple d’un travail : DMS-20221219007781
|
401 Non autorisé
Le code d’erreur 401 Non autorisé est renvoyé lorsque vous tentez d’appeler l’API avec un access_token expiré.
Vous devez obtenir un nouveau access_token avec un appel à l’API d'authentification d'application.
Le code d’erreur 401 Unauthorized est également renvoyé si vous n’avez pas demandé l’accès à l’API en créant un ticket dans le Jira du DCP.
Lorsque vous êtes prêt à commencer à travailler sur une API, vous devez créer un ticket de certification dans Jira, comme décrit dans la section Activités de certification avec Jira.
Si vous avez déjà commencé à travailler sur une API et perdu l’accès, créez un ticket de support comme décrit dans la section Ouvrir un ticket de support.
404 Introuvable
Le code d’état 404 Introuvable est renvoyé par le service Obtenir le statut du travail lorsque l’identifiant de travail demandé est introuvable.
{
"status": "404",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1664528-1.1",
"title": "not_found",
"meta": {
"service": "17",
"detail": "job_id 00000000 not found"
}
}Exigences DSP
Exigences fonctionnelles
ID | Type | Exigence |
|---|---|---|
1 | Obligatoire | L’ébauche de réclamation de garantie doit être créée à partir d’un ordre de réparation. |
2 | Obligatoire | Les messages d’erreur doivent être affichés au concessionnaire. |
3 | Obligatoire | La liste des numéros de réclamation soumis doit être affichée aux concessionnaires. |
Activités de certification
Cette section présente toutes les activités de certification et les validations qui doivent être complétées pour certifier l’API.
Assurance qualité
Les tests répertoriés dans le tableau ci-dessous doivent être réalisés avec succès dans l’environnement de test avant que vous puissiez commencer la phase pilote du concessionnaire.
ID | Test | Résultat attendu |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
Pilote concessionnaire
Le tableau ci-dessous décrit les paramètres et validations du pilote concessionnaire.
Paramètre | Valeur |
|---|---|
Environnement | Production |
Nombre de concessionnaires | 1 à 3 |
Durée | 1 semaine |
Validation 1 | Envoyer une capture d'écran de l'état de création d'une réclamation de garantie brouillon pour un VIN pour chaque ligne de produit prise en charge par le concessionnaire. |
Validation 2 | Un concessionnaire doit être en mesure de trouver des VIN "Sous garantie" pour produire une réponse appropriée. |
Postman
Cette section décrit ce qui est disponible dans Postman pour explorer l’API.
Environnements
Un environnement Postman est disponible pour essayer l’API Warranty. Cet environnement Postman contient des variables utilisées par les requêtes et est configuré pour se connecter à l’environnement de test.
Collections
La collection DMS - Warranty inclut des exemples d’appels API pour créer un brouillon de réclamation de garantie et récupérer le statut du travail.