Systèmes de gestion de concession : réception et rapprochement par l’API

Où les données manquent dans le processus

Un DMS crée des véhicules à de nombreux endroits : à la reprise, à l’achat d’occasion, à la réception après-vente d’un véhicule d’une autre marque, à l’import d’une flotte. Chaque fois, un certificat d’immatriculation est posé sur le comptoir, et chaque fois quelqu’un en reporte les champs à la main.

• Reprise. Le client est assis à côté pendant que le vendeur tape VIN, première immatriculation et codes dans le masque d’évaluation. Une inversion de chiffres dans le VIN n’apparaît que lorsque la place de marché rejette la fiche.
• Dossier technique. Ce que le certificat n’indique pas — boîte, transmission, carrosserie — est complété de mémoire, depuis un site constructeur, ou pas du tout. Pour les autres marques, l’accès constructeur manque entièrement.
• Texte d’annonce. Titre et description sortent de modules de texte qui correspondent au véhicule ou non.
• Réception après-vente. Quelles campagnes de rappel sont publiées pour la série, le conseiller le cherche dans un portail constructeur hors du DMS — pour les autres marques, souvent pas du tout. Savoir si une campagne a été réalisée sur le véhicule précis, seul le portail constructeur y répond, même avec l’API.
• Commande de pièces. Savoir si une référence OE convient à ce véhicule précis, le magasin le décide d’après le catalogue et l’expérience. Pour les composants à nombreuses variantes, c’est une source fréquente d’erreurs de commande.

Ce que l’API fournit

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

1. Photographier le certificat. Le vendeur photographie le certificat d’immatriculation dans l’application du DMS. Le DMS enregistre le fichier sur son propre serveur et transmet son adresse comme fileUrl à POST /vehicles/intake ; les photos du tour du véhicule, 5 prises au plus, partent comme photoUrls.
2. Écrire la réponse dans le dossier. Les champs du document remplissent VIN, première immatriculation et données de type ; les données véhicule avec la tapiId remplissent le dossier technique ; le rapport d’état est joint. components dit pour chaque composant s’il a été fourni ; un composant non fourni laisse ses champs vides et est remboursé au prorata. Le rapprochement dans l’intake passe toujours par le fournisseur 2 ; provider dans la réponse vaut toujours 2.
3. Rapprochement fournisseur 1 en alternative. Si le véhicule doit être rapproché via le fournisseur 1, GET /vin/{vin}/vehicle répond à un système tiers par redirect_required. Le DMS crée alors côté serveur, avec POST /vin/redirect-sessions, une session à partir de vin, de la returnUrl HTTPS absolue et d’un state pour sa propre opération, puis envoie le vendeur vers la redirectUrl.
4. Traiter le retour. Après le rapprochement dans l’interface tapinoma, le vendeur revient sur la returnUrl — avec status=completed, tapiId et state, ou avec status=cancelled. Aucune donnée véhicule, d’équipement ou d’accès ne figure dans la redirection ; la session expire au bout de dix minutes.
5. Recharger les données véhicule. Avec la tapiId enregistrée, le DMS appelle GET /vehicles/{tapiId} dans le cadre du parcours VIN déjà facturé — sans VIN et sans équipement.
6. Générer l’annonce. POST /vehicles/{tapiId}/listing avec language et des notes du vendeur optionnelles dans notes renvoie titre, description et points forts d’équipement. Le texte n’invente aucune caractéristique et ne mentionne ni prix ni état.
7. Préparer l’après-vente. GET /recalls/vehicles/{vin} liste les campagnes de la série issues des registres officiels. Condition : la VIN a été rapprochée auparavant via POST /vehicles/intake ou un déroulé VIN de ce client, car elle est résolue uniquement à partir du propre stock constitué par une requête VIN antérieure, sans appel au fournisseur ; sinon le point d’entrée répond 404 vin_not_resolvable. Son traitement commercial suit les conditions affichées avant la commande et convenues au contrat. Savoir si une campagne a été réalisée sur le véhicule précis, seul le constructeur y répond. Avant une commande de pièces, POST /vin/cart-check contrôle jusqu’à 30 positions OE contre le véhicule (mode=vehicle) ou le type (mode=type) ; pour les calculateurs, le codage reste l’affaire de l’atelier, voir Calculateurs d’occasion : codage, antidémarrage, annonce.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <NUMERO_DOSSIER>' \
  -d '{"fileUrl": "https://dms.example/certificats/4711.pdf", "photoUrls": ["https://dms.example/photos/4711-avant.jpg"]}' \
  'https://api.tapinomahub.com/vehicles/intake'

L’intégration

1. Garder la clé côté serveur. La clé API part comme en-tête X-Api-Key depuis le backend du DMS et va dans sa configuration — jamais dans l’interface navigateur, jamais dans une application mobile, jamais dans le code source.
2. Choisir un point d’entrée. POST /vehicles/intake est le point de départ naturel, car il couvre la réception du véhicule en un seul appel. Qui veut seulement lire le certificat commence par POST /scanner/document/registration.
3. Définir la correspondance des champs. Quel champ de la réponse va dans quel champ du dossier ? Cette correspondance est le vrai travail. Le dossier a en outre besoin d’un champ pour la tapiId et d’une mention indiquant quelles valeurs viennent de la requête.
4. Distinguer résultat vide et erreur. 404 vehicle_not_found n’est pas une erreur mais une issue : non trouvé. Le DMS crée quand même le dossier, laisse les champs vides et génère une reprise — « aucun résultat » n’apparaît jamais à l’utilisateur comme un message d’erreur rouge. Une connexion interrompue, en revanche, peut être rejouée, avec le même Idempotency-Key.
5. Récupérer les opérations longues. Si un point d’entrée répond 202, Location et Retry-After désignent le job et le délai d’attente. Le statut se récupère sur le point d’entrée de job, pour le contrôle des pièces via GET /vin/cart-check/jobs/{jobId} — pas en rappelant une seconde fois le point d’entrée initial.
6. Déployer et observer. D’abord une concession pilote, puis le reste. GET /client/usage et l’en-tête de réponse X-Tapinoma-Usage-Warning montrent la consommation de crédit. Le chemin du contrat à la mise en service est décrit dans le guide d’intégration.

Points de vigilance

• Définir un `Idempotency-Key`. Si une connexion s’interrompt, le DMS rejoue l’appel avec la même clé et reçoit la même réponse, reconnaissable à l’en-tête X-Tapinoma-Idempotent-Replay. Exception : les appels qui délivrent une clé secrète (sous-utilisateurs, espaces partenaires) ; après un délai dépassé, rapprocher avec l’existant au lieu de rejouer à l’aveugle.
• Laisser vides les champs vides. Si la réponse renvoie null, le champ reste vide — ni valeur par défaut, ni déduction à partir de l’identifiant constructeur mondial. Une mention plausible dans une annonce est plus dangereuse qu’un manque visible.
• Enregistrer la `tapiId`. Elle est stable et ouvre GET /vehicles/{tapiId} et POST /vehicles/{tapiId}/listing. Qui la perd paie de nouveau le rapprochement.
• Jamais la clé dans le navigateur. L’interface parle à son propre backend, le backend à l’API. La session de redirection pour le fournisseur 1 est elle aussi créée côté serveur ; le navigateur ne voit que la redirectUrl.
• Fixer des limites de débit par utilisateur. PUT /client/users/{clientId}/rate-limits limite par utilisateur, clé ou point d’entrée, pour qu’un import défectueux n’épuise pas le crédit de toute la concession.
• Faire contrôler le résultat. Texte d’annonce, liste de rappels et avis de compatibilité sont des aides au travail. Le vendeur lit le texte avant la diffusion, le conseiller vérifie les rappels de la série contre le portail constructeur, et complete=false signifie qu’un non n’est pas définitif.

Ce que l’API ne fait pas

L’API ne fournit ni évaluation ni expertise : le rapport d’état de POST /vehicles/intake décrit le visible, il ne calcule ni réparation ni valeur résiduelle. Elle n’interroge pas le titulaire et ne garantit aucun prix — le texte d’annonce ne mentionne volontairement aucun prix. Le fournisseur 1 n’est accessible aux systèmes tiers que par la redirection navigateur. Et elle ne vend aucun jeu de données : ce qui est dû, c’est la requête ou l’analyse avec son résultat ; l’usage relève de la concession. Ce que le matériel ne donne pas reste une lacune — pourquoi, c’est expliqué dans Requête VIN en pratique : déroulé, résultat, facturation.