Du VIN à l’analyse de rentabilité : la voie véhicule

Un véhicule accidenté est dans la cour, le vendeur attend un prix, et la décision se prend en quelques minutes. S’en remettre à l’expérience seule conduit à payer trop cher les séries inhabituelles et à laisser de l’argent sur les banales. La voie véhicule de l’API tapinomahub part d’où part l’acheteur : du numéro d’identification du véhicule — et aboutit à un montant traçable, accompagné d’un ordre de démontage.

Étape 1 : rendre le véhicule univoque

GET /vin/{vin}/vehicle rapproche le VIN de la source activée. includeEquipments, includeColors et includeTechnical règlent la profondeur de la réponse ; country fixe le contexte de marché et provider la source prévue au contrat. Un rapprochement réussi contient une tapiId stable — la référence par laquelle tous les appels suivants désignent le même véhicule. La description du service figure dans Comparer les données d’un véhicule par VIN.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/WVWZZZ1KZAW000000/vehicle?includeEquipments=true&includeTechnical=true'

Étape 2 : la liste des pièces du véhicule

GET /vin/{vin}/parts renvoie les positions OE trouvées : par pièce number et numberUnformatted, name et nameAddition, category, manufacturer, amount, price, tapiGenArt et le champ obligatoire vdi. vdi contient les codes VDI 4081 complets et confirmés et reste présent sous la forme [] lorsqu’aucune correspondance valide n’est disponible. Plus important que la liste : sa qualification. matchLevel indique la fiabilité de l’affectation et missingCategories ce qui manque. Une liste missingCategories non vide signifie expressément que la liste est incomplète. Détails dans Comparer les affectations de pièces par VIN.

Traiter correctement le travail asynchrone

La liste des pièces et l’évaluation peuvent demander plus de temps qu’une réponse HTTP ne doit attendre. L’API répond donc soit immédiatement 200, soit accepte le travail avec 202 — avec Location, Retry-After et un jobId. C’est le cas normal documenté, pas un incident.

1. Traiter les deux réponses. Une intégration qui ne connaît que 200 fonctionne en test et échoue en production. 202 fournit jobId, statusUrl, status et retryAfterSeconds.
2. Interroger à l’intervalle indiqué, pas en boucle serrée. GET /vin/parts/jobs/{jobId} et GET /vin/economic-evaluation/jobs/{jobId} renvoient queued, running, succeeded ou failed.
3. Avec `succeeded`, le résultat est dans `result` — même structure qu’une réponse 200 directe. Votre code n’a donc besoin que d’un seul chemin de lecture.
4. Avec `failed`, `error.code` distingue vehicle_not_found — constat métier vide — de vin_service_unavailable, panne technique. Seul le second justifie une nouvelle tentative.
5. La référence du travail appartient au dossier. La perdre empêche de récupérer le résultat ; un travail inconnu donne 404 vin_parts_job_not_found.

# 202 Accepted : {"jobId":"8f1c…","status":"queued","retryAfterSeconds":5,…}
curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/parts/jobs/8f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21'

Étape 3 : l’analyse de rentabilité

GET /vin/{vin}/economic-evaluation combine la liste des pièces et les prix du marché pour calculer trois choses : le potentiel de revenus du véhicule, un ordre de démontage et une recommandation d’achat. La réponse expose ses hypothèses afin que chaque montant puisse être recalculé — voir Créer une évaluation économique par VIN.

• `coverage` rend la situation des données visible : totalParts, excludedIrrelevant, relevantParts, selectedParts, pricedParts et unpricedParts. Un unpricedParts élevé est un signal d’alerte, pas un détail.
• `revenuePotential` donne min, average et max. La fourchette reste entièrement visible — elle n’est pas réduite à un chiffre.
• `purchaseRecommendation.goodPurchasePriceEur` est le montant pour la discussion dans la cour : recoveryRate fois le minimum, moins le coût supposé par pièce évaluée.
• `assumptions.priceBasis` indique min. Le résultat documente ainsi la base sur laquelle repose la recommandation.
• `parts[]` porte rank, référence, désignation, catégorie et pricing avec min, average, max, confidence et evaluatedAt. Les montants de pricing valent à l’unité.
• `amount` provient tel quel de la liste du fournisseur, n’est pas vérifié et n’entre dans aucun calcul. Le calcul retient une unité par pièce.

Facturation : le forfait VIN mensuel

• VIN Vehicle, VIN Parts et VIN Cart Check forment le forfait `VIN_MONTHLY_LOOKUP`. La facturation et les répétitions sont régies exclusivement par les conditions convenues. La réutilisation du cache ou d’un résultat ne modifie pas la facturation client.
• L’en-tête `X-Tapinoma-Billing-Bundle` est présent lorsqu’un appel relève de ce plafond. X-Tapinoma-Billing-Source nomme en plus la décision de facturation.
• Un plan s’applique par clé d’endpoint, pas globalement. Si aucun plan ne couvre l’appel ou si le quota mensuel est épuisé, le solde est débité ; s’il ne suffit pas, l’API répond 402 insufficient_credits.
• `404 vin_not_resolvable` signale un rapprochement non effectué ; son traitement commercial suit les conditions affichées avant la commande et convenues au contrat.
• Le sandbox suit les conditions convenues. Il utilise la même adresse de base, ne répond qu’avec des données de test synthétiques documentées et se comporte comme indiqué pour la validation, les limites de débit et les états asynchrones — l’endroit pour construire la gestion du 202.

Le déroulé à l’achat

1. Saisir le VIN — à la main, depuis le certificat via POST /scanner/document/registration, ou depuis le véhicule via POST /scanner/vin/extract. Dix-sept caractères, sinon 400 invalid_vin.
2. Rapprocher le véhicule et consigner tapiId, le matchLevel des appels suivants et incomplete dans le dossier.
3. Demander la liste des pièces et traiter proprement le 202. Enregistrer la référence du travail, interroger à l’intervalle indiqué.
4. Demander l’évaluation avec vos hypothèses, pas les valeurs par défaut. Votre entreprise connaît son taux et son coût par pièce mieux que toute valeur par défaut.
5. Afficher ensemble recommandation, fourchette et couverture. Un chiffre sans coverage à côté inspire une confiance que les données ne justifient pas.
6. Planifier le démontage selon rank. Les premières positions portent le revenu ; le reste décide du temps d’occupation du hall.
7. Recalculer après la vente : revenu obtenu contre recommandation, pièces évaluées contre pièces vendues. C’est ainsi que naît votre propre recoveryRate fiable.

Des limites à connaître

• Une évaluation n’est pas une garantie de prix. Elle est indicative, repose sur des offres et des hypothèses, et ne remplace pas l’inspection. Aucune requête VIN ne voit les dommages, le kilométrage ou l’intégralité.
• La couverture dépend de la source. Selon le constructeur, l’année et le marché, les données disponibles varient. incomplete, missingCategories et unpricedParts rendent cela visible.
• Un VIN se rattache à un véhicule et peut devenir une donnée personnelle. Ne transmettez que ce que vous êtes autorisé à transmettre, et seulement ce que la finalité exige. La conservation dans votre système suit votre contrat et vos délais de suppression.
• `vehicle_type_candidates` n’est pas une affirmation de compatibilité. À ce niveau, la liste décrit le type, pas le véhicule individuel.
• La liste des pièces n’est pas un inventaire. Elle dit ce qui peut être monté sur ce type — pas ce qui est encore monté et vendable sur ce véhicule. L’inspection fait la différence.

Schémas, codes d’erreur et exemples de réponse figurent dans la documentation développeur. Dès que le véhicule évalué devient des pièces, la suite est dans De la référence OE à l’article prêt pour la marketplace et, lorsque ces pièces sont sur l’établi, dans De la photo de pièce à l’annonce : la voie image de l’API tapinomahub.