API des livraisons

39 min

Commencer

L'API Deliveries 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 factures.

👉 Prenez le temps de lire la section Commande, Facture et Livraison : L'Histoire Complète pour des détails sur les commandes de pièces, les livraisons, la facturation, et comment utiliser les trois APIs pour tout relier !

L'API Deliveries permet au concessionnaire de récupérer un document de livraison avec les informations d'expédition à l'aide d'un numéro de livraison figurant sur le bordereau d'expédition ainsi que les informations de commande de pièces lorsque la commande a été expédiée.

L'API Deliveries fournit également un service permettant de récupérer une liste de documents de livraison pour un concessionnaire à l'aide d'un filtre.

❗ L'API Deliveries NE PEUT PAS être utilisée pour récupérer un document de livraison d'unité ❗

Par Où Commencer ? Lisez Ceci 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 :

Commencez ici avec la lecture obligatoire !
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 informations sur la manière d’obtenir de l’aide et sur Jira.
Commande, Facture et Livraison : L'Histoire Complète pour obtenir un aperçu du processus de commande et de livraison des pièces.

Résumé de l'entreprise

Sujet	Description
Portée	PA&A en Amérique du Nord
Scénarios	Module Commandes DMS : consulter les livraisons associées à une commande, gérer les quantités manquantes, obtenir les informations de suivi Module Service DMS : confirmer la réception des pièces pour une maintenance/réparation planifiée Suivi des commandes clients : faciliter le suivi des commandes/réparations
Fonctionnalités principales	Fournir les informations de suivi des expéditions de commande Fournir les informations du bon de livraison
Processus métier pris en charge	Processus de réception des marchandises en concession Gestion des stocks Suivi des ventes / services
Avantages pour les concessionnaires	Gestion des stocks de pièces (en transit) Mises à jour du suivi Faciliter la réception des marchandises
Avantages pour BRP	Augmentation de la satisfaction des concessionnaires Moins de tickets de support Économies sur les frais de retour

Informations techniques

Caractéristiques

Type d’API	Type DSP	Version DCP	Complexité
Obtenir des données depuis le 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 de l'application.

Vous avez besoin d'un jeton d'accès valide avant d'appeler cette API, ou vous devez appeler 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 : Livraison

Lorsqu’elle est appelée pour demander une liste de documents de livraison, l’API Deliveries renvoie un tableau de Livraison ressources. Chaque ressource Livraison présentée ci-dessous contient toutes les informations d’un document de livraison.

Lorsqu'elle est appelée pour obtenir un document de livraison spécifique, l'API Deliveries renvoie une seule ressource Delivery .

Représentation JSON

{
    "delivery_no": "8502015519",
    "dealer_no": "0000690885",
    "customer_address": {
        "street": "109 THOMAS DRIVE",
        "city": "AMERICUS",
        "state": "GA",
        "country": "US",
        "postal_code": "31709-5533"
    },
    "shipping_condition": "S1",
    "ship_to_no": "0020000953",
    "ship_to_address": {
        "street": "1601 S SLAPPEY BLVD",
        "city": "ALBANY",
        "state": "GA",
        "country": "US",
        "postal_code": "31701-2645"
    },
    "last_change_date": "2024-05-07T00:00:00Z",
    "items": [
        {
            "delivery_item_no": "000010",
            "product_code": "420686602",
            "product_description": "GASKET SET",
            "order_qty": 1,
            "delivery_qty": 1,
            "package_qty": 1,
            "sales_order_no": "1030969589",
            "sales_order_item_no": "007001",
            "dealer_po_no": "ODN041123",
            "tracking_details": [
                {
                    "tracking_no": "1Z7F7W950301444225",
                    "tracking_url": "https://wwwapps.ups.com/WebTracking/track?loc=en_US&AgreeToTermsAndConditions=yes&track.x=26&track.y=5&trackNums=1Z7F7W950301444225"
                }
            ]
        }
    ]
}

Propriétés

Tous les champs numériques avec des 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
delivery_no	String	Delivery number	Length: 10
dealer_no	String	Code representing the dealer number or other entity number who placed the order.	Length:10
customer_address	object	Delivery address
customer_address .street	string	Street address (1st line)	Max Length:60
customer_address .city	string	City	Max Length:40
customer_address .state	string	Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format.	Max Length:3
customer_address .country	string	Code that uniquely identifies a country, in ISO 3166-1 format.	Max Length:2
customer_address .postal_code	string	Postal code.	Max Length:10
ship_to_no	string	Code representing the customer or other entity number to which the goods are delivered.	Length:10
ship_to_address	object	Delivery address
ship_to_address .street	string	street address (1st line)	Max Length:60
ship_to_address .city	string	City	Max Length:40
ship_to_address .state	string	Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format.	Max Length:3
ship_to_address .country	string	Code that uniquely identifies a country, in ISO 3166-1 format.	Max Length:2
ship_to_address .postal_code	string	Postal code.	Max Length:10
shipping_condition	string	BRP custom code that uniquely identifies the shipping method for which the order is delivered. One value from the Shipping Method table.	Max Length: 2
last_change_date	string	Last date and time at which this resource has changed, in ISO 8601 UTC format.	Format: YYYY-MM-DDTHH:MM:SSZ
items	List of objects
items. delivery_item_no	string	Delivery item number.	Max Length: 6
items. product_code	string	Code that uniquely identifies a product.	Max Length: 18
items. product_description	string	The product description.	Max Length: 40
items. order_qty	number	Ordered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped.	Precision:1.00
items. delivery_qty	number	Delivered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped.	Precision:1.00
items. package_qty	number	Quantity in a package.	Precision:1.00
items. sales_order_no	string	Sales order document the item refers to.	Length:10
items. sales_order_item_no	string	Sales order document item number the item refers to.	Max Length:6
items. dealer_po_no	string	The number that the customer uses to uniquely identify a purchasing document.	Max Length: 35
items. tracking_details	List of objects
items. tracking_details. tracking_no	String	Tracking number from the carrier.	Max Length: 30
items. tracking_details. tracking_url	String	URL tracking number from the carrier.	Max Length: 300 for each URL tracking number

Méthodes d'expédition - Amérique du Nord

Code V3	Code V4	Description	Utilisation
01	S1	Sol accéléré	Mise à niveau de premier niveau à partir de l’expédition terrestre standard nationale : Service d’expédition : expédition terrestre standard. Habituellement des colis ou LTL expédiés par voie terrestre. Les frais de manutention du fret sont facturés aux clients.
02	S2	Véhicule immobilisé	Expédition la plus rapide disponible. Ceci est couramment utilisé lorsque les retards d’expédition sont critiques (scénarios de véhicule immobilisé) : Service d’expédition : le plus rapide possible, souvent appelé Express (Purolator) ou Next Day Air (UPS). Option de mise à niveau depuis la méthode d’expédition 01/S1. Les frais de manutention du fret sont facturés aux clients.
03	S3	Véhicule immobilisé Samedi	Identique à Véhicule immobilisé avec la possibilité d’être reçu un samedi.

Méthodes d'expédition - International

Organisation commerciale	Code V3	Description
6030 - Scandinavie	50	itella
6030 - Scandinavie	51	posten_logistik
6030 - Scandinavie	52	sol
6030 - Scandinavie	53	air
6030 - Scandinavie	54	sol
6030 - Scandinavie	55	air
6030 - Scandinavie	59	sol
6030 - Scandinavie	60	air
6050 - Europe (EMEA)	30	régulier
6050 - Europe (EMEA)	33	urgent
7080 - Asie-Pacifique (APAC)	38	régulier
7080 - Asie-Pacifique (APAC)	39	urgent
7080 - Asie-Pacifique (APAC)	40	régulier
7080 - Asie-Pacifique (APAC)	82	stock
7080 - Asie-Pacifique (APAC)	90	stock
8070 - Mexique	92	régulier
8070 - Mexique	93	air
8070 - Mexique	94	urgent
8075 - Brésil	63	aereo_azul_cargo
8075 - Brésil	77	sedex_correios
8075 - Brésil	78	padrao_rodoviario

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.

Document de livraison pour un concessionnaire

Un concessionnaire ne peut récupérer qu’un seul de ses documents de livraison. Le paramètre d’en-tête Dealer-Number doit identifier le concessionnaire qui demande le document, et l’API renvoie uniquement le document de livraison pour ce concessionnaire appelant.

Délai d’expiration lors de l’appel pour obtenir

L’API Deliveries propose le service LISTE pour récupérer les livraisons en fonction de certains critères, comme une plage de dates.

❗ Dans certains cas, les critères utilisés pour l’appel au service LIST peuvent sélectionner trop de documents de livraison, et l’API renvoie un délai d’expiration ❗

👉 Votre DMS doit gérer le délai d’expiration et afficher un message d’erreur demandant au concessionnaire de réduire la plage de dates.

Lorsque la quantité commandée et la quantité livrée sont à 0

Dans certains cas, les propriétés order_qty et delivery_qty sont à 0. Cela se produit lorsqu’une livraison est créée mais n’est pas prête à être expédiée.

Par exemple, cette livraison a les propriétés order_qty et delivery_qty à 0.

{
    "delivery_no": "8502072259",
    "dealer_no": "0000690885",
    "customer_address": {
        "street": "109 THOMAS DRIVE",
        "city": "AMERICUS",
        "state": "GA",
        "country": "US",
        "postal_code": "31709-5533"
    },
    "shipping_condition": "S1",
    "ship_to_no": "0020000953",
    "ship_to_address": {
        "street": "1601 S SLAPPEY BLVD",
        "city": "ALBANY",
        "state": "GA",
        "country": "US",
        "postal_code": "31701-2645"
    },
    "last_change_date": "2024-05-24T00:00:00Z",
    "items": [
        {
            "delivery_item_no": "000010",
            "product_code": "9779426",
            "product_description": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
            "order_qty": 0,
            "delivery_qty": 0,
            "package_qty": 3,
            "sales_order_no": "1030997804",
            "sales_order_item_no": "012208",
            "dealer_po_no": "ODN041256",
            "tracking_details": []
        }
    ]
}

La propriété deliveries de la commande de pièces correspondante indique que l’état de la pièce est alloué, ce qui signifie qu’elle n’a pas été expédiée.

Ces livraisons peuvent être ignorées parce que le concessionnaire ne les a pas reçues.

{
    "ordered_line": {
        "item_id": "5DCAC1B678131EEF84D74B96E2BBC46A",
        "item_no": "012200",
        "product_code": "9779426",
        "product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
        "order_qty": 3,
        "dealer_po_item_no": "",
        "dealer_product_code": "",
        "sales_uom": "PC",
        "min_order_qty": 1,
        "is_sales_bom": false,
        "product_line": "SNO",
        "product_type": "110",
        "texts": []
    },
    "shipping_lines": [
        {
            "item_no": "012216",
            "product_code": "9779426",
            "product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
            "ship_qty": 3,
            "sales_uom": "PC",
            "price_uom": "PC",
            "package_uom": "CS",
            "in_package": {
                "qty": 3,
                "uom": "PC"
            },
            "package_count": 3,
            "msrp_unit_price": 56.99,
            "wholesale_unit_price": 36.98,
            "net_unit_price": 37.02,
            "currency": "USD",
            "is_substitute_product": false,
            "substituted_product_code": null,
            "product_line": "SNO",
            "product_type": "110",
            "plant": {
                "name": "BRP - LAS VEGAS",
                "city": "LAS VEGAS",
                "state": "NV",
                "country": "US"
            },
            "pricings": [
                {
                    "condition_type": "gross_amt",
                    "total_amount": 110.94,
                    "currency": "USD"
                },
                {
                    "condition_type": "subtotal_amt",
                    "total_amount": 111.05,
                    "currency": "USD"
                },
                {
                    "condition_type": "tax_amt",
                    "total_amount": 8.88,
                    "currency": "USD"
                },
                {
                    "condition_type": "handling_fee",
                    "total_amount": 0.11,
                    "currency": "USD"
                }
            ],
            "deliveries": [
                {
                    "status_code": "allocated",
                    "status_date": "2024-07-06T20:20:34Z",
                    "status_descr": "",
                    "qty": 3,
                    "availability_date": "2024-07-15",
                    "no": "",
                    "item_no": "",
                    "delivery_qty": 0,
                    "creation_date": "",
                    "carrier_name": "",
                    "split_delivery_no": "",
                    "split_delivery_item_no": "",
                    "trackings": [],
                    "billings": []
                }
            ],
            "statuses": [
                {
                    "type": "success",
                    "code": "in_process",
                    "descr": "Your part is in process"
                }
            ]
        }
    ]
}

Référence API

Get a Delivery Document

Get a delivery document using the delivery number.

GET

/delivery/{delivery_no}

curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502022612' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obtenir les documents de livraison

Obtenir une liste de documents de livraison.

GET

/deliveries

curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--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 un document de livraison pour trouver une commande de pièces

En utilisant le numéro de livraison, vous pouvez obtenir un document de livraison spécifique. Par exemple, lors de la réception d’un colis, le concessionnaire saisit le numéro de livraison figurant sur l’étiquette d’expédition pour trouver le document de livraison.

Une fois le document de livraison trouvé, le concessionnaire peut utiliser le numéro de commande de vente (sales_order_no) pour trouver la commande de pièces associée.

Obtenir le document de livraison

curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502022612' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'

Obtenir la commande de pièces

Get the Parts Order

curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1030971827&dealer_no=0000690005' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'

Obtenir les documents de livraison pour une période

Obtenir les documents de livraison pour une plage de dates.

Get the Delivery Documents for a Period

curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--header 'Dealer-Number: 0000690885' \
--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 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 durant 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 présentés dans le tableau ci-dessous.

Réponse	Résolution
Renvoyé si le Dealer-Number est manquant dans l’en-tête. { "status": "400", "id": "rrt-00a574511a562afb5-b-ea-22208-1683284-1", "title": "mauvaise_requete", "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 '/deliveries' mais est introuvable dans la requête.: []" } ] } } }	Mettez à jour votre appel API pour ajouter le paramètre Dealer-Number dans l’en-tête.
Renvoyé si le numéro de livraison est manquant dans la requête. { "status": "400", "id": "rrt-00a574511a562afb5-b-ea-22209-1683475-1", "title": "mauvaise_requete", "meta": { "service": "00", "detail": "Chemin introuvable." } }	Assurez-vous d’inclure un numéro de livraison dans le chemin de la requête.
Renvoyé si le numéro de concessionnaire est invalide { "status": "400", "id": "rrt-023ba21d3844ea361-c-ea-4985-19207929-2.1", "title": "mauvaise_requete", "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 de l’inventaire des pièces. Assurez-vous que le numéro de concessionnaire compte 10 caractères. Si vous enregistrez le numéro sans le ‘0’ initial, ajoutez ce ‘0’ avant d’appeler l’API.

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 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 numéro de livraison est introuvable.

{
    "status": "404",
    "id": "rrt-00a574511a562afb5-b-ea-22209-1683823-1.1",
    "title": "not_found",
    "meta": {
        "service": "97",
        "detail": "Delivery 8500045713 not found."
    }
}

Le concessionnaire a peut-être fait une erreur en saisissant le numéro de livraison. 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 un document de livraison en utilisant un numéro de livraison.
2	Obligatoire	Le document de livraison doit être affiché au concessionnaire.
3	Obligatoire	Le concessionnaire doit pouvoir ouvrir une commande de pièces en utilisant le numéro de commande client (sales_order_no) trouvé dans un document de livraison.
4	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.
5	Optionnel	Le DMS récupère les documents de livraison des 3 derniers mois et les enregistre dans la base de données du DMS. Le concessionnaire peut consulter les documents de livraison chargés.
6	Optionnel	Le concessionnaire peut trouver un document de livraison en utilisant le numéro de suivi du transporteur.
7	Optionnel	Le service Get est utilisé quotidiennement pour récupérer les livraisons des 30 derniers jours et les enregistrer dans la base de données du DMS.

Activités de certification

Cette section présente toutes les activités de certification et les validations qui doivent être réalisées pour certifier l'API.

Assurance qualité

Les tests répertoriés dans le tableau ci‑dessous doivent être effectués 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 le document de livraison 8502067956	Le document de livraison est chargé et affiché.
2	Obtenir la liste des documents de livraison pour la période du 2023‑06‑20 au 2023‑09‑25	Une liste de 15 documents de livraison est chargée.
3	Trouver la commande de pièces avec le numéro de commande de vente indiqué dans le document de livraison 8502067956	La commande de pièces est trouvée et affichée.

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	Fournir une liste de 10 à 20 numéros de livraison provenant des livraisons reçues par le concessionnaire. Fournir une capture d’écran ou effectuer une démonstration en direct pour afficher au moins 10 documents de livraison tels que vus par le concessionnaire.
Validation 2	Fournir les numéros de commande client (commande de pièces) extraits des documents de livraison de l’étape 1. Fournir une capture d’écran ou effectuer une démonstration en direct pour afficher la commande de pièces liée à au moins 10 documents de livraison, telle que vue 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 Deliveries. Cet environnement Postman contient des variables utilisées par les requêtes et est configuré pour se connecter à l'environnement de test.

Test - Environnement DSP

Collections

La collection DMS - Deliveries contient des exemples d'appels API pour récupérer des documents de livraison.

DMS - Livraisons

Journal des modifications

Révision 1.1

Fixed

Renommé customer_po_no en dealer_po_no pour être aligné avec les autres APIs.

Révision 1.0

Added

Première version