Sociétés de leasing et remarketing : restitution, état et annonce via l’API

Où les données manquent dans le processus

Une restitution est un rendez-vous court avec beaucoup de reports : le certificat d’immatriculation est photographié puis ressaisi, l’état est écrit dans un champ libre, l’annonce est composée à partir de la fiche contrat — qui ne décrit pas toujours le véhicule réellement revenu. À cinq endroits, des manques apparaissent régulièrement :

• À la réception. Le VIN du contrat et celui du certificat ne sont pas recoupés ; les fautes de frappe n’apparaissent que lorsque l’annonce est en ligne ou que la radiation échoue.
• Au procès-verbal d’état. Chaque site photographie et décrit autrement. Deux rapports sur le même dommage ne sont pas comparables, et un acheteur sur la plateforme d’enchères ne peut se fier à aucun.
• À l’annonce. Titre, description et liste d’équipements sont rédigés à la main pour chaque véhicule — et une fois de plus dans une autre langue pour chaque marché cible.
• Avant la mise en vente. Personne ne vérifie systématiquement si un rappel ouvert existe pour la série, alors que le véhicule part chez un nouveau titulaire.
• En bout de chaîne. Les véhicules non commercialisables partent au recyclage sans base de données : savoir s’il s’agit juridiquement d’un VHU et ce que les pièces rapportent encore reste une estimation.

Ce que l’API fournit

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

1. Avant le tour du véhicule : réinitialiser. Infodivertissement aux réglages d’usine, appairages déconnectés, supports de stockage retirés — tant que le véhicule est sous tension. Ce n’est pas un appel à l’API mais un champ du procès-verbal ; pourquoi est expliqué dans Données dans le véhicule hors d’usage.
2. Créer la restitution en un appel. L’application sur site charge la photo du certificat et jusqu’à 5 prises de vue du tour du véhicule ; le backend appelle POST /vehicles/intake avec fileUrl et photoUrls. En retour : les champs du certificat, les données véhicule avec tapiId et le rapport d’état en huit zones. components indique pour chaque composant s’il a été fourni ; le traitement commercial suit les conditions affichées avant la commande et convenues au contrat.
3. Vérifier la plaque contre le contrat. À partir d’une vue de face, POST /vision/license-plate lit caractères, pays et confiance — pour le recoupement avec la fiche contrat, pas comme recherche de titulaire.
4. Recouper les rappels avant la mise en vente. GET /recalls/vehicles/{vin} vérifie la série contre les registres officiels. Une campagne avec indicateur stop-drive bloque la mise en vente dans votre système ; les autres sont traitées avant la remise ou jointes à l’annonce comme mention.
5. Générer l’annonce. POST /vehicles/{tapiId}/listing avec language par marché cible et les notes du vendeur dans notes renvoie titre, description et points forts d’équipement à partir des données véhicule documentées. Prix et mention d’état sont ajoutés par votre logiciel ; le texte n’invente aucune caractéristique.
6. Classer les véhicules non commercialisables. Lorsqu’accident, panne ou âge excluent le remarketing, POST /vision/vehicle/elv-classification fournit la classification à partir de 1 à 10 prises de vue avec des critères étayés ; la distinction juridique est traitée dans Véhicule d’occasion ou VHU et Véhicules accidentés. Ce que le véhicule rapporte encore au démontage, GET /vin/{vin}/economic-evaluation avec provider=1 y répond — une opération longue qui répond 202. L’analyse suppose le recoupement du véhicule auprès du fournisseur 1, que l’intake ne fournit pas : pour les systèmes tiers, il passe par le navigateur de l’utilisateur via POST /vin/redirect-sessions ; l’appel ne suit qu’après le retour avec status=completed.
7. Conserver l’identifiant. Le tapiId va dans le dossier véhicule. GET /vehicles/{tapiId} fournit plus tard les données techniques dans le cadre du parcours VIN initial déjà facturé — sans VIN ni équipements et sans nouveau recoupement.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <IDEMPOTENCY_KEY>' \
  -d '{
    "fileUrl": "https://example.com/restitution/certificat.jpg",
    "photoUrls": [
      "https://example.com/restitution/avant.jpg",
      "https://example.com/restitution/arriere.jpg"
    ]
  }' \
  'https://api.tapinomahub.com/vehicles/intake'

L’intégration

1. Garder la clé côté serveur. L’en-tête X-Api-Key est posé uniquement depuis le backend. L’application de restitution parle à votre serveur, jamais à l’API directement.
2. Commencer par un point d’entrée. POST /vehicles/intake remplace trois saisies d’un coup et constitue l’entrée la plus rentable. Rappels, annonce et classification VHU suivent comme étapes distinctes.
3. Définir la correspondance des champs. Quels champs du certificat, données véhicule et zones du rapport d’état vont dans quels champs du procès-verbal ? Cette correspondance est le vrai travail ; la référence figure dans le guide d’intégration.
4. Séparer échec et résultat vide. Pour l’intake, un résultat vide est une réponse 200 : si le VIN reste illisible ou si la voie de données ne répond pas, components.vehicle vaut vin_not_readable ou unavailable et complete vaut false. La restitution est créée, les champs du certificat repris, le recoupement reste en reprise. 404 vehicle_not_found est, pour GET /vin/{vin}/vehicle et l’analyse économique, le résultat vide pour le VIN ; pour POST /vehicles/{tapiId}/listing et GET /vehicles/{tapiId}, le même code signifie un tapiId inconnu ou étranger. Pour le recoupement des rappels, 404 signifie que le VIN ne peut pas être résolu à partir du stock existant. Le traitement commercial suit les conditions affichées avant la commande et convenues au contrat. On ne réessaie que si l’analyse n’a pas pu être effectuée du tout.
5. Prévoir la récupération en `202`. L’analyse économique répond 202 avec Location, Retry-After et un identifiant de job ; GET /vin/economic-evaluation/jobs/{jobId} récupère le résultat — depuis une file d’attente de votre backend, pas depuis l’application.
6. Déployer site par site. D’abord un site de retour, puis les autres. GET /client/usage montre quels appels tournent et à quelle fréquence ; X-Tapinoma-Usage-Warning signale un crédit faible.

Points de vigilance

• Poser `Idempotency-Key`. Une application sur réseau mobile envoie parfois deux fois ; avec l’en-tête, le second appel est reconnu comme répétition (X-Tapinoma-Idempotent-Replay) et n’est pas facturé deux fois. Exception : les appels qui délivrent une clé ne sont pas rejoués — après un délai dépassé, rapprocher l’existant au lieu de recréer.
• Laisser vides les champs vides. Un champ du certificat non lu, une zone sans constat, un véhicule sans correspondance : le résultat nomme le manque, et le logiciel le reprend comme manque — ni valeur par défaut, ni complément tiré du contrat.
• Conserver `tapiId` dans le dossier. C’est l’identifiant stable pour l’annonce et les données véhicule. Qui le jette recoupe le même véhicule une seconde fois.
• Jamais la clé dans le navigateur. Ni dans l’application de restitution, ni dans le portail distributeurs. Chaque appel passe par votre backend.
• Prévoir les limites de débit. Un import massif depuis les archives relève d’une file d’attente. Les limites par utilisateur, clé ou point d’entrée se règlent via PUT /client/users/{clientId}/rate-limits.
• Faire vérifier le résultat. Rapport d’état, recoupement des rappels et texte d’annonce sont des aides au travail ; la mise en vente reste une décision de votre propre processus. Une analyse d’image effectuée est facturée, même sans constat.

Ce que l’API ne fait pas

Le rapport d’état n’est pas une expertise et ne contient aucun calcul de réparation ni de valeur résiduelle ; il décrit ce qui est visible sur les prises de vue et signale comme telles les zones sans constat. La plaque est lue, pas vérifiée contre un registre ; il n’existe aucune recherche de titulaire. Le texte d’annonce ne cite aucun prix, et l’analyse économique est une recommandation d’achat issue de références de marché, pas une garantie de prix — la manière de calculer un achat est traitée dans Achat de véhicules. Les données véhicule du fournisseur 1 ne peuvent pas être récupérées directement par un système tiers via GET /vin/{vin}/vehicle ; ce recoupement passe par le navigateur de l’utilisateur via POST /vin/redirect-sessions. Aucun jeu de données n’est vendu : ce qui est dû est l’exécution de la requête ou de l’analyse ; le résultat est vérifié et utilisé par vous et vos clients.