ERP et gestion commerciale : créer les articles, vérifier la compatibilité, facturer par client final

Où les données manquent dans le processus

Un fichier articles dans le commerce de pièces se construit rarement d’un bloc. Il grandit à partir de bons de livraison, d’étiquettes, de recherches catalogue et d’appels depuis l’entrepôt — et à chacun de ces points, quelque chose est aujourd’hui ressaisi, estimé ou laissé vide :

• Créer un article à partir d’une référence. La référence OE arrive de l’étiquette, du bon de livraison ou d’une photo, en plusieurs graphies. Savoir si 5Q0 919 275 C et 5Q0919275C sont le même article relève aujourd’hui du gestionnaire — voir Référence OE : bien lire une référence d’origine.
• Désignation, constructeur et type d’article. L’article s’appelle « capteur » parce que le champ devait être rempli. Une désignation documentée, un type d’article et la chaîne de remplacement manquent.
• Fixation du prix. Le prix de vente d’une pièce d’occasion est posé de mémoire, faute de base de comparaison dans le système.
• Compatibilité dans la commande. Un client commande cinq positions pour un véhicule, et leur compatibilité se règle au montage — ou au retour.
• Étiquettes à la réception. Référence fournisseur, référence OE et références croisées figurent sur l’étiquette et sont recopiées à la main dans le masque, voir Identification des pièces : de la dépose à la fiche vendable.

Ce que l’API fournit

Un déroulé de bout en bout

1. Réception : photographier l’étiquette. L’ERP envoie l’image à POST /scanner/label/extract-partnumbers et reçoit les références pièce et les références croisées. Ce qui n’est pas lisible sur l’image n’est pas renvoyé — l’analyse est facturée malgré tout, parce qu’elle a été effectuée.
2. Nettoyer la référence. GET /parts/oe/normalize met la référence lue sous sa forme de comparaison ; ambiguous et invalid vont dans une liste à clarifier, pas dans le fichier articles.
3. Créer l’article. GET /parts/oe/{oeNumber} renvoie 200 pour une correspondance confirmée, avec désignation, constructeur, type d’article et chaîne de remplacement ; 404 signifie aucune correspondance dans le référentiel OE, pas une erreur.
4. Proposer un prix. GET /parts/oe/{oeNumber}/price donne une évaluation indicative que le gestionnaire voit et confirme. Elle ne remplace pas la décision de prix.
5. Vérifier la commande. Avant la confirmation, l’ERP envoie le VIN et les positions OE à POST /vin/cart-check, avec mode=type pour le type de véhicule ou mode=vehicle pour le véhicule précis.
6. Publier. Pour les places de marché et documents multilingues, GET /translation/translations traduit la désignation ; l’article part en stock et en vente avec des champs documentés, voir Le stock en centre VHU : l’emplacement qui retrouve la pièce.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<NOM_CLIENT>",
    "externalReference": "erp-client-4711",
    "endpointKeys": ["parts.oe", "vin.cart_check"],
    "sponsorship": true
  }' \
  'https://api.tapinomahub.com/client/partner-workspaces'

L’intégration

1. Stocker la clé côté serveur. La X-Api-Key va dans la configuration de votre backend. Elle ne doit jamais atteindre un navigateur ou un bundle client — pas même « juste pour le test ».
2. Commencer par un point d’entrée. Pour un ERP, c’est presque toujours GET /parts/oe/{oeNumber} derrière la création d’article. L’ordre contrat, clé, processus, mise en production est décrit dans le guide d’intégration.
3. Définir la correspondance des champs. Désignation, constructeur, type d’article et chaîne de remplacement ont des cibles fixes dans le fichier ; le tapiGenArt reçoit un champ à part entière pour que filtres et places de marché puissent l’exploiter, voir Numéro GenArt : de quel genre de pièce s’agit-il ?.
4. Distinguer résultat vide et erreur. 404 sur la requête OE est un résultat métier : aucune correspondance confirmée. L’ERP crée l’article, laisse les champs vides et génère une tâche de clarification. Seule une erreur technique se réessaie.
5. Récupérer les réponses asynchrones. Les vérifications de panier peuvent répondre 202 avec Location et Retry-After. L’ERP mémorise l’identifiant du job et interroge GET /vin/cart-check/jobs/{jobId} au lieu de répéter l’appel.
6. Déployer. D’abord chez un client final, puis en largeur. GET /client/usage et, par espace, GET /client/users/{clientId}/usage montrent quels appels tournent et à quelle fréquence.

Points de vigilance

• Poser un `Idempotency-Key`. Sur les appels répétables comme la vérification de panier, l’en-tête protège des doubles imputations après un délai dépassé ; X-Tapinoma-Idempotent-Replay signale la relecture. Exception : POST /client/partner-workspaces émet une clé secrète une seule fois et n’est pas rejoué — après un délai dépassé, rapprocher l’existant au lieu de répéter à l’aveugle.
• Ne pas combler les champs vides. Si manufacturer, name ou listPrice revient à null, le champ du fichier reste vide et l’article reçoit une tâche de clarification. Une valeur par défaut dans le fichier articles est plus dangereuse qu’un manque visible.
• Conserver le `tapiId`. Quand un véhicule a été rapproché par un parcours VIN, le tapiId va dans le dossier véhicule ; GET /vehicles/{tapiId} en renvoie les données techniques dans le cadre de ce parcours facturé, sans VIN et sans équipements.
• Jamais la clé dans le navigateur. Un ERP web appelle lui aussi l’API depuis le backend ; le navigateur ne parle qu’à votre serveur.
• Fixer des limites par espace. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée, pour qu’un import défectueux chez un client final n’épuise pas le contingent de tous les autres.
• Faire vérifier le résultat. Évaluation de prix et indications de compatibilité sont la base d’une décision dans l’ERP, pas la décision. Le gestionnaire confirme, le système documente d’où vient une valeur.

Ce que l’API ne fait pas

L’API ne vend pas de base de données : ce qui est dû, c’est la requête et la restitution de son résultat ; la vérification avant usage incombe au client. L’évaluation de prix est indicative et sans garantie de prix. Les données véhicule du fournisseur 1 ne peuvent pas être appelées directement par des systèmes tiers : là, GET /vin/{vin}/vehicle répond redirect_required, et le rapprochement passe par une session navigateur issue de POST /vin/redirect-sessions, qui expire après dix minutes ; les fournisseurs 2 et 3 sont interrogeables directement. Une recherche du titulaire, une expertise ou un calcul de valeur résiduelle ne font pas partie de l’API. Et là où un champ n’est pas documenté, il reste null — l’API ne devine pas, et votre ERP ne devrait pas non plus.