API de commande des unités
Pour commencer
L’API Units Order permet au concessionnaire de récupérer les commandes d’unités préparées dans le système de gestion des commandes (OMS) dans BOSSWeb.
Le concessionnaire peut ensuite suivre la livraison de l’unité et, une fois livrée, l'insérer dans l’inventaire en utilisant le NIV indiqué dans les informations de livraison.
Par où commencer ? Lisez ceci en premier !
Avant de commencer à travailler avec 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.
- Processus de Certification pour plus de détails sur le processus de certification et Jira.
- Obtenir de l'aide pour des détails sur la façon d'obtenir de l'aide et Jira.
Résumé commercial
Sujet | Description |
|---|---|
Portée | Commandes d’unités en Amérique du Nord |
Scénarios |
|
Fonctionnalités principales |
|
Processus métiers pris en charge |
|
Avantages pour les concessionnaires |
|
Avantages pour BRP |
|
Informations techniques
Caractéristiques
Type d'API | Type DSP | Version DCP | Complexité |
|---|---|---|---|
Obtenir des données du BRP | DMS | V3 - International | Faible |
Envoyer des données au BRP | CRM | V4 - Amérique du Nord | Un peu plus |
Transaction avec le BRP | | | Quelque peu plus |
Authentification
L'API utilise Authentification du concessionnaire et Authentification de l'application.
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)
Authentification du concessionnaire
Vous avez besoin d’un jeton d’accès valide avant d’appeler cette API ou vous devez appeler l’API d'authentification du concessionnaire pour en obtenir un.
Le access_token est valable pendant 2 heures.
Vous devez utiliser le refresh_token pour obtenir un access_token avant que l’actuel n’expire.
❗❗ Le access_token obtenu via l’API d'authentification du concessionnaire doit correspondre au concessionnaire dont le numéro est utilisé dans le champ dealer_no du payload ou de l’en-tête ❗❗
Voir la section Connexion concessionnaire pour plus d’informations.
Reportez-vous à la Authentification du concessionnaire et API d'authentification du concessionnaire sections pour plus d’informations.
URL de base
Test | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Production | https://cloud-api.brp.com/dcp/v4 |
Ressource : Commande d’unité
L'API renvoie la Commandes d'unités ressource qui contient des commandes d'unités.
Représentation JSON
{
"sales_order_no": "1030001693",
"order_type": "regular",
"dealer_no": "0000690885",
"dealer_po_no": "IO690885-MY23-91DEC",
"creation_date": "2023-02-04T01:22:25Z",
"requested_delivery_date": "2022-11-21",
"items": [
{
"item_no": "000010",
"product_code": "0008MPF00",
"product_descr": "Defender MAX XT HD10",
"color": "Mossy Oak Break-Up Country Cam",
"model_year": "2023",
"segment_descr": "Defender MAX",
"package_descr": "XT",
"product_line": "SSV",
"customer_reference_period_descr": "Dec",
"customer_reference_year_code": "",
"order_qty": 1,
"requested_delivery_date": "2022-11-21",
"requested_delivery_period_descr": "Dec",
"is_cancellable": false,
"is_pre_order": false,
"is_cancellable_pre_order": false,
"estimated_delivery_period": "2023-02-27",
"estimated_delivery_period_type": "week",
"estimated_shipped_period": "2023-02-28",
"estimated_shipped_period_type": "week",
"ship_to_no": "0000690885",
"delivery_schedule": [
{
"schedule_line_no": "0002",
"confirmed_date": "2023-02-28",
"confirmed_qty": 1,
"processing_status": "",
"delivery_status": ""
}
],
"delivery_progress": [
{
"freight_no": "7000003739",
"estimated_shipped_date": "2023-02-28",
"estimated_delivery_date": "2023-02-27",
"goods_issue_date": "2023-02-27",
"shipped_date": "2023-02-28",
"delivery_date": "2023-02-28",
"confirmation_status_code": "10",
"serial_numbers": [
"3JBUCAX44PK001102"
],
"shipping_carrier": {
"carrier_no": "31000164",
"carrier_name": "MCK TRUCKING INC",
"carrier_mobile": "",
"carrier_email": "",
"carrier_contact": ""
}
}
]
}
]
}Propriétés
Propriété | Type | Type | Notes |
|---|---|---|---|
sales_order_no | string | Numéro qui identifie de manière unique le document de vente. | Longueur max : 10 |
Lignes de produits
Clé | Valeur | Marque |
|---|---|---|
2WV | Véhicules à deux roues | Can-Am On-Road |
3WV | Véhicules à trois roues | Can-Am On-Road |
ATV | Véhicules tout-terrain | Can-Am Off-Road |
OE | Moteurs hors-bord | Sea-Doo |
PTN | Bateaux pontons | Sea-Doo |
PWC | Motomarines | Sea-Doo |
SNO | Motoneiges | Ski-Doo |
SSV | Véhicules côte à côte | Can-Am Off-Road |
Ressource : Liste des commandes d’unités
Lorsqu'elle est appelée pour demander une liste d’ordres d’unités, l’API Units renvoie un tableau de ressources d’Ordre d’Unité .
👉 Même si vous appelez l’API Units Order avec un filtre pour récupérer un seul ordre, l’API renvoie toujours une liste d’ordres d’unités.
Les réponses retournées contiennent deux objets qui vous aident à naviguer dans les pages des ordres d’unités.
Représentation JSON
{
"items": [
{
List of Unit Orders resources
}
],
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/units/orders?page=2&limit=200"
},
"meta": {
"total_records": 233,
"total_pages": 2,
"current_page": 1,
"limit": 200
}
}Propriétés
Propriété | Type | Définition |
|---|---|---|
éléments | Liste d’objets | Liste des ressources Unit renvoyées. |
liens | objet | Liens de pagination. |
liens.précédent | chaîne | URL à utiliser pour récupérer la page précédente. NULL s’il n’y a pas de page précédente. |
liens.suivant | chaîne | URL à utiliser pour récupérer la page suivante. NULL s’il n’y a pas de page suivante. |
meta | objet | Statistiques de la requête. |
meta.total_records | nombre | Nombre d’enregistrements renvoyés par la requête. |
meta.total_pages | nombre | Nombre de pages calculé à partir de la limite. |
meta.current_page | nombre | Le numéro de page actuel ou le numéro de page demandé. |
meta.limit | nombre | Limite provenant des paramètres de la requête. |
Liens
Le Lien peut être utilisé pour naviguer entre les pages renvoyées par l'API Units.
Lorsqu’un lien n’est pas NULL, il peut être utilisé pour accéder à la page précédente ou suivante. Cela simplifie la navigation entre les pages, car vous n’avez pas à conserver votre requête de paramètres ; l’URL du lien contient les paramètres de requête que vous avez fournis ainsi que les paramètres par défaut pour ceux que vous n’avez pas fournis.
Métadonnées
L’objet Meta fournit des statistiques sur le nombre de ressources Unit renvoyées par votre requête et sur le nombre de pages attendues.
Ces informations peuvent être utiles pour le diagnostic et pour vérifier que toutes les ressources de l’unité ont été reçues.
Limitations & Contraintes
Format de nombre
Tous les champs numériques avec décimales utilisent le point(.) comme séparateur décimal. La virgule (,) n’est PAS prise en charge comme séparateur décimal.
Paramètre de requête Filter
Le $filter peut être utilisé pour filtrer les commandes d’unités en utilisant uniquement les propriétés suivantes :
- sales_order_no
- dealer_po_no
- date_de_livraison_demandee
👉 L'utilisation d'autres propriétés dans la $filter entraînera une erreur ou sera ignorée.
Référence de l'API
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'Gammes de produits
Clé | Valeur | Marque |
|---|---|---|
2WV | Véhicules à deux roues | Can-Am On-Road |
3WV | Véhicules à trois roues | Can-Am On-Road |
ATV | Véhicules tout-terrain | Can-Am Off-Road |
OE | Moteurs hors-bord | Sea-Doo |
PTN | Bateaux pontons | Sea-Doo |
PWC | Motomarines | Sea-Doo |
SNO | Motoneiges | Ski-Doo |
SSV | Véhicules côte à côte | Can-Am Off-Road |
Comment faire
Cette section fournit des informations sur la manière d'obtenir des résultats spécifiques avec l'API.
Obtenir des commandes en utilisant une plage de dates
Cet exemple montre comment obtenir les commandes d'unités en utilisant une plage de dates.
La requête utilise le limite paramètre pour limiter la réponse à 3 commandes par page.
Le liens fournit les informations pour naviguer entre les pages. Consultez la Pagination section pour plus d'informations.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir les commandes unitaires pour une ligne de produits
Cet exemple montre comment obtenir les commandes unitaires pour une ligne de produits spécifique. Les lignes de produits valides sont répertoriées dans le tableau API de commande des unités .
La requête utilise le paramètre limit pour limiter la réponse à 3 commandes par page.
La propriété links fournit les informations nécessaires pour naviguer entre les pages. Consultez la section Pagination pour plus d’informations.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&product_line=PWC&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir une commande avec le numéro de commande
Cet exemple montre comment obtenir l'ordre d'unité en utilisant un numéro de commande client dans le $filter paramètre de requête.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=sales_order_no%20eq%20%271030417429%27' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir une commande avec le numéro de bon de commande du concessionnaire
Cet exemple montre comment obtenir la commande d'unité en utilisant un numéro de bon de commande du concessionnaire dans le $filter paramètre de requête.
La requête utilise le paramètre limit pour limiter la réponse à 2 commandes par page.
La propriété links fournit les informations nécessaires pour naviguer entre les pages. Consultez la section Pagination pour plus d’informations.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=dealer_po_no%20eq%20%20%27IO690885-MY23-91%27&limit=2' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir les commandes d’unités en utilisant la date demandée
Cet exemple montre comment obtenir les commandes d’unités en utilisant une plage de dates demandée dans le $filter paramètre de requête.
La requête utilise le paramètre limit pour limiter la réponse à 3 commandes par page.
La propriété liens fournit les informations permettant de naviguer entre les pages. Reportez-vous à la Pagination section pour plus d'informations.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=((requested_delivery_date%20ge%202024-01-02)%20and%20((requested_delivery_date%20le%202024-07-02)))&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' 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 Requête incorrecte
Le code d’état 400 est généralement observé pendant le développement et 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 entraîner un code d’état 400 ; les plus courants sont répertoriés dans le tableau ci-dessous.
Réponse | Résolution |
|---|---|
Renvoyé si le numéro de concessionnaire est invalide. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6461009-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "La chaîne \"12345\" est trop courte (longueur : 5, minimum requis : 10) : []"
}
]
}
}
} | Si le concessionnaire utilise votre DMS, il se peut qu’il ne soit plus un concessionnaire BRP. Vérifiez avec lui et désactivez les mises à jour d’inventaire des pièces. Assurez-vous que le numéro de concessionnaire comporte 10 caractères. Si vous enregistrez le numéro sans les '0' initiaux, ajoutez-les avant d’appeler l’API. L’erreur est également renvoyée si le concessionnaire n’est pas un concessionnaire BRP actif. |
Renvoyé si le numéro de concessionnaire est manquant. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6460630-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 'dealer_no' est requis sur le chemin '/units/orders' mais est absent de la requête. : []"
}
]
}
}
} | Le numéro de concessionnaire est obligatoire dans l’appel. |
Renvoyé si une date a un format invalide. {
"status": "400",
"id": "rrt-0aa500db076dc9eed-d-ea-1328974-8272532-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "échec de la validation de la requête",
"payload": {
"details": [
{
"message": "La chaîne \"AAbbCC\" est invalide par rapport au(x) format(s) de date demandé(s) yyyy-MM-dd : []"
}
]
}
}
} | Modifiez le format de la chaîne de date pour qu’il corresponde au format du payload. |
Renvoyé si les dates sont inversées.
{
"status": "400",
"id": "rrt-007c4ae418b4c128f-b-ea-3013144-8304219-1.1",
"title": "bad_request",
"meta": {
"service": "21",
"detail": "creation_date_from ne peut pas être postérieure à creation_date_to. Veuillez vérifier vos dates et réessayer."
}
}
| Vérifiez que le creation_date_from est antérieur (plus ancien) au creation_date_to. |
401 Non autorisé
Le code d’erreur 401 Unauthorized est renvoyé lorsque vous tentez d’appeler l’API avec un access_token expiré.
Vous devez obtenir un nouveau access_token en appelant l’API 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 d’assistance comme décrit dans la section Ouvrir un ticket d’assistance.
403 Forbidden
Le code d’erreur 403 Forbidden est renvoyé si le numéro de concessionnaire ne correspond pas au jeton du concessionnaire.
{
"status": "403",
"id": "rrt-08ca5848b0d5e485e-b-ea-1816747-7377470-1.1",
"title": "forbidden",
"meta": {
"service": "96",
"detail": "The dealer_no in the request doesn't correspond to the dealer_no associated with the dealer token provided."
}
}Assurez-vous d’utiliser le jeton d’authentification du concessionnaire correspondant.
Exigences DSP
Exigences fonctionnelles
ID | Type | Exigence |
|---|---|---|
1 | Obligatoire | Le access_token doit être automatiquement rafraîchi toutes les 90 minutes |
2 | Obligatoire | Le API d'authentification du concessionnaire access_token et refresh_token doivent être enregistrés et utilisés par tous les utilisateurs ayant la permission de gérer les commandes d’unités. |
3 | Obligatoire | Le API d'authentification du concessionnaire access_token doit être rafraîchi toutes les 2 heures en utilisant le refresh_token. |
4 | Optionnel | Le concessionnaire doit pouvoir trouver une commande d’unité en utilisant un numéro de bon de commande (PO). |
5 | Optionnel | Le concessionnaire doit pouvoir trouver une commande d’unité en utilisant un numéro de commande de vente. |
6 | Optionnel | Le concessionnaire peut charger manuellement des commandes d’unités en fournissant une plage de dates. |
7 | Obligatoire | Le DMS doit utiliser le service Get pour effectuer un chargement initial, récupérer toutes les commandes d’unités des 12 derniers mois et les enregistrer dans la base de données du DMS. |
8 | Obligatoire | Le service Get doit être utilisé quotidiennement pour récupérer les commandes d’unités des 30 derniers jours et les enregistrer dans la base de données du DMS. Elle est mise à jour si une commande d’unité existe déjà dans la base du DMS. |
9 | Obligatoire | Pour chaque commande d’unité, au minimum, les informations spécifiques BRP suivantes doivent être disponibles pour le concessionnaire :
|
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.
Validations
Les tests énuméré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.
👉 Pour exécuter les tests, vous avez besoin d’identifiants revendeur BOSSWeb dans l’environnement de test. Si vous ne les avez pas, ouvrez un ticket dans le Jira de DCP.
ID | Test | Résultat attendu |
|---|---|---|
1 | Récupérer les commandes d’unités créées au cours des 12 derniers mois. | Les commandes d’unités sont affichées dans le DMS, et les propriétés delivery_progress sont visibles. |
2 | Obtenir les commandes d’unités pour une ligne de produit prise en charge par le concessionnaire. | Les commandes d’unités sont affichées dans le DMS. |
3 | Obtenir une commande d’unité à l’aide du numéro de commande client. | Obtenir un numéro de commande client à partir des commandes d’unités chargées à l’étape 1. Récupérer la commande d’unité correspondante. |
4 | Obtenir une commande d’unité à l’aide du numéro de commande du concessionnaire (PO). | Obtenir un numéro de commande du concessionnaire à partir des commandes d’unités chargées à l’étape 1. Récupérer la commande d’unité correspondante. |
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 | Récupérer les commandes unitaires créées au cours des 12 derniers mois. |
Validation 2 | Les commandes unitaires sont actualisées quotidiennement et mises à disposition du 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 Units Order. 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 - Commandes d’Unités contient des exemples d’appels API pour obtenir les commandes d’unités d’un concessionnaire.