Logiciels pour centres VHU : dossier véhicule, justificatifs et stock via API

Où les données manquent dans le processus

Le dossier véhicule naît à la réception, et le temps y est compté : le déposant attend son certificat, la carte grise est sur le comptoir, le véhicule est dans la cour. À cinq endroits, on saisit, on estime ou on laisse vide aujourd’hui :

• Création du dossier. VIN, marque, type et catégorie de véhicule sont recopiés de la carte grise. Un VIN mal recopié rend le futur certificat de destruction contestable — voir Certificat d’immatriculation : les champs qui comptent.
• Classement du véhicule. Savoir si un véhicule doit être traité comme véhicule hors d’usage se décide dans la cour et se documente rarement par des photos — voir Réglementation VHU allemande : obligations des détenteurs et des centres.
• Profondeur de démontage. Quelles pièces démonter se décide à l’expérience, pas sur une attente de recette documentée par pièce — voir Profondeur de démontage : quelles pièces valent la dépose.
• Référence et état au démontage. La référence de l’étiquette finit sur un papier écrit les mains grasses ; le champ état dit « bon » parce qu’il fallait le remplir — voir Identification des pièces : de la dépose à la fiche vendable.
• Classement du stock. Groupe principal et position selon VDI 4081 sont attribués différemment dans chaque centre, faute de catalogue dans le système.

Ce que l’API fournit

Un déroulé de bout en bout

1. Réception : photographier la carte grise. Votre logiciel envoie la fileUrl de l’image à POST /vehicles/intake, avec en option des photos du tour du véhicule en photoUrls pour un rapport d’état. Reviennent les champs du document, les données véhicule avec tapiId et le rapport ; ce que le document ne montre pas reste vide.
2. Établir le certificat. VIN, marque, type et immatriculation issus des champs du document remplissent le certificat de destruction. POST /vision/vehicle/elv-classification documente le classement en véhicule hors d’usage avec constat et photos par critère ; la décision juridique reste au centre.
3. Obtenir la liste de pièces. Juste après la réception, le logiciel appelle GET /vin/{vin}/parts sans provider. La réception a rattaché le VIN à la voie de données 2 ; l’appel reprend ce rattachement et renvoie la liste de pièces au niveau du type de véhicule avec matchLevel=vehicle_type_candidates, en règle générale immédiatement en 200. Plusieurs variantes d’une même pièce peuvent figurer côte à côte. Un provider explicite qui contredit le rattachement existant est refusé avec 409 vin_provider_mismatch.
4. Ou : la voie fournisseur 1, choisie avant le premier rapprochement. Le classement par recette repose sur la liste de pièces propre au véhicule du fournisseur 1, et un système tiers ne peut pas appeler directement le rapprochement fournisseur 1. Le logiciel décide donc par véhicule, avant le premier rapprochement, quelle voie il emprunte : la réception via la voie de données 2 avec la liste au niveau type — ou la voie fournisseur 1, où votre serveur crée une session avec POST /vin/redirect-sessions à partir de vin, returnUrl et, en option, state, puis dirige l’utilisateur vers la redirectUrl ; le retour sur returnUrl porte status=completed et le tapiId. La session expire après dix minutes ; aucune donnée véhicule ne figure dans la redirection. La spécification ne documente aucun changement d’un rattachement de VIN existant ; un provider contraire au rattachement est refusé avec 409 vin_provider_mismatch.
5. Planifier le démontage. Sur la voie fournisseur 1, GET /vin/{vin}/economic-evaluation avec provider=1 renvoie, après le rapprochement issu de la session navigateur, le classement trié par recette avec min/average/max par pièce ; les petites pièces sont écartées. Si toutes les évaluations ne sont pas encore disponibles, l’appel répond 202 avec Location, Retry-After et un identifiant de job pour GET /vin/economic-evaluation/jobs/{jobId}. Le logiciel affiche le classement comme liste de travail ; où passe la ligne, c’est le centre qui décide.
6. Démontage : photographier l’étiquette. POST /scanner/label/extract-partnumbers lit références et numéros ; GET /parts/oe/{oeNumber} renvoie, pour une correspondance confirmée, la désignation, exactement un tapiGenArt et l’affectation VDI 4081, 404 signifie aucune correspondance.
7. Classer l’état. Une à trois photos partent vers POST /vision/part/quality ; revient A, B ou C avec limitations — ou gradable=false avec reason ; le champ reste alors vide.
8. Tenir le stock. GET /vdi renvoie le catalogue avec version et valeur de contrôle, sur lequel le logiciel aligne ses groupes principaux ; dépollution, retrait des pièces et remise de la carcasse sont sous le même tapiId — voir Dépollution : ce qui doit sortir avant le démontage.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fileUrl": "https://<VOTRE_SERVEUR>/dossiers/4711/carte-grise.jpg",
    "photoUrls": [
      "https://<VOTRE_SERVEUR>/dossiers/4711/tour-avant.jpg",
      "https://<VOTRE_SERVEUR>/dossiers/4711/tour-arriere.jpg"
    ]
  }' \
  'https://api.tapinomahub.com/vehicles/intake'

L’intégration

1. Stocker la clé côté serveur. La X-Api-Key va dans la configuration de votre backend ; la photo prise sur la tablette dans la cour va vers votre serveur, et seul votre serveur appelle l’API.
2. Commencer par un point d’entrée. Pour un logiciel de centre VHU, c’est POST /vehicles/intake derrière la réception, parce que toute saisie ultérieure s’accroche au dossier. L’ordre contrat, clé, processus, mise en production est décrit dans le guide d’intégration.
3. Définir la correspondance des champs. Champs du document, données véhicule et rapport d’état ont des cibles fixes dans le dossier ; le tapiId reçoit son propre champ, tout comme la provenance de chaque valeur : lue, rapprochée ou saisie à la main.
4. Distinguer résultat vide et erreur. Si tapiId reste null dans le dossier et que components signale la partie véhicule comme non fournie, c’est un résultat métier, pas une erreur : créer le dossier, laisser le champ véhicule vide, générer une tâche de clarification ; les champs du document restent dans la réponse, la part véhicule est remboursée au prorata. Seule une erreur technique se réessaie.
5. Récupérer les réponses asynchrones. Liste de pièces et évaluation économique peuvent répondre 202 ; sur la voie fournisseur 1, les deux supposent le rapprochement issu de la session navigateur, choisie avant le premier rapprochement du VIN. Le logiciel mémorise l’identifiant du job et interroge GET /vin/parts/jobs/{jobId} ou GET /vin/economic-evaluation/jobs/{jobId} après Retry-After, au lieu de répéter l’appel.
6. Déployer. D’abord dans un centre, 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, l’en-tête évite les doublons de dossier 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 un champ du document reste vide ou si gradable=false revient, le champ du dossier reste vide et reçoit une tâche de clarification. Un VIN deviné sur un certificat de destruction est pire qu’un manque visible.
• Conserver le `tapiId`. C’est l’ancre du dossier : GET /vehicles/{tapiId} en renvoie les données techniques dans le cadre du parcours VIN déjà facturé, sans VIN et sans équipements, et chaque pièce démontée y est rattachée.
• Jamais la clé dans le navigateur. Une application web ou tablette appelle elle aussi l’API depuis le backend ; l’appareil 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 de photos dans un centre n’épuise pas le contingent de tous les autres ; X-Tapinoma-Usage-Warning signale un crédit bas.
• Faire vérifier le résultat. Classement et niveau d’état sont la base d’une décision, pas la décision ; les évaluations de prix de marché sont réutilisées jusqu’à 30 jours. Le démonteur confirme, le logiciel 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 ou l’analyse et la restitution de son résultat ; la vérification avant usage incombe au centre. Elle n’établit pas de certificat de destruction ; elle en fournit les mentions et documente d’où elles viennent. Le classement en véhicule hors d’usage est un contrôle visuel sur photos, pas une expertise ; le rapport d’état ne contient ni calcul de réparation ni valeur résiduelle ; l’évaluation économique est une attente de recette, pas une garantie de prix. Il n’y a pas de recherche du titulaire. 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. Là où un champ n’est pas documenté, il reste null — l’API ne devine pas, et votre logiciel ne devrait pas non plus.