API des campagnes
Commencer
L’API Campaigns permet à vos concessionnaires de demander et d’afficher les détails des campagnes/bulletins de garantie via leur DMS pour un numéro d’identification de véhicule (VIN) spécifique.
Lorsqu’un client apporte une unité pour un entretien ou une réparation, une partie importante des activités du concessionnaire consiste à vérifier si des bulletins de garantie et de sécurité s’appliquent à l’unité. Les bulletins de garantie et de sécurité peuvent être trouvés à l’aide du VIN de l’unité. Lors de la création de l’ordre de réparation, le technicien recherche les bulletins applicables à l’unité. Si des bulletins sont trouvés, les travaux et pièces correspondants peuvent être ajoutés à l’ordre de réparation.
Par où commencer ? Lisez-moi d’abord !
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 des détails sur l’authentification et les identifiants.
Informations techniques
Caractéristiques
Type d'API | Type DSP | Version DCP | Complexité |
|---|---|---|---|
Obtenir des données depuis BRP | DMS | V3 - International | Faible |
Envoyer des données à BRP | CRM | V4 - Amérique du Nord | Un peu plus |
Transaction avec BRP | | | Un peu plus encore |
Authentification
L'API utilise Authentification des applications.
Vous avez besoin d'un jeton d'accès valide avant d'appeler cette API ou vous devez appeler le 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/<v3 ou v4> |
|---|---|
Production | https://cloud-api.brp.com/dcp/<v3 ou v4> |
Ressource : Campagnes
La ressource Campagnes fournit des informations sur un numéro de série (VIN) spécifique, ainsi que certaines informations sur les campagnes associées.
Représentation JSON
{
"vin": "2BPSCEKCXKV000009",
"usage_descr": "Personal/Recreational",
"target_market_descr": "Canada, US",
"product_code": "000CEKC00",
"platform_descr": "REV-G4",
"package_descr": "SP",
"model_year": "2019",
"model_descr": "Summit",
"length": "154\" (3923 mm)",
"is_cross_border": false,
"engine_type": "850 E-TEC",
"comments": "",
"color_descr": "Black",
"campaigns": [
{
"type_descr": "Regular",
"period_valid_to": "2022-01-31",
"period_valid_from": "2019-01-22",
"is_claimed": true,
"campaign_no": "0010",
"campaign_descr": "ENGINE COOLANT OUTLET HOSE LEAK",
"bulletin_no": "2019-9",
"articles": [
{
"last_publish_date": "2019-03-11T17:10:42.000Z",
"content_type": "PDF",
"article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000fxSR?lang=en_US",
"article_no": "000136062",
"article_id": "kaA0c000000L42WEAS",
"article_descr": "SKI-DOO 2019-9 Engine Coolant Outlet Hose Leak_136062_WCN11Y019S01_en"
}
]
},
{
"type_descr": "Safety",
"period_valid_to": "9999-12-31",
"period_valid_from": "2019-07-02",
"is_claimed": false,
"campaign_no": "0012",
"campaign_descr": "FUEL INJECTOR POTENTIAL LEAK",
"bulletin_no": "2019-11",
"articles": [
{
"last_publish_date": "2019-07-03T16:52:52.000Z",
"content_type": "PDF",
"article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000KzTR?lang=en_US",
"article_no": "000136589",
"article_id": "kaA0c000000L48jEAC",
"article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en"
},
{
"last_publish_date": "2019-07-03T15:07:14.000Z",
"content_type": "URL",
"article_url": "https://brp--qauat.my.salesforce.com/kA90c000000004S?lang=en_US",
"article_no": "000136553",
"article_descr": "Ski-Doo Fuel Injector Bolts Replacement"
}
]
}
],
"brand_descr": "Ski-Doo Snowmobile"
}
Propriétés
Property | Type | Definition | Notes |
|---|---|---|---|
serial_no | string | Serial number of the unit | Max Length:18 |
usage_descr† | string | Describe the usage of the unit | Max Length:30 |
product_code | String | Code that uniquely identifies a product. | Max Length:18 |
model_descr | String | Description of the product. | Max Length:40 |
model_year | number | Model year of the vehicle. | Max Length:4 |
brand_descr† | string | Product brand description. | Max Length:40 |
package_descr† | string | Describe the package of a product. | Max Length:40 |
color_descr† | string | Identifies the colour of the vehicle. | Max Length:40 |
length | string | Specify the length of the product. | Max Length:25 |
engine_type | string | Identify the engine’s type related to a product. | Max Length:40 |
platform_descr | string | Identify the product’s platform. | Max Length:512 |
target_market_descr | string | Identify which market is related to a vehicle. | Max Length:40 |
is_cross_border | Boolean | Will be set to ‘true’ when the dealer country is different from the consumer country. |
|
comments† | string | Comments will be provided only when a vehicle is ‘cross_border’ to provide additional information to the dealer | Max Length: 255 |
campaigns | list of objects | The campaign article object is used to show the details of each campaign. |
|
campaigns .campaing_no | string | The number that is used to identify the campaign. | Max Length:10 |
campaigns .campaign_descr† | string | Description of the campaign. | Max Length:40 |
campaigns .type_descr† | String | The classification for the types of campaigns. | Max Length:40 |
campaigns .period_valid_from | date | Identify the start date of the campaign. In ISO 8601 format. | Format: YYYY-MM-DD |
campaigns .period_valid_to | date | Identify the date on which the campaign will end. In ISO 8601 format. | Format: YYYY-MM-DD |
campaigns .is_claimed | boolean | The state that allows us to know the status of the bulletin:
|
|
campaigns .bulletin_no | string | The number that is used to identify the bulletin. | String |
campaigns.articles | List of Objects | The campaign article object is used to show the details of each article related to one campaign. |
|
campaigns.articles .article_no | string | The number that is used to identify the article. |
|
campaigns.articles .article_descr | string | Description of the article. | String |
campaigns.articles .content_type | string | Description of the type of the article.One of the:
| Max Length:3 |
campaigns.articles .article_url | string | The URL is used to display the article in the DMS. | String |
campaigns.articles .last_publish_date | Date-time | Date and time the article has been published. In ISO 8601 format. | Format: yyyy-mm-ddThh:mm:ssZ
|
- Les propriétés marquées d'une dague (†) sont renvoyées dans la langue demandée.
Limitations et contraintes
Ligne de produit
Le concessionnaire peut demander les campagnes de l’unité uniquement pour la ligne de produit qu’il prend en charge.
Comme un concessionnaire ne peut pas effectuer de travail sur une ligne de produit pour laquelle il n’est pas qualifié, les campagnes sont inutiles.
URL de l'article
Chaque campagne contient une liste d'articles. Dans les informations de l'article, la propriété article_url contient l'URL de l'article.
Cette URL renvoie à l'article dans BOSSWeb. Pour accéder à l'article en utilisant cette URL, vous devrez ouvrir une fenêtre de navigateur vers l'URL de l'article et le concessionnaire doit fournir ses identifiants BOSSWeb pour accéder à l'article.
Voir la Utilisation des campagnes pour obtenir des articles section sur la façon d'utiliser les informations de campagne.
Disponibilité linguistique
Toutes les campagnes ne sont pas traduites dans toutes les langues.
Si la langue demandée n'est pas disponible, les campagnes sont renvoyées en anglais.
Référence de l'API
curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=en-US' \
--header 'Dealer-Number: 0000701207' \
--header 'Authorization: Bearer REPLACE_ME'
Tables de référence
Langues
Langue en code de langue ISO (ISO-639-1 + ISO 3166-1)
Format : xx-XX
xx : code de langue en minuscules
XX : code de pays en majuscules
Valeurs de code de langue prises en charge
Code | Langue |
|---|---|
de | Allemand |
en | Anglais |
es | Espagnol |
fi | Finnois |
fr | Français |
it | Italien |
nl | Néerlandais |
no | Norvégien |
pt | Portugais (Brésil) |
sv | Suédois |
Comment faire
Cette section fournit des informations sur la manière d'obtenir des résultats spécifiques avec l'API.
Obtenir les campagnes en français
La requête ci‑dessous est un exemple rapide de la façon d’obtenir les campagnes en français.
curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=fr-CA' \
--header 'Dealer-Number: 0000691888' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'Utiliser les campagnes pour obtenir les articles
Appeler l’API des articles
Lorsque vous appelez l’API des campagnes, vous devriez remarquer la propriété article_no dans le corps de la réponse JSON. Utilisez le numéro d’article provenant des campagnes pour appeler l’API des articles et récupérer le PDF de l’article.
Reportez-vous à la API d'articles pour plus d'informations.
Utilisation de l’URL de l’article
Veuillez noter que ce n’est pas la méthode privilégiée pour récupérer un article à partir d’une campagne.
Dans le corps de la réponse JSON renvoyée par l’API, vous devriez remarquer la propriété article_url. Copier/coller l’URL dans votre navigateur vous redirigera vers BOSSweb, comme illustré dans l’image ci-dessous.
Vous pouvez vous connecter en utilisant vos identifiants QA BOSSweb et être dirigé vers le PDF de l’article.
L’article dépend de la langue demandée lors de l’appel à l’API.
L’article est affiché dans BOSSWeb, comme le montre l’image ci-dessous.
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 inappropriés.
400 Mauvaise requête
Le code d’état 400 est généralement observé lors du développement et de l’intégration et ne devrait pas être reçu lors d’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.
Réponse | Résolution |
|---|---|
Renvoyé si le format de langue est invalide. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22692-1283834-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "La regex ECMA 262 \"^[a-z]{2}-[A-Z]{2}$\" ne correspond pas à la chaîne d'entrée \"\": []"
}
]
}
}
} | Le format de langue valide est le suivant Format : xx-XX xx : code de langue en minuscules XX : code pays en majuscules Un format de langue valide doit être saisi pour produire une réponse correcte. |
Renvoyé si le VIN est invalide. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Le VIN YDV40501Afff est introuvable",
"payload": {
"errors": [
{
"title": "Le VIN YDV40501Afff est introuvable",
"code": "not_found"
}
]
}
}
} | Un VIN valide doit être saisi pour produire une réponse correcte. |
Renvoyé si le concessionnaire n’a pas la ligne de produits correspondant au VIN. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11755-1483106-1.1",
"title": "not_found",
"meta": {
"service": "97",
"detail": "Désolé, le VIN saisi ne correspond pas à un produit que vous supportez.",
"payload": {
"errors": [
{
"title": "Désolé, le VIN saisi ne correspond pas à un produit que vous supportez.",
"code": "unauthorized"
}
]
}
}
}
| Le concessionnaire doit prendre en charge la ligne de produits du VIN. |
Renvoyé lorsque le numéro de concessionnaire est manquant. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22691-1284376-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "Le paramètre d’en-tête 'Dealer-Number' est requis sur le chemin '/unit/{vin}/campaigns' mais est absent de la requête.: []"
}
]
}
}
}
| Un numéro de concessionnaire doit être fourni dans l’en-tête de la requête. |
Renvoyé lorsque le numéro de concessionnaire est invalide. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1482909-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Aucun concessionnaire principal trouvé pour Dealer-Number",
"payload": {
"errors": [
{
"title": "Aucun concessionnaire principal trouvé pour Dealer-Number: 000011hhhh",
"code": "not_found"
}
]
}
}
} | Le numéro de concessionnaire fourni dans l’en-tête doit être un numéro de concessionnaire BRP valide. |
401 Non autorisé
Le code d'état 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 Not Found est renvoyé lorsque le VIN demandé est introuvable ou n’a aucune campagne.
Réponse | Résolution |
|---|---|
Renvoyé lorsque le VIN saisi est introuvable {
"status": "404",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Le VIN YDV40501Afff est introuvable",
"payload": {
"errors": [
{
"title": "Le VIN YDV40501Afff est introuvable",
"code": "not_found"
}
]
}
}
} | Un VIN correct doit être saisi pour que l’API réponde correctement. |
Renvoyé lorsque le VIN est valide, mais qu’il n’a aucune campagne active. {
"status": "404",
"id": "rrt-065e1c5bbf0ebc061-b-ea-31810-5677524-5.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Le VIN 3JB2GEG2XLJ006676 n’a aucune campagne.",
"payload": {
"errors": [
{
"title": "Le VIN 3JB2GEG2XLJ006676 n’a aucune campagne.",
"code": "not_found"
}
]
}
}
} | Il n’y a rien à faire, si ce n’est afficher un message à l’attention du concessionnaire pour l’informer qu’aucune campagne active n’est associée à ce VIN. |
Exigences DSP
Exigences fonctionnelles
ID | Type | Exigence |
|---|---|---|
1 | Obligatoire | La liste des campagnes applicables à l’unité doit être affichée au concessionnaire. |
2 | Obligatoire | L’indicateur de marché transfrontalier/parallelle et le texte d’avertissement doivent être affichés au concessionnaire. |
3 | Obligatoire | Les messages d’erreur doivent être affichés au concessionnaire. |
4 | Obligatoire | Un message doit être affiché à l’utilisateur lorsque l’unité n’a aucune campagne active. |
Activités de certification
Cette section présente toutes les activités de certification et les validations qui doivent être effectué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 concessionnaire.
Liste des NIV
Gamme de produits | NIV |
|---|---|
Motoneige (SNO) | 2BPSMXKF5KV000020 |
VTT | RLVDGF119FVN00027 |
Sea-Doo (PWC) | YDV00005G819 |
Côte-à-côte (SSV) | 3JB7VAX42MK000288 |
3-roues (3WV) | 3JB2FEG45PJ002724 |
ID | Test | Résultat attendu |
|---|---|---|
1 | Appeler l’API de campagne pour chaque langue et ligne de produit du VIN prise en charge par votre concession. | Afficher toutes les informations de campagne pertinentes concernant le VIN saisi. |
2 | Appeler l’API de campagne avec une ligne de produit du VIN qui n’est pas prise en charge par votre concession. | Un journal d’erreur s’affiche avec le statut 400 : « Désolé, le VIN saisi ne correspond pas à un produit que vous prenez en charge. » |
Programme pilote pour concessionnaires
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 des campagnes pour un ou deux VINs pour chaque ligne de produit prise en charge par le concessionnaire. |
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 Campaigns. Cet environnement Postman contient des variables utilisées par les requêtes et configurées pour se connecter à l'environnement de test.
Collections
La collection DMS - Campaigns contient des exemples d'appels API pour récupérer les campagnes de véhicules.