Commencer
L'API de commande de pièces permet au concessionnaire de passer une commande de pièces, accessoires et vêtements (PA&A) depuis son DMS au lieu d'aller sur BOSSWeb.
BOSSWeb et l' API de commande de pièces utilisent la même API interne pour créer la commande dans SAP.
L' API de commande de pièces offre 6 services :
- VALIDER pour valider la commande avant de la créer.
- CRÉER pour créer la commande.
- VÉRIFIER pour vérifier l'état de création d'une commande.
- OBTENIR pour obtenir une ou plusieurs commandes en fonction des paramètres de requête.
- ANNULER pour annuler un ou plusieurs articles de ligne qui n'ont pas encore été traités.
- COMMANDES EN RETARD pour obtenir les commandes de pièces avec au moins une pièce en retard.
Commande de pièces dans BOSSWeb
Si vos concessionnaires demandent, l'API de commande de pièces est utilisée uniquement pour les Commandes Quotidiennes dans BOSSWeb.
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.
- Commande, Facture et Livraison : L'Histoire Complète pour obtenir un aperçu du processus de commande et de livraison des pièces.
Dépendances
Pour appeler l'API de commande de pièces, vous avez besoin d'une access_token d'authentification de concessionnaire obtenue à partir de l' API d'authentification du concessionnaire.
Un access_token d'authentification de concessionnaire est requis car l'API travaille avec des commandes de pièces et avec 💲💲
L'API de commande de pièces dépend des données récupérées à partir d'autres API DCP, à savoir:
- API des concessionnaires pour récupérer les méthodes d'expédition autorisées pour le concessionnaire.
Il existe également une relation entre l'API de commande de pièces et les API suivantes:
- API d'inventaire des pièces du concessionnaire pour rechercher une pièce dans l'inventaire des concessionnaires.
Limitations importantes
Dans la version actuelle de l'API de commande de pièces et avec la limitation des systèmes backend, il y a une limite de 25 lignes d'articles.
Si une commande de pièces a plus de 25 à 30 lignes d'articles, le Valider et Créer service renvoie une erreur 504 Gateway Timeout.
Le délai d'attente est causé par le système backend, qui prend plus de temps pour créer la commande de pièces que la valeur de délai d'attente dans l'API de commande de pièces (et cette valeur de délai d'attente ne peut pas être changée. Ne me lancez pas là-dessus.)
Voir la Vérifier le flux de données section pour des informations sur la façon de gérer le délai d'attente.
Commande de pièces avec kit
Un kit (ou BOM dans le jargon de BRP) est un numéro de pièce qui représente un ensemble de pièces vendues et expédiées ensemble.
Différences importantes entre V3 et V4
Il existe des différences petites mais importantes entre les versions V3 et V4 de l'API de commande de pièces.
ID de commande PAC
Dans la réponse renvoyée par le Create service, la première propriété est le pac_order_id.
Le pac_order_id est l'identifiant unique pour la commande de pièces utilisé par SAP.
Dans la V3 version, la valeur GUID fournie par votre DMS dans la pac_order_id propriété est utilisée par SAP et renvoyée dans les réponses Validate et Create .
Dans la V4 version, SAP utilise la valeur GUID fournie par votre DMS dans la pac_order_id propriété et la renvoie dans la réponse Validate .
Cependant, SAP renvoie une valeur différente dans la réponse Create.
🛑 Le pac_order_id propriété retournée dans le Create réponse doit être sauvegardée car elle est nécessaire pour identifier la commande de pièces dans un appel aux Cancel et Get services.
Numéro de commande de vente
La sales_order_no propriété contient le numéro du document de vente que le concessionnaire peut utiliser pour suivre la commande.
Dans la V3 version de l'API, la sales_order_no propriété est répétée dans chaque objet de ligne d'article.
Dans la V4 version de l'API, la sales_order_no propriété se trouve uniquement dans l'en-tête.
ID de ligne d'article commandée
La item_idpropriété d'un article identifie de manière unique l'article dans SAP dans toutes les commandes.
Dans la V3 version, la valeur GUID fournie par votre DMS dans la item_id propriété est utilisée par SAP et retournée dans les Validate et Create réponses.
Dans la V4 version, SAP utilise la valeur GUID fournie par votre DMS dans la item_id propriété et la retourne dans la Validate réponse.
Cependant, SAP retourne une valeur différente dans la réponse Create.
🛑 Le item_id propriété retournée dans le Create réponse doit être sauvegardée car elle est nécessaire pour identifier la commande de pièces dans un appel aux services Cancel et Get .
Flux de données de haut niveau
Les sections suivantes présentent le flux de données de haut niveau pour les services fournis par l'API de commande de pièces.
Ces flux de données sont destinés à introduire les services de l'API de commande de pièces ; ils ne sont pas complets, et de nombreux détails sont documentés plus tard dans les autres sections.
L' API d'authentification du concessionnaire appel pour authentifier le concessionnaire n'est pas montré sur les diagrammes.
Valider/Créer le flux de données
Le diagramme ci-dessous décrit le flux de données qui simule et crée une commande de pièces.
Les informations provenant de l' API des concessionnaires et API des pièces sont nécessaires pour une commande de pièces. Lors de la création d'une commande de pièces, le concessionnaire doit sélectionner un mode d'expédition dans la liste disponible. La liste des modes d'expédition valides est retournée par l' API des concessionnaires.
Des frais d'expédition supplémentaires seront facturés pour certains modes d'expédition. D'autres conditions de commande, comme la valeur totale de la commande, peuvent également entraîner des frais supplémentaires.
C'est pourquoi le Validate service doit être appelé avant le Create service. Le service Validate retourne les mêmes informations de commande de pièces que le Create et permet au concessionnaire d'apporter des modifications avant de soumettre la commande.
L'API de commande de pièces valide la commande, et s'il y a des coûts supplémentaires à facturer, la charge utile retournée contient un ou plusieurs messages d'avertissement, par exemple :
Des frais d'expédition supplémentaires seront facturés avec ce mode de livraison Votre commande PAC est inférieure à 150,00$, des frais de traitement de 20,00$ seront appliqués à la facture.
Ces messages d'avertissement doivent être affichés au concessionnaire. Après avoir consulté les avertissements, le concessionnaire peut décider d'accepter les coûts supplémentaires et de créer la commande ou d'annuler la commande.
Notez que l'API de commande de pièces retourne également ces avertissements lorsque le Créer service est appelé, mais il est trop tard car la commande a déjà été créée.
Le Valider service permet également au concessionnaire de gérer les pièces en rupture de stock.
Par exemple, la réponse Valider peut indiquer qu'une pièce est en rupture de stock avec BRP. Le concessionnaire peut décider d'utiliser le API d'inventaire des pièces du concessionnaire service de localisation des pièces pour essayer de trouver la pièce dans l'inventaire d'un concessionnaire. Si une pièce est trouvée, elle peut être retirée de la commande.
En résumé, vous devez toujours appeler le service Valider avant le service Créer pour valider la commande et les coûts supplémentaires.
Dans votre DMS, le bouton soumettre/créer ne doit pas être activé si la validation n'a pas été effectuée pour toutes les commandes de pièces.
Tous les messages d'avertissement retournés dans la charge utile Valider doivent être affichés au concessionnaire. Après que les messages d'avertissement ont été montrés, une confirmation du concessionnaire doit être demandée avant que la commande ne soit créée.
Vérifier le flux de données
Le Vérifier service récupère le statut d'une commande de pièces. L'appel gère principalement l'erreur 504 Gateway Timeout que l'API de commande de pièces retourne lorsque la commande a plus de 25 lignes.
Lorsque l'API de commande de pièces Créer renvoie un délai d'attente, l'idée est d'attendre quelques minutes puis d'appeler le Vérifier service pour vérifier si la commande a été créée.
Le temps d'attente peut être calculé en multipliant le nombre d'articles par 3 secondes.
Si le Vérifier service renvoie une erreur, attendez une autre période et appelez à nouveau le Vérifier service jusqu'à ce que la commande soit créée ou que vous ayez atteint un nombre maximum de tentatives (pour éviter une boucle infinie).
Lorsque la commande est créée, le Vérifier service renvoie les informations de la commande créée qui peuvent être enregistrées dans votre base de données DMS.
Obtenir le flux de données
Le service Obtenir récupère une ou plusieurs commandes de pièces en fonction de critères. La recherche peut être effectuée sur :
- L'ID de la commande.
- Le numéro de commande d'achat du concessionnaire.
- Le statut de la commande.
- La date de création de la commande.
- Le type de commande.
Le Obtenir service doit être utilisé pour mettre à jour une commande tant qu'elle est ouverte.
Il faut un moment pour compléter le traitement de la commande dans le backend, donc lorsque le service Créer renvoie le charge utile de la commande, toutes les informations ne sont pas disponibles.
Par exemple, les informations de livraison sont généralement indisponibles dans la charge utile renvoyée par le Créer service car elles ne sont disponibles que lorsque les pièces sont traitées.
Une approche consiste à appeler le Get service pour actualiser les informations de commande lorsqu'elles sont affichées au concessionnaire.
👉Un appel au Get service pour récupérer une liste de commandes de pièces, par exemple, en utilisant une plage de dates, renvoie également les commandes de pièces créées par le concessionnaire dans BOSSWeb.
❗❗ Le Get service est essentiel pour aider le concessionnaire dans son processus de réception des commandes de pièces. ❗❗
Si les commandes de pièces ne sont pas chargées et mises à jour dans votre base de données DMS, le API des livraisons et API des factures ne peuvent pas être utilisés pour lier les pièces reçues aux commandes de pièces.
Annuler le flux de données
Le Cancel service vous permet d'annuler des articles qui sont en rupture de stock dans une commande de pièces.
Notez qu'un article de commande en rupture de stock expédié ou partiellement expédié ne peut pas être annulé via l'API.
❗ ❗ Il est important d'appeler le Get service pour mettre à jour la commande et afficher au concessionnaire les dernières informations de commande ❗ ❗
Rappelez-vous que seuls les articles en rupture de stock peuvent être annulés.
