La pièce convient-elle ? Vérifier le panier face au VIN

Un client met trois pièces au panier et saisit son numéro de châssis. Deux conviennent, une appartient à une autre motorisation de la même série. Si cela n’apparaît pas en caisse, cela apparaît au montage — et coûte alors port, retour, avoir et un client mécontent.

Le contrôle du panier prend tout le panier en un appel. Si le résultat est disponible aussitôt, il revient directement avec 200. Si un contrôle du véhicule ne peut pas être terminé immédiatement, l’API répond 202 avec un jobId, et le résultat est récupéré via l’endpoint de statut.

Ce que ce cas suppose

• Un numéro de châssis fourni par le client. Sans lui, aucune référence à contrôler.
• Les lignes du panier sous forme de références. Le texte libre n’est pas contrôlable ; d’où la normalisation en premier.
• Un endroit dans la caisse qui peut attendre le résultat. Si l’API répond 202, le résultat n’est disponible que via l’endpoint de statut — l’interface doit le refléter.
• Une règle pour le cas `fits=false` avec `complete=false`. Autoriser avec avertissement ou bloquer : c’est une décision commerciale.
• Le droit d’interroger le véhicule. Par l’appel, vous confirmez être détenteur, propriétaire ou mandaté de façon prouvée, ou autrement habilité en droit, et utiliser le numéro de châssis exclusivement pour la finalité licite indiquée.

Le déroulement

Le tableau indique pour chaque étape l’appel compétent et ce qui existe ensuite. La justification de l’étape figure en dessous.

Pourquoi chaque étape est nécessaire

1. Normaliser les références. GET /parts/oe/normalize transforme une saisie manuelle en lookupKey. Sans cette étape, on contrôle aussi tirets et espaces, et le panier échoue pour une question de forme.
2. Contrôler le panier. POST /vin/cart-check prend d’une à 30 lignes d’un coup dans oeNumbers, avec vin et le champ obligatoire mode (type ou vehicle). Un appel pour tout le panier remplace une requête par ligne ; la réponse conserve l’ordre et les doublons de l’entrée.
3. Récupérer le résultat. Après une réponse 202, GET /vin/cart-check/jobs/{jobId} renvoie le statut ; en cas de succeeded, result contient oe et fits par ligne et complete pour le panier. Si complete=false, un résultat négatif isolé n’est pas une exclusion définitive.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: korb-88213' \
  -d '{"vin":"<VIN>","country":"de","mode":"vehicle","oeNumbers":["8K0959455K","1K0121207AK"]}' \
  'https://api.tapinomahub.com/vin/cart-check'

Ce que l’on obtient

Il reste une caisse qui avertit le client avant le paiement. Cela réduit le taux de retour, et du bon côté : non par des conditions de retour plus strictes, mais par moins de commandes erronées.

Où cela figure dans la documentation

Les listes de champs contractuelles, les codes d’erreur et les réponses d’exemple se trouvent dans le contrat OpenAPI de cette surface, à l’adresse docs.tapinomahub.com (tapinoma-hub). Tous les cas d’usage classés par surface et par rôle : aperçu des cas d’usage.