Gestion des sinistres et assureurs : chiffrage, état et valeur résiduelle par API

Où les données manquent dans le processus

Un dossier sinistre se compose en grande partie de documents et de photos dont le contenu n’existe pas sous forme d’enregistrement. Le chiffrage arrive en PDF, les photos viennent de la déclaration. Ce qu’il en faut dans des champs, quelqu’un le lit et le ressaisit aujourd’hui.

• Chiffrages et rapports d’expertise arrivent en PDF. Totaux, pièces, main-d’œuvre et codes d’équipement sont reportés à la main pour le contrôle et la comparaison.
• Le dommage est photographié mais pas décrit. Le gestionnaire rédige un texte libre qui diffère d’un collègue à l’autre.
• L’état hors zone de choc n’est pas documenté. Pour la valeur résiduelle et le sort du véhicule, ce qui n’est pas endommagé compte aussi — un centre VHU valorise précisément ces pièces, voir Pièces de carrosserie : évaluer l’état et le décrire honnêtement.
• Réparation ou VHU se décide au jugé. Qu’un véhicule soit marchandise ou déchet après le sinistre détermine la suite — voir Occasion ou VHU ? La frontière qui décide de l’exportation.
• Identité du véhicule et rappels vivent dans des sources séparées et finissent rarement dans le même dossier.

Ce que l’API fournit

Un déroulé de bout en bout

1. Déclaration avec photos. 1 à 5 photos du même dommage vont à POST /vision/damage/describe ; revient une description en six sections fixes qui figure au dossier comme constat, pas comme texte libre.
2. Rapprocher le véhicule. Le VIN va à GET /vin/{vin}/vehicle avec provider=2 ou provider=3 ; le fournisseur 1 n’est joignable depuis un système tiers que par la redirection navigateur et il est requis si l’analyse économique doit suivre. Le rapprochement lie le VIN, pour ce client, au fournisseur choisi. Reviennent les données du véhicule et un tapiId — ou 404 vehicle_not_found : pas d’enregistrement, le champ reste vide, le dossier continue.
3. Lire le chiffrage. Le PDF va par fileUrl à POST /scanner/document/calculation. Totaux, appréciation de réparation, postes et equipment avec codes DAT en chaînes sont ensuite disponibles en champs — seules les valeurs du document, rien n’est ajouté.
4. Vérifier les rappels. GET /recalls/vehicles/{vin} livre les mesures par série avec l’indicateur d’immobilisation, avant que le véhicule ne soit libéré pour réparation.
5. État et qualification. Jusqu’à 8 photos du tour du véhicule vont à POST /vision/condition-report ; 1 à 10 photos avec valeur de marché et estimation de réparation à POST /vision/vehicle/elv-classification. Le niveau altfahrzeug ne naît que d’un critère fortement étayé ou de l’arithmétique avec les valeurs transmises.
6. Préparer la question résiduelle. GET /vin/{vin}/economic-evaluation n’accepte que provider=1 et suppose que le véhicule a été rapproché au préalable par le fournisseur 1 — depuis un système tiers, uniquement via POST /vin/redirect-sessions avec un retour status=completed et tapiId ; un VIN rapproché par provider=2 ou provider=3 reste lié à ce fournisseur. L’analyse livre alors le potentiel de recette pièces en min/average/max et un classement de démontage ; statut via GET /vin/economic-evaluation/jobs/{jobId}. C’est une base de calcul, pas une valeur résiduelle — celle-ci naît des offres, voir Véhicules accidentés : épave, valeur résiduelle et intérêt pour le centre et Achat de véhicules : ce que vaut réellement un VHU.
7. Clore le dossier. tapiId, champs du document et constats restent au dossier ; GET /vehicles/{tapiId} livre plus tard les données techniques dans le cadre du parcours VIN déjà facturé, sans VIN ni équipement.

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

L’intégration

1. Stocker la clé côté serveur. La clé API va dans la configuration du backend et dans l’en-tête X-Api-Key — jamais dans une application navigateur.
2. Commencer par un point d’entrée. Le plus souvent POST /scanner/document/calculation, parce que c’est là qu’on ressaisit aujourd’hui ; techniquement un appel HTTPS en JSON, indépendant du langage et de la plateforme.
3. Définir la correspondance des champs. Quels champs de la réponse vont dans quels champs du dossier ? Cette correspondance est le vrai travail.
4. Séparer l’échec du constat vide. 404 vehicle_not_found, un champ null ou une section sans constat sont des résultats métier et sont enregistrés ; une erreur technique déclenche une reprise ou une tâche, jamais une valeur par défaut.
5. Construire la relève `202`. Les appels longs répondent 202 avec Location et Retry-After ; le statut se relève sur le point d’entrée .../jobs/{jobId} correspondant. Jusque-là, l’opération reste « en cours ».
6. Déployer et observer. Un mandant d’abord, puis tous ; GET /client/usage et GET /client/credits montrent appels et crédit.

Points de vigilance

• Poser un `Idempotency-Key`. Une reprise après délai d’attente renvoie alors la même réponse, reconnaissable à X-Tapinoma-Idempotent-Replay. Les appels qui émettent une clé une seule fois ne sont pas rejoués : après un délai, rapprocher l’existant au lieu de réessayer à l’aveugle.
• Ne pas combler les champs vides. Un null dans le chiffrage signifie que le document n’indique pas la valeur ; une section sans constat signifie rien de visible. Les deux vont au dossier tels quels — ni valeur par défaut ni estimation.
• Conserver le `tapiId`. C’est l’identifiant stable du véhicule rapproché et la clé de toute question ultérieure sans nouveau rapprochement.
• Jamais la clé dans le navigateur. Pour le fournisseur 1 aussi : le backend crée via POST /vin/redirect-sessions une session à usage unique à partir de vin, returnUrl et state ; le retour ne porte que status, tapiId et state, jamais de données véhicule ou d’accès. La session expire au bout de dix minutes.
• Limites de débit par mandant. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée pour qu’un traitement de masse ne freine pas les autres mandants ; X-Tapinoma-Usage-Warning signale un crédit bas.
• Faire vérifier les résultats. La description ne remplace pas une inspection, la qualification pas une expertise, le potentiel de recette pas une valeur résiduelle. Le dossier indique quel champ vient de quel appel.

Ce que l’API ne fait pas

L’API ne produit aucune expertise et ne remplace aucun expert : le rapport d’état ne contient ni calcul de réparation ni valeur résiduelle, la description du dommage ne couvre que le visible, et le niveau gutachten_empfohlen signifie exactement cela — expertise recommandée. Elle n’effectue aucune recherche de titulaire ni de rapprochement avec le registre d’immatriculation ; le rapprochement des rappels est par série et une aide de travail — seul le constructeur répond de façon contraignante pour un véhicule donné. Les évaluations de prix et le potentiel de recette sont indicatifs, sans garantie de prix. Le fournisseur 1 n’est atteint par des systèmes tiers que par la redirection navigateur. Et tapinomahub ne vend aucune base de données : ce qui est dû, c’est l’exécution de la requête ou de l’analyse — une analyse d’image effectuée est facturée même sans constat —, la vérification et l’usage des résultats relèvent du client. Ce que les données véhicule d’un dossier sinistre impliquent en protection des données est traité dans Données dans un VHU : ce qui reste dans l’infodivertissement.