De la photo de pièce à l’annonce : la voie image de l’API tapinomahub

Celui qui veut croître dans la vente de pièces en ligne achoppe rarement sur le stock et presque toujours sur la saisie. La pièce est démontée, la référence figure sur la plaque, et les minutes partent malgré tout en ressaisie, en recherche de catégorie et en détourage. La voie image de l’API tapinomahub inverse l’ordre : la photo n’est pas la dernière chose ajoutée à une annonce, c’est la première dont l’annonce naît.

Ce que la voie image suppose

• Une adresse d’image accessible. Les services d’image acceptent imageUrl, pas un fichier téléversé. L’image doit donc être accessible depuis votre stockage, votre boutique ou un espace objet signé — une adresse à durée limitée suffit.
• Une prise de vue qui porte de l’information. Une vignette de 200 pixels ne contient aucune plaque lisible. Chargez la plus grande version disponible, pas celle qu’affiche votre catalogue.
• Le droit sur l’image. En envoyant la requête, vous confirmez être autorisé à la transmettre pour un traitement automatisé. Un contenu à caractère personnel — une plaque d’immatriculation à l’arrière-plan — exige une base légale et doit, si possible, rester hors du cadre.
• Un choix de niveau de traitement. quality accepte standard, enhanced et maximum. Les niveaux diffèrent en étendue et en temps de réponse ; leur coût relève de votre contrat.

Étape 1 : lire l’étiquette

POST /scanner/label/extract-all analyse la photo d’une étiquette et renvoie toutes les informations reconnues avec une certitude suffisante, sous forme structurée — pas seulement la référence. C’est l’appel le plus substantiel de la voie et il remplace l’essentiel du travail manuel. Usage et facturation sont détaillés dans Extraire toutes les informations détectables d’une étiquette.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: piece-4711-etiquette' \
  -d '{"imageUrl":"https://example.com/calculateur.jpg","quality":"maximum"}' \
  'https://api.tapinomahub.com/scanner/label/extract-all'

Étape 2 : faire d’une lecture une référence fiable

Une chaîne lue sur une étiquette n’est pas encore une référence OE. Elle peut porter des tirets inconnus du catalogue, être une référence de fournisseur ou correspondre à plusieurs fabricants. Deux appels tranchent avant tout enregistrement.

1. `GET /parts/oe/normalize` contrôle l’écriture et répond par status : matched, unresolved, ambiguous ou invalid. En cas de correspondance, la réponse porte normalizedOeNumber, lookupKey, matchRule et confidence, ainsi que equivalentOeNumbers. Voir Normaliser et valider un numéro OE.
2. `POST /parts/identify` décide lorsque plusieurs sources entrent en jeu. L’appel prend la référence client, la lecture de l’étape 1 dans labelReadings et, si disponible, le VIN du véhicule donneur. Il renvoie status avec matched, candidates ou unresolved, source avec customer, label ou vin_parts_list, et une liste de candidats avec score et reasons.
3. Avec `candidates`, un humain décide. La liste est classée et motivée ; c’est une présélection, pas une décision. C’est exactement là qu’une file de contrôle doit exister dans l’ERP, et non un transfert automatique.
4. Avec `unresolved`, le champ reste vide et le dossier reçoit une tâche. Une pièce non identifiée peut être photographiée, stockée et identifiée plus tard — elle n’est pas mise en vente.

Étape 3 : la fiche derrière la référence

Avec une référence confirmée, GET /parts/oe/{oeNumber} renvoie la désignation, le fabricant, les affectations véhicule dans fitment, les arêtes de remplacement documentées dans replacementChain et les références regroupées par fabricant dans references. Cette partie de la voie est décrite en détail dans De la référence OE à l’article prêt pour la marketplace — avec le sens de chaque champ et la raison pour laquelle une référence ne devient jamais une affirmation de compatibilité.

Étape 4 : l’image de galerie

La première image décide du clic. POST /vision/part/remove/bg détoure la pièce et renvoie un PNG : avec background: "transparent" un canal alpha, avec background: "white" un blanc pur. La valeur par défaut est transparent, car le blanc peut être ajouté ensuite mais jamais retiré. L’appel est décrit dans Détourer la photo d’une pièce.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"imageUrl":"https://example.com/pare-chocs.jpg","background":"transparent","partType":"pare-chocs avant"}' \
  'https://api.tapinomahub.com/vision/part/remove/bg'

• `found` indique si un objet a été reconnu. Si la valeur est false, imageUrl vaut null — et l’annonce conserve sa photo d’origine au lieu d’afficher un cadre vide.
• `coverage.cropped` et `coverage.touchesImageEdge` signalent que l’objet dépasse le bord du cadre. Ces prises de vue sont à refaire, pas à publier.
• `sourcePixelsPreserved` confirme que les pixels de l’objet proviennent de la photo soumise. Le procédé détermine le contour ; il ne repeint pas la pièce.
• `limitations` nomme ce qui est resté incertain — une arête dans l’ombre, par exemple. Cette indication appartient à la liste de contrôle de validation.
• `422 part_segmentation_failed` est la réponse honnête lorsque la pièce n’a pu être séparée de façon fiable du fond ou des surfaces voisines. Aucune image à moitié détourée n’est renvoyée.

Étape 5 : les identifiants qui n’ont rien à faire en ligne

Calculateurs, combinés d’instruments et clés portent des numéros qui ne désignent pas le type de pièce mais l’exemplaire : numéros de série, IMEI, codes de calibration, champs data matrix. POST /vision/identifiers/redact les rend illisibles et ne renvoie une image que si l’anonymisation a pu être confirmée — sinon 422 identifier_redaction_unverified et aucune image. L’enjeu commercial et juridique est exposé dans Anonymiser les identifiants sur les photos sans perdre la référence OE.

Étape 6 : l’état que l’acheteur veut voir

POST /vision/part/quality prend une à trois photos de la même pièce et renvoie un classement : grade avec A, B ou C, les critères dans criteria — traces d’usage, corrosion, déformation, rayures, état de la peinture, intégralité, salissure —, plus reworkEffort et refinishEffort comme classes d’effort. visualOnly précise sur quoi repose le jugement : le visible. Une boîte de vitesses remplie de copeaux paraît normale de l’extérieur. Si l’image ne permet pas de classer, la réponse porte gradable: false avec une explication dans reason, et aucun niveau n’est deviné. Plus de détails dans Évaluer une pièce d’occasion sur images : état, dommages et limites.

Ce que coûte la voie et comment elle se comporte

• L’analyse est la prestation. Un service d’image qui s’exécute et répond a livré — même si la photo ne montrait aucune référence. On rembourse un échec, pas un constat vide. D’où l’intérêt d’écarter les photos floues avant, plutôt que d’en discuter après.
• `Idempotency-Key` protège de la double facturation. Une répétition avec la même clé renvoie le même résultat sans nouvelle exécution. Pendant le premier appel, l’API répond 409 idempotency_request_in_progress.
• Un appel à la fois par client. Les requêtes parallèles supplémentaires sont refusées avec 429 client_request_in_progress. Une file d’attente dans l’ERP est donc obligatoire, pas une finition.
• `402 insufficient_credits` signifie qu’aucun plan ne couvre l’endpoint et que le solde et le découvert ne suffisent pas. L’en-tête X-Tapinoma-Usage-Warning avertit avant, dès 90 pour cent de consommation du plan.
• Les résultats appartiennent à votre base. Pas d’appel à chaque affichage de page, pas de seconde requête pour le même article. Les champs des étapes 1 à 3 ne changent pas tant que la pièce reste la même.

L’intégration dans l’ERP, la boutique et la marketplace

1. Fixer la routine de prise de vue : une photo de la pièce, une de la plaque, toutes deux en résolution maximale et sous une adresse accessible.
2. Appeler l’étape 1 et enregistrer la réponse intégralement, pas seulement la référence. Les autres champs font partie de la réponse à cette commande et répondront plus tard à des questions que personne ne pose aujourd’hui.
3. Exécuter l’étape 2 et consigner le résultat comme matched, candidates ou unresolved — avec confidence et source, pour que l’origine de la référence reste explicable.
4. Récupérer les données pièce et marketplace, puis mapper les champs sur vos champs article. Ce mapping est le vrai travail d’intégration, pas l’appel.
5. Produire les images : l’image de galerie détourée et, pour l’électronique, la version anonymisée. Déposer les deux fichiers dans votre stockage au lieu de pointer vers l’adresse de réponse.
6. Tracer la limite de validation : toute publication automatique exige une référence confirmée, une image avec found: true et un niveau d’état. Le reste va en file de contrôle.
7. Mesurer après deux semaines : temps de traitement par article, part de la file de contrôle, taux de correction après publication, retours pour mauvaise compatibilité.

Des limites à connaître

• Aucune image ne donne la compatibilité. L’affectation vient de la référence confirmée et des données de référence, pas de la photo. Une liste d’utilisation est une documentation, pas une garantie.
• Les dommages cachés restent cachés. Le classement est explicitement visuel. Les organes mécaniques exigent un essai fonctionnel — et cet essai appartient à la description de l’article.
• Les noms de fabricants et de marques sont des renvois, pas une indication d’origine. Une pièce d’occasion est décrite comme telle. Les indications trompeuses sur des caractéristiques essentielles sont illicites, quelle que soit la source des données.
• Les données marketplace sont un contenu de publication, jamais une affirmation de compatibilité. Avant de publier, l’entreprise contrôle ce qu’elle publie : titre, catégorie et caractéristiques.
• La couverture n’est pas homogène. Les séries rares et les pièces très anciennes sont moins documentées. Une liste vide informe sur les données, pas sur la pièce.

Les schémas complets, les codes d’erreur et les exemples de réponse figurent dans la documentation développeur. Pour construire le même article à partir de la référence ou du véhicule plutôt que de l’image, voir De la référence OE à l’article prêt pour la marketplace et Du VIN à l’analyse de rentabilité : la voie véhicule.