Logiciels de gestion d’atelier : vérifier les pièces sur le véhicule avant de commander

Où les données manquent dans le processus

Un ordre de réparation commence par un véhicule et finit par une facture. Entre les deux, le logiciel ignore ce qu’il devrait savoir, et un collaborateur complète depuis le catalogue ou par téléphone :

• La commande de pièces part avant que la compatibilité soit vérifiée. Le conseiller service reporte les références OE du catalogue dans l’ordre. Si elles conviennent à ce véhicule précis avec cet équipement précis, on le voit au montage — ou au retour.
• La référence OE des documents du client est une référence antérieure. La référence sur la facture ou l’ancienne pièce apportée a été remplacée. Laquelle vaut aujourd’hui, quelqu’un le cherche à la main — voir Référence OE : bien lire une référence d’origine.
• La pièce déposée porte une étiquette que personne ne recopie. Les références pièce et équipementier du calculateur remplacé finissent en photo dans l’ordre, pas en données — voir Calculateurs d’occasion : codage, antidémarrage, annonce.
• Les rappels ne sont pas recoupés pendant la visite. Le véhicule est sur le pont ; une campagne de rappel ouverte serait un second ordre, mais le logiciel n’en sait rien.
• La désignation de la pièce n’existe que dans une langue. Une entreprise avec des clients ou des fournisseurs à l’étranger traduit elle-même les désignations sur la facture.

Ce que l’API fournit

Un déroulé de bout en bout

1. Créer l’ordre, recouper le véhicule. L’atelier saisit le VIN. Les fournisseurs 2 et 3, votre système les interroge directement par GET /vin/{vin}/vehicle. Pour le fournisseur 1, votre serveur crée une session par POST /vin/redirect-sessions à partir de vin, returnUrl et state et envoie le conseiller service vers la redirectUrl ; le retour apporte status=completed avec tapiId et state — ou status=cancelled. La session expire après dix minutes ; aucune donnée véhicule ou d’accès ne figure dans la redirection.
2. Charger les données véhicule incluses. GET /vehicles/{tapiId} fournit les données techniques du véhicule pour l’écran de l’ordre dans le cadre du parcours VIN déjà facturé — sans VIN ni équipement et sans commander un nouveau rapprochement.
3. Vérifier les rappels tant que le véhicule est là. GET /recalls/vehicles/{vin} recoupe la série avec le Kraftfahrt-Bundesamt, EU Safety Gate et la NHTSA. Une mesure ouverte apparaît dans l’ordre avec dossier, remède et indicateur stop-drive.
4. Situer les pièces de l’ordre. Chaque référence OE passe par GET /parts/oe/{oeNumber}. Reviennent la chaîne de remplacement, la tapiGenArt comme GenArt pour la famille de produits et, sous part, les champs manufacturer, name et listPrice, qui peuvent être null et restent alors vides. Sans correspondance de base confirmée, l’appel répond 404.
5. Vérifier la compatibilité avant de commander. Toutes les lignes partent ensemble vers POST /vin/cart-check avec mode=vehicle, jusqu’à 30 par appel. Chaque ligne renvoie fits ; complete figure une seule fois au niveau de la réponse et dit si la liste de pièces du véhicule était complète. Avec complete=true, les lignes avec fits=false sont signalées avant la commande ; avec complete=false, chaque non de cette vérification reste une question ouverte. Si le service répond 202, votre système récupère le résultat par GET /vin/cart-check/jobs/{jobId}.
6. Proposer des alternatives et des pièces d’occasion. Pour une ligne sans compatibilité ou sans disponibilité, GET /parts/oe/{oeNumber}/aftermarket-references fournit des candidats de recherche du marché indépendant, pas une garantie de compatibilité. Une pièce d’occasion d’un centre VHU est une option de plus ; les informations dont l’atelier a besoin sont dans Les garages comme clients : ce que le professionnel attend d’autre.
7. Saisir la pièce déposée. Le mécanicien photographie l’étiquette ; POST /scanner/label/extract-partnumbers lit les références pièce et équipementier et les range dans l’ordre. Ce qui n’est pas lisible sur l’image reste un vide.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"vin":"<VIN>","mode":"vehicle","oeNumbers":["5Q0919275C"]}' \
  'https://api.tapinomahub.com/vin/cart-check'

L’intégration

1. Garder la clé côté serveur. La X-Api-Key va dans la configuration de votre serveur, jamais dans l’interface d’atelier ni dans une application mobile. Dans une installation sur site, un service sur le serveur de l’atelier passe les appels.
2. Commencer par un point d’entrée. Pour cette catégorie de logiciels, c’est POST /vin/cart-check : il agit là où les erreurs coûtent le plus et n’a besoin que de données que l’ordre contient déjà.
3. Définir la correspondance des champs. fits dans la ligne de l’ordre, le complete de la réponse sur toutes les lignes de cette vérification, tapiGenArt dans la famille de produits, la référence actuelle de la chaîne de remplacement dans un champ propre à côté de la référence saisie. Cette correspondance est le vrai travail.
4. Séparer résultat vide et panne. 404 vehicle_not_found ou une liste de références vide sont des résultats métier : l’ordre reste, le champ reste vide, une indication apparaît. Une erreur technique déclenche une reprise ou une tâche de suivi — jamais une valeur par défaut.
5. Prévoir la récupération après `202`. Les vérifications longues répondent 202 avec Location, Retry-After et un identifiant de job. Votre système interroge GET /vin/cart-check/jobs/{jobId} sans bloquer l’écran de l’ordre.
6. Déployer et observer. Un atelier pilote d’abord, puis largement. GET /client/usage montre quels appels tournent et à quelle fréquence ; l’en-tête X-Tapinoma-Usage-Warning signale un crédit faible.

Points de vigilance

• Poser un `Idempotency-Key` sur chaque POST. Un second clic sur « Vérifier » ne doit pas déclencher une seconde vérification ; X-Tapinoma-Idempotent-Replay signale une réponse rejouée. Exception : POST /client/partner-workspaces délivre la clé une seule fois — après un délai dépassé, recouper par externalReference au lieu de recréer.
• Ne pas combler les champs vides. Si name ou listPrice vaut null, le champ reste vide dans l’ordre. Un prix catalogue plausible venu d’ailleurs est plus dangereux qu’un manque visible.
• Enregistrer la `tapiId` sur le véhicule. Elle est stable et rattache GET /vehicles/{tapiId} au parcours VIN déjà facturé lors de la visite suivante.
• Ne jamais donner la clé au navigateur. Pas même pour la redirection : votre serveur appelle POST /vin/redirect-sessions, le navigateur ne reçoit que la redirectUrl.
• Fixer des limites de débit par atelier. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée, pour qu’une entreprise n’épuise pas le quota des autres.
• Faire vérifier le résultat, pas le transmettre tel quel. fits=true est un recoupement, pas une promesse de montage ; une référence adaptable est un candidat de recherche. Le logiciel affiche provenance et confiance, l’atelier décide.

Ce que l’API ne fait pas

Elle ne remplace pas le catalogue du constructeur et ne fournit pas de notice de montage. POST /vin/cart-check recoupe si une référence OE convient au véhicule ; disponibilité et prix, l’appel ne les dit pas — GET /parts/oe/{oeNumber}/price fournit une évaluation indicative, pas une garantie de prix. Le recoupement des rappels est une aide de travail au niveau de la série, pas un renseignement officiel. Aucun titulaire n’est identifié nulle part, aucune expertise n’est établie nulle part. Pour le fournisseur 1, le recoupement véhicule passe exclusivement par la redirection vers l’interface tapinoma ; un système tiers ne peut pas l’appeler directement. Ce qu’aucune source n’étaye reste vide : un résultat vide n’est pas une erreur, c’est le résultat. Ce qui est vendu est le recoupement, pas un fonds de données ; vérifier et utiliser les résultats incombe à l’atelier.