La plupart des intégrations n’échouent pas sur la technique. Elles échouent parce que personne n’a décidé où va un champ de réponse, ce que signifie un champ vide et qui tranche quand deux sources se contredisent. Ce texte décrit l’intégration que l’on construit une fois et que l’on ne fait ensuite qu’étendre — quel que soit l’ERP en place.
Les quatre flux de données d’un recycleur
- Véhicule entrant. Saisir le VIN, rapprocher le véhicule, créer le dossier. Une fois par véhicule, au début de la chaîne.
- Pièces sortantes. Liste des pièces, sélection des positions à déposer, entrée en stock par exemplaire.
- Commercialisation. Données pièce, données marketplace et images par article, diffusion vers les canaux.
- Retour d’information. Vente, retour, réévaluation — les données qui reviennent du canal et corrigent le stock.
Le mapping : le vrai travail
| Champ de réponse | Champ cible typique | Si la valeur est vide |
|---|---|---|
tapiId | Référence véhicule du dossier | Aucun rapprochement — créer le dossier, ouvrir une tâche |
mainType, subType | Série et exécution | Conserver le texte du certificat, ne pas deviner |
kba.hsn, kba.tsn | Clés d’homologation allemandes | Laisser vide ; beaucoup d’importations n’en ont pas |
parts[].number | Référence OE de la position | Créer la position sans référence et la marquer à compléter |
parts[].tapiGenArt | Type de pièce pour catégorie et analyses | Fixer la catégorie manuellement, pas depuis la désignation |
parts[].vdi | Correspondances VDI 4081 confirmées | Conserver le [] reçu sans rien déduire ; mettre la réponse en quarantaine si ce champ obligatoire manque |
matchLevel | Indicateur de qualité sur la liste | Ne jamais l’omettre — il décide si la liste est vendable |
content.ebayTitle, itemSpecifics | Champs canal de l’article | Ne pas publier, envoyer en file de contrôle |
Les quatre points techniques qui coincent
- Réponses asynchrones.
GET /vin/{vin}/partsetGET /vin/{vin}/economic-evaluationrépondent200ou acceptent le travail avec202. Une intégration qui ne connaît que200marche en test et échoue en production ; conserver l’identifiant du travail et interroger à l’intervalle indiqué. - Un appel à la fois par client. Les requêtes parallèles finissent en
429 client_request_in_progress. Une file d’attente dans l’ERP est obligatoire. - Idempotence. Les appels en écriture acceptent un
Idempotency-Key. La même clé renvoie le même résultat sans réexécution — la protection la plus simple contre la double facturation. - Rendre la facturation visible. Les en-têtes
X-Tapinoma-Billing-SourceetX-Tapinoma-Billing-Bundledisent comment un appel a été imputé. Les journaliser permet d’expliquer chaque ligne de facture.
Ordre de déploiement
- Commencer par l’entrée véhicule. L’intégration VIN fait gagner le plus de temps et se mesure le plus clairement.
- Écrire le mapping, y compris le sens de chaque valeur vide. Ce document est l’intégration ; le code n’en est que la mise en œuvre.
- Tester avec cinq véhicules, dont une importation sans clés de type et un sans résultat.
- Définir le cas d’erreur : créer le dossier, laisser le champ vide, ouvrir une tâche — jamais de valeur estimée.
- Déployer et mesurer deux semaines : temps par véhicule, part de la file de contrôle, compléments, appels par dossier.
Limites
- L’API ne remplace pas un ERP. Elle alimente le système de référence ; stock, pièces comptables et comptabilité y restent.
- Les résultats appartiennent à votre base. Pas d’appel à chaque affichage ; les données pièce changent rarement et chaque répétition coûte.
- Les droits sur le résultat relèvent du contrat. Ce qui peut être stocké y figure, pas dans le modèle de données.
- Tous les champs ne sont pas renseignés partout. La couverture varie selon constructeur, année et marché ; cela appartient au mapping, pas au support.
Le parcours complet du véhicule à l’évaluation figure dans Du VIN à l’analyse de rentabilité : la voie véhicule, celui de la pièce au canal dans De la référence OE à l’article prêt pour la marketplace. Sans développeurs internes, interrogez d’abord l’éditeur de l’ERP — la plupart des systèmes pour recycleurs disposent déjà d’une couche d’intégration ; voir ERP et gestion commerciale : créer les articles, vérifier la compatibilité, facturer par client final et Connecter une API : quand cela devient rentable.
Sources et références juridiques
Questions fréquentes
Quel processus intégrer en premier ?
L’entrée véhicule par le VIN. C’est ce qui économise le plus de saisie et se mesure le plus clairement.
Que se passe-t-il si l’API ne répond pas ?
Le dossier est créé quand même, le champ reste vide et une tâche de complément apparaît. Un dossier ne doit jamais dépendre d’une requête externe.
Comment éviter les doubles facturations ?
Avec un Idempotency-Key par opération métier. Une répétition avec la même clé renvoie le même résultat sans réexécution.
Faut-il des développeurs internes ?
Pas nécessairement. Beaucoup de systèmes de gestion sont connectés par leur éditeur ; le mapping des champs reste votre décision.