Connecter un logiciel d’expertise : lire les documents, décrire les dommages, identifier les véhicules

Où les données manquent dans le processus

Un rapport commence presque toujours par du matériel déjà existant : certificat photographié au téléphone, chiffrage d’atelier en PDF, rapport antérieur, photos d’atelier. Dans le logiciel, il est joint, pas lu. Les champs, quelqu’un les tape.

• Prise en charge du véhicule. VIN, codes de réception et données d’émission (voir Normes d’émission : ce que signifient Euro 1 à Euro 7) sont reportés du certificat vers le dossier véhicule — chaque report manuel est une source d’erreur.
• Chiffrage préalable et rapports antérieurs. Totaux, postes et équipements sont ressaisis alors qu’ils figurent dans le document.
• Description des dommages. Le texte « pare-chocs avant déformé, rayures jusqu’à l’apprêt » est rédigé à neuf pour chaque mission, et différemment selon l’expert.
• Dommages antérieurs. Le tour du véhicule est photographié mais rarement relevé de façon structurée — alors que les dommages hors zone sinistrée pèsent sur valeur de remplacement et valeur de sauvetage.
• Rappels et classification. Rappels ouverts et statut du véhicule — encore une marchandise ou déjà un déchet — sont recherchés à part, ou pas du tout.

Ce que l’API fournit

Les points d’entrée scanner ne renvoient que les valeurs présentes dans le document ou l’image ; ce qui manque reste null. Pour les documents personnels comme le certificat, seul le niveau standard est disponible pour l’instant. POST /vehicles/intake regroupe certificat, identification par VIN et tour du véhicule en un appel (fileUrl, photoUrls) ; components indique ce qui a été fourni, le reste est remboursé au prorata.

Un déroulé du début à la fin

Un client d’atelier signale un choc avant et envoie des photos ainsi qu’une photo du certificat d’immatriculation.

1. Lire le certificat. La photo part en URL de fichier vers POST /scanner/document/registration ; VIN et codes de réception alimentent le dossier véhicule sous forme structurée (champs dans Certificat d’immatriculation : les champs qui comptent). Documents étrangers : POST /scanner/document/registration/international.
2. Confirmer le VIN sur le véhicule. Sans certificat, POST /scanner/vin/extract lit le numéro sur une photo du pare-brise, de la plaque constructeur ou de la frappe. Illisible signifie vin égal à null — le logiciel demande une précision, il ne complète rien.
3. Identifier le véhicule. GET /vin/{vin}/vehicle renvoie les données véhicule et un tapiId stable. Fournisseurs 2 et 3 : interrogation directe ; fournisseur 1 : redirect_required — votre serveur crée une session avec POST /vin/redirect-sessions (vin, returnUrl, state en option) et redirige l’expert vers redirectUrl ; l’identification se fait dans l’interface tapinoma, et le retour vers returnUrl porte status=completed, tapiId et state. 404 vehicle_not_found est un résultat vide, pas une erreur (voir VIN : lire, vérifier et exploiter le numéro d’identification).
4. Reprendre les documents existants. Chiffrage ou rapport antérieur partent vers POST /scanner/document/calculation, commandes et factures vers POST /scanner/document/vehicle. Totaux, postes et équipements deviennent des champs — uniquement avec les valeurs du document.
5. Décrire le dommage. Jusqu’à cinq photos du même dommage partent vers POST /vision/damage/describe. Revient un texte en six sections fixes : élément, déformations, rayures, peinture et corrosion, pièces rapportées, divers — la matière brute du champ « description des dommages ». L’expert vérifie, abrège et complète, avec la sobriété que Pièces de carrosserie : évaluer l’état et le décrire honnêtement recommande pour la carrosserie.
6. État général et classification. Le tour du véhicule, jusqu’à 8 photos, part vers POST /vision/condition-report : constats par zone, note globale A, B ou C. Si une perte totale est possible, POST /vision/vehicle/elv-classification reçoit jusqu’à 10 photos plus valeur marchande et estimation de réparation du rapport, et répond kein_altfahrzeug_verdacht, gutachten_empfohlen ou altfahrzeug. Volet juridique : Occasion ou VHU ? La frontière qui décide de l’exportation, Véhicules accidentés : épave, valeur résiduelle et intérêt pour le centre.
7. Joindre les rappels. GET /recalls/vehicles/{vin} confronte la série au Kraftfahrt-Bundesamt, à l’EU Safety Gate et à la NHTSA ; pour chaque mesure, référence, défaut, remède et indicateur stop-drive. Une aide de travail, pas une preuve officielle.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"fileUrl":"<URL_DOCUMENT>"}' \
  'https://api.tapinomahub.com/scanner/document/calculation'

L’intégration

1. Garder la clé côté serveur. La X-Api-Key va dans la configuration du backend. Votre serveur téléverse photos et documents et les transmet en URL de fichier.
2. Commencer par un point d’entrée. POST /scanner/document/calculation est le plus souvent l’entrée la plus rentable : les chiffrages préalables existent déjà en PDF.
3. Définir la correspondance des champs. Quels champs de la réponse vont où dans le dossier véhicule, lesquels volontairement nulle part ? Les codes d’équipement arrivent en chaînes, série et options séparées. Cette correspondance est le vrai travail.
4. Distinguer résultat vide et erreur. null, vin égal à null et 404 vehicle_not_found sont des résultats métier : champ vide, reprise affichée, mission poursuivie. Une erreur technique, c’est une réponse absente ou une erreur serveur.
5. Intégrer la récupération différée. Les opérations longues répondent 202 avec Location, Retry-After et un identifiant de tâche ; la récupération passe par le point d’entrée .../jobs/{jobId} associé — par exemple GET /vin/{vin}/parts avec GET /vin/parts/jobs/{jobId}.
6. Déployer et observer. D’abord un cabinet pilote, puis tous. GET /client/usage montre la fréquence par point d’entrée ; X-Tapinoma-Usage-Warning signale un crédit faible.

Points de vigilance

• Poser un Idempotency-Key. Les répétitions portent X-Tapinoma-Idempotent-Replay. Les appels qui émettent une clé une seule fois ne sont pas rejoués — après un délai dépassé, rapprocher l’existant plutôt que réessayer à l’aveugle.
• Laisser vides les champs vides. Un null issu du document est une information ; une valeur par défaut ressemble à un constat dans le rapport.
• Conserver le `tapiId`. GET /vehicles/{tapiId} renvoie plus tard les données techniques dans le cadre du parcours VIN déjà facturé, sans VIN ni équipements.
• Jamais la clé dans le navigateur. Pas davantage dans une application de terrain — le téléversement passe par votre serveur.
• Photos en pleine résolution. Les vignettes produisent des lacunes, pas des constats — et l’analyse est facturée même si rien n’était reconnaissable.
• Limites de débit par cabinet. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée.
• Vérifier le résultat. Totaux et descriptions extraits sont une entrée pour l’expert, pas son jugement. Sur les données personnelles du certificat : Données dans un VHU : ce qui reste dans l’infodivertissement.

Ce que l’API ne fait pas

Elle n’établit aucun rapport et ne remplace aucun expert. La description des dommages est un texte sur le visible, pas une évaluation ; le rapport d’état ne contient ni chiffrage de réparation ni calcul de valeur de sauvetage ; la classification VHU s’appuie sur valeur marchande et estimation de réparation de votre rapport et ne décide pas. L’évaluation de prix des pièces est indicative, sans garantie. POST /vision/license-plate lit une plaque, sans recherche du titulaire. Le fournisseur 1 n’est pas interrogeable directement par des systèmes tiers, seulement via la redirection navigateur. La vérification des rappels est liée à la série, pas une preuve officielle pour le véhicule individuel. Aucune base de données n’est vendue : ce qui est dû, c’est l’exécution de la requête ou de l’analyse ; vérification et usage vous reviennent, à vous et à vos clients.