API des factures
activités de certification et validations requises Pour bien commencer
L’API des factures fait partie de la triade d’APIs liées à la gestion des commandes de pièces, accessoires et vêtements (PA&A), les deux autres étant l’API de commande de pièces et l’API des livraisons.
👉 Prenez le temps de lire la section Commande, Facture et Livraison : L'Histoire Complète pour connaître les détails sur les commandes de pièces, les livraisons, la facturation, et comment utiliser les trois APIs pour tout relier !
L’API des factures permet aux concessionnaires de récupérer une facture en utilisant le numéro de facture trouvé dans les informations de commande de pièces, qui apparaît également sur la facture envoyée par BRP.
L’API des factures fournit également un service permettant de récupérer une liste de factures pour un concessionnaire en utilisant un filtre.
L’API des factures peut être utilisée pour récupérer une unité facture.
🛑 Les factures d’unités retournées sont celles entre BRP et le concessionnaire !
👉 Ce sont les factures envoyées au concessionnaire lorsque celui-ci achète des unités auprès de BRP.
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 des détails sur l'authentification et les identifiants.
- Commande, Facture et Livraison : L'Histoire Complète pour avoir une vue d’ensemble du processus de commande et de livraison des pièces.
Résumé de l'entreprise
Sujet | Description |
|---|---|
Portée | Unité et PA&A (Amérique du Nord) |
Scénarios |
|
Fonctionnalités principales |
|
Processus opérationnels 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 BRP | | | Un 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 : Facture
Lorsqu’elle est appelée pour demander une liste de factures, l’API des Factures retourne un tableau de ressources Facture. Chaque ressource Facture, présentée ci-dessous, contient toutes les informations sur une facture.
Lorsque vous appelez pour récupérer une facture spécifique, l’API des Factures retourne une seule ressource Facture.
Représentation JSON
{
"dealer_no": "0000690885",
"invoice_type": "ZF2P",
"invoice_no": "9060858271",
"invoice_date": "2024-03-20",
"payer": "0000690885",
"tax_amount_value": 0,
"invoice_total": 302.97,
"currency": "USD",
"credit_indicator": false,
"is_cancelled": false,
"items": [
{
"item_no": "003202",
"product_code": "705009190",
"sales_order_no": "1030902201",
"sales_order_item_no": "003202",
"delivery_no": "8501841899",
"delivery_item_no": "000010",
"quantity": 12,
"gross_value": 167.76,
"discount_value": 0,
"net_value": 167.94,
"surcharge_value": 0,
"handling_fees_value": 0.18,
"freight_value": 0,
"consignment_fees_value": 0,
"other_fees_value": 0
},
{
"item_no": "004101",
"product_code": "705010334",
"sales_order_no": "1030902201",
"sales_order_item_no": "004101",
"delivery_no": "8501841899",
"delivery_item_no": "000020",
"quantity": 6,
"gross_value": 134.88,
"discount_value": 0,
"net_value": 135.03,
"surcharge_value": 0,
"handling_fees_value": 0.15,
"freight_value": 0,
"consignment_fees_value": 0,
"other_fees_value": 0
}
],
"last_change_date": "2024-03-20T22:00:42Z"
}Propriétés
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.
Property | Type | Definition | Notes |
|---|---|---|---|
dealer_no | string | Code that represents the dealer number or other entity number. | Length:10 |
invoice_no | string | Invoice number | Length:10 |
invoice_type | string | Type of invoice. The available values are listed in the Invoice Type table below. |
|
invoice_date | date | The date the sales transaction was billed in ISO 8601 format. | yyyy-mm-dd
|
payer | string | Customer Number (Payer). | Length:10 |
tax_amount_value | number | Total tax amount value of the invoice. | Precision: 0.01 |
invoice_total | number | Total net value of the billing document. | Precision: 0.01 |
currency | string | Document currency. The available values are listed in the Currency table below. | Max Length:3 |
credit_indicator | boolean | Indicates if the invoice is a credit. Value can be true or false. |
|
is_cancelled | boolean | Indicates if the invoice has been canceled. Value can be true or false. |
|
last_change_date | String | Date when the last change was made. | Format: YYYY-MM-DDTHH:MM:SSZ |
items | List of objects |
|
|
items.item_no | string | Item number. |
|
items.product_code | string | Code that uniquely identifies a product. | Max Length: 18 |
items.sales_order_no | string | The sales order document that the item refers to. | Max Length:10 |
items.sales_order_item_no | string | The item in the sales order document that the invoice item refers to. | Max Length:10 |
items.delivery_no | string | The delivery number for the invoiced item. | Max Length: 10 |
items.delivery_item_no | string | The delivery number document that the item refers to. | Max Length: 10 |
items.quantity | number | Invoiced quantity in a sales unit of measure. | Precision: 0.001 |
items.gross_value | number | The gross value of the invoiced item. | Precision: 0.01 |
items.discount_value | number | Discount value of the invoiced item. | Precision: 0.01 |
items.net_value | number | Net value of the invoiced item. | Precision: 0.01 |
items.surcharge_value | number | Surcharge amount. | Precision: 0.01 |
items.handling_fees_value | number | Handling fees. | Precision: 0.01 |
items.freight_value | number | Freight value.
| Precision: 0.01 |
items. consignment_fees_value | number | Consignment fees value. | Precision: 0.01 |
items.other_fees_value | number | Other fee value. | Precision: 0.01 |
Types de facture
Code | Description |
|---|---|
ZCBR | Avoir pour un retour |
ZF2F | Facture pour une unité |
ZF2P | Facture pour une commande PA&A |
ZF2S | Facture de service |
ZF2W | Facture de garantie étendue (BEST) |
ZG2 | Avoir |
ZG2R | Avoir - retour |
ZG2W | Avoir - garantie |
ZL2 | Note de débit |
ZL2W | Note de débit - garantie |
ZREP | Crédit pour retours |
ZREV | Retour véhicule |
ZS1 | Annulation de facture |
ZS1C | Annulation de note de débit |
ZS1W | Annuler facture - garantie |
ZS2 | Annulation d’avoir |
ZS2W | Annuler avoir - garantie |
ZVG2 | Avoir - promotions |
ZVL2 | Note de débit - promotions |
ZVS1 | Annulation de facture - promotions |
ZVS2 | Annulation d’avoir - promotions |
Limitations et contraintes
Format des nombres
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.
Factures pour un revendeur
Un revendeur peut uniquement récupérer l’une de ses factures. Le paramètre d’en-tête Dealer-Number doit identifier le revendeur demandant les factures, et l’API renvoie uniquement les factures de ce revendeur.
Délai d’expiration lors de l’appel à Get
L’API de factures fournit le service LISTE pour récupérer les factures selon une plage de dates.
❗ Dans certains cas, les critères utilisés pour l’appel au service LIST peuvent sélectionner trop de factures, et l’API renvoie un délai d’attente dépassé (timeout) ❗
👉 Votre DMS doit gérer le timeout et afficher un message d’erreur demandant au concessionnaire de réduire la plage de dates.
Référence de l'API
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9060858271' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338.pdf'
--header 'Dealer-Number: 00006908855' \
--header 'Authorization: Bearer REPLACE_ME'
curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2024-06-01'&limit=2 \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Comment faire
Cette section fournit des informations sur la manière d’obtenir des résultats spécifiques avec l’API.
Obtenir une facture pour trouver une commande de pièces
En utilisant le numéro de facture, obtenez une facture spécifique. Une fois la facture trouvée, le concessionnaire peut utiliser le numéro de commande client (sales_order_no) pour trouver la commande de pièces associée.
Obtenir la facture
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir la commande de pièces
👉 Cette commande de pièces contient 116 articles, et un résumé est présenté.
curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir une facture pour trouver une livraison
À l’aide du numéro de facture, obtenez une facture spécifique. Une fois la facture trouvée, le concessionnaire peut utiliser le numéro de livraison (delivery_no) pour trouver la livraison correspondante.
👉 À partir du numéro de livraison, la commande de pièces correspondante peut être trouvée, comme décrit dans la section Obtenir un document de livraison pour trouver une commande de pièces
Obtenir la facture
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061023211' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir la livraison
curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502015519' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir la facture pour une livraison
Obtenir une facture à l’aide d’un numéro de livraison.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'Obtenir les factures pour les numéros de livraison
Obtenir une liste de factures à l'aide d'une liste de numéros de livraison.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312,8503004404,8503003809' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'Obtenir les factures pour une période
Obtenir les factures pour une plage de dates.
curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-05-01&invoice_date_to=2025-05-10&limit=3' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Obtenir une facture pour une unité
L’API de facturation peut être utilisée pour obtenir les factures des unités. L’appel se fait également en utilisant le numéro de facture.
👉 Les factures renvoyées sont envoyées par BRP au concessionnaire lorsque celui‑ci achète des unités auprès de BRP.
❗ Ce ne sont pas les factures des clients ❗
🚗 Les factures unitaires sont identifiées par le type de facture ZF2F.
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061034465' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Obtenir des factures d’un type spécifique
Lors de l’appel à l’endpoint Obtenir des factures , le paramètre invoice_type peut être utilisé pour demander des factures d’un type spécifique.
Les valeurs valides sont :
- pièces: renvoie les factures de type ZF2P.
- unités: renvoie les factures de type ZF2F.
- service: renvoie les factures de type ZF2S.
❗ Lors de l'utilisation du invoice_type filtre, SEULEMENT les factures répertoriées ci-dessus sont renvoyées.
L'exemple ci-dessous montre un appel pour obtenir uniquement les factures de pièces.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-20&limit=2&invoice_type=parts' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME' Obtenir des factures avec une liste de types
Lors de l'appel de l'Obtenir des factures point de terminaison, le invoice_types paramètre peut être utilisé pour demander des factures de types spécifiques.
Le paramètre prend une liste de types de factures, séparés par une virgule. L’API des factures renvoie les factures avec les types demandés.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-01&limit=3&invoice_types=ZCBR%2C%20ZF2F%2C%20ZF2P%2C%20ZF2S%2C%20ZF2W%2C%20ZG2%2C%20ZG2R%2C%20ZG2W%2C%20ZL2%2CZL2W%2CZREP%2C%20%20ZREV%2C%20ZS1%2C%20ZS1C%2C%20ZS1W%2C%20ZS2%2C%20ZS2W%2C%20ZVG2%2C%20ZVL2%2C%20ZVS1%2C%20ZVS2' \
--header 'Dealer-Number: 0000690005' \
--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 rencontré lors du développement et de l'intégration, et il ne devrait pas être reçu pendant les 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 |
|---|---|
Retourné si le paramètre d’en‑tête Dealer-Number est manquant. {
"status": "400",
"id": "rrt-074faba1d0796ac77-c-ea-24396-616154-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 '/invoices' mais n'a pas été trouvé dans la requête."
}
]
}
}
} | Mettez à jour votre appel API pour ajouter le paramètre Dealer-Number dans l’en‑tête. |
Retourné si le numéro de facture est manquant dans la requête. {
"status": "400",
"id": "rrt-074faba1d0796ac77-c-ea-24397-616812-1",
"title": "bad_request",
"meta": {
"service": "00",
"detail": "Chemin introuvable."
}
} | Assurez-vous d’inclure un numéro de facture dans le chemin de requête. |
✏Retourné si le numéro de concessionnaire est invalide. {
"status": "400",
"id": "rrt-023ba21d3844ea361-c-ea-4985-19207929-2.1",
"title": "bad_request",
"meta": {
"service": "19",
"detail": "Numéro de concessionnaire invalide"
}
} | 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. |
401 Non autorisé
Le code d’erreur 401 Unauthorized est renvoyé lorsque vous essayez d’appeler l’API avec un access_token expiré.
Vous devez obtenir un nouvel access_token en effectuant 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 numéro de facture est introuvable.
{
"status": "404",
"id": "rrt-074faba1d0796ac77-c-ea-24396-616988-1.1",
"title": "not_found",
"meta": {
"service": "97",
"detail": "Invoice 9060002826 not found."
}
}Le revendeur a peut-être fait une erreur en saisissant le numéro de facture. Vous devez signaler l’erreur à l’utilisateur afin qu’il puisse réessayer.
Exigences DSP
Exigences fonctionnelles
ID | Type | Exigence |
|---|---|---|
1 | Obligatoire | Le concessionnaire doit pouvoir rechercher une facture en utilisant un numéro de facture. |
2 | Obligatoire | La facture doit être affichée au concessionnaire. |
3 | Obligatoire | Le concessionnaire doit pouvoir ouvrir une commande de pièces en utilisant le numéro de commande (sales_order_no) trouvé dans une facture. |
4 | Obligatoire | Le concessionnaire doit pouvoir ouvrir un document de livraison en utilisant le numéro de livraison (delivery_no) trouvé dans une facture. |
5 | Obligatoire | Le paramètre d’en-tête Dealer-Number doit être défini sur le numéro BRP du concessionnaire, et celui-ci ne peut pas le modifier. |
6 | Optionnel | Le DMS récupère les factures des 3 derniers mois et les enregistre dans la base de données du DMS. Le concessionnaire peut consulter les factures chargées. |
7 | Optionnel | Le concessionnaire peut demander la version PDF d’une facture en utilisant un numéro de facture. |
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éussis dans l’environnement de test avant que vous puissiez commencer la phase pilote concessionnaire.
Pour ces tests, nous devons utiliser le numéro de concessionnaire 0000690005
ID | Test | Résultat attendu |
|---|---|---|
1 | Obtenir la facture 9061863617 | La facture est chargée et affichée. |
2 | Obtenir la liste des factures avec la plage de dates du 2053-01-01 au 2026-03-01 | Une liste de 21 factures est chargée. |
3 | Trouver la commande de pièces avec le numéro de commande trouvé dans le document de facture 9061863617 | La commande de pièces est trouvée et affichée. |
4 | Obtenir le fichier PDF pour la facture 9061860929 (Optionnel) | Le fichier PDF de la facture est chargé. |
Pilote concessionnaire
Le tableau ci-dessous décrit les paramètres et les validations du pilote concessionnaire.
Paramètre | Valeur |
|---|---|
Environnement | Production |
Nombre de concessionnaires | 1 à 3 |
Durée | 1 semaine |
Validation 1 | Fournir une liste de 10 à 20 factures provenant des factures reçues par le concessionnaire. Fournir la capture d’écran ou effectuer une démonstration en direct pour afficher au moins 10 factures telles que vues par le concessionnaire. |
Validation 2 | Fournir les numéros de commande (commande de pièces) extraits des factures de l’étape 1. Fournir la capture d’écran ou effectuer une démonstration en direct pour afficher la commande de pièces liée à au moins 10 factures telles que vues 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 tester l'API Invoices. Cet environnement Postman contient les variables utilisées par les requêtes et est configuré pour se connecter à l'environnement de test.
Collections
La collection DMS - Invoices contient des exemples d’appels API pour récupérer des factures.