API d'articles
Commencer
L'API Articles permet à vos revendeurs d’afficher un article PDF dans leur DMS pour un numéro d’article spécifique.
Lorsqu’un client apporte une unité pour maintenance ou réparation, une partie importante des activités du revendeur consiste à utiliser les articles applicables à la campagne de garantie de l’unité. En utilisant les articles, votre revendeur peut voir la campagne de garantie.
Un article fournit des informations sur :
- Problème
- Solution
- Pièces requises
- Actions correctives
L’article détaille tout et inclut des images, garantissant que vos revendeurs n’aient aucun problème à résoudre le souci.
Par où commencer ? Lisez-moi 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 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 d’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 valide 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 : Articles
La ressource d'article fournit des informations sur un article spécifique.
Représentation JSON
{
"article_no": "000136021",
"article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en",
"article_url": "https://brp--qauat--c.visualforce.com/apex/Article_Detail_Warranty_Bulletin?lang=en_US&id=kAA0c000000KzTR#googtrans(en|en)",
"last_publish_date": "2019-07-03T12:52:50Z",
"content_type": "PDF",
"content":"pdf…!@#$%^&DFRUIJHKODFGHUJK^&U*I(OGHJKHJKKJbase64dsadasadsdasa"
}
Propriétés
Propriété | Type | Définition | Notes |
|---|---|---|---|
article_no* | chaîne | La chaîne utilisée pour identifier l’article. | Longueur maximale : 18 |
article_descr | chaîne | Description de l’article. | Chaîne |
article_url | chaîne | L’URL est utilisée pour afficher l’article dans BOSSweb. | Chaîne |
last_publish_date | Date-heure | Date et heure de publication de l’article. Au format ISO 8601. | Format : yyyy-mm-ddThh:mm:ssZ |
content_type | chaîne | Description du type d’article. L’un des suivants :
| Longueur maximale : 3 |
content | chaîne | Détails de l’article.
| Chaîne maximale |
Limitations et Contraintes
URL de l’article
Pour utiliser l’URL de l’article afin d’afficher le contenu de l’article, le concessionnaire doit être connecté à BOSSWeb.
Le contenu de l’article est stocké dans SalesForce. Le concessionnaire ne peut y accéder qu’à travers BOSSWeb, c’est pourquoi l’URL est une URL du Centre de connaissances BOSSWeb.
La méthode privilégiée pour afficher le contenu de l’article est d’utiliser le PDF.
Le PDF est encodé en base64 et doit être converti en PDF binaire avant d’être affiché.
Disponibilité des langues
Tous les articles ne sont pas traduits dans toutes les langues.
Si la langue demandée n’est pas disponible, l’article est retourné en anglais.
Référence de l'API
curl --request POST 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer REPLACE_ME'Comment faire
Cette section fournit des informations sur la façon d’obtenir des résultats spécifiques avec l’API.
Obtenir des articles en français
La requête ci-dessous est un exemple rapide de la façon d’obtenir un article en français.
curl --location 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'Une fois converti du codage base64 en PDF, le document peut être affiché et ressemble à 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 inadéquats.
400 Mauvaise requête
Le code d’état 400 est généralement observé durant le développement et l’intégration et ne devrait pas être reçu 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 entraîner un code d’état 400, et les plus courants sont listé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-22691-415152-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 \"AA-BBB\": []"
}
]
}
}
} | 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 afin de produire une réponse correcte. |
Renvoyé lorsque le numéro de revendeur est manquant. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22692-415715-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 '/article/{article_no}' mais est introuvable dans la requête.: []"
}
]
}
}
} | Un numéro de revendeur doit être fourni dans l’en-tête de la requête. |
401 Non autorisé
Le code d’erreur 401 Non autorisé est renvoyé lorsque vous tentez d’appeler l’API avec un access_token.
Vous devez obtenir un nouveau jeton d'accès 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 l’article est introuvable.
Réponse | Résolution |
|---|---|
Renvoyé lorsque le numéro d’article saisi est introuvable {
"status": "404",
"id": "rrt-00a574511a562afb5-b-ea-22206-2601758-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Erreur backend",
"payload": {
"status": "404",
"errors": [
{
"title": "L’article 123456789 est introuvable",
"code": "not_found"
}
]
}
}
} | Un numéro d’article correct doit être saisi pour que l’API puisse renvoyer une réponse appropriée. Pour qu’un numéro d’article soit correct, il doit figurer dans la liste des numéros d’article. |
Exigences DSP
Exigences fonctionnelles
ID | Type | Exigence |
|---|---|---|
1 | Obligatoire | Les messages d'erreur doivent être affichés au concessionnaire. |
2 | Obligatoire | Les articles applicables à la campagne doivent être affichés aux concessionnaires. |
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 listé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.
ID | Test | Résultat attendu |
|---|---|---|
1 | Appeler l’API Article pour chaque langue prise en charge par votre DMS. Article #: 000136062 | Afficher toutes les informations pertinentes concernant l’article correspondant au numéro saisi. |
2 | Appeler l’API avec un numéro d’article invalide. Article #: 123456789 | Un log d’erreur apparaît avec le statut 400 "Article introuvable" |
Pilote concessionnaire
Le tableau ci-dessous décrit les paramètres et validations du pilote concessionnaire.
Paramètre | Valeur |
|---|---|
Environnement | Production |
Nombre de distributeurs | 1 à 3 |
Durée | 1 semaine |
Validation 1 | Envoyer une capture d’écran d’un article pour un ou deux numéros d’article, pour chaque distributeur du pilote. |
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 Articles. 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 - Articles contient des exemples d’appels API pour récupérer un article.