Ein belastbarer End-to-End-Prozess für ERP-Anbieter, Teilehändler und Verwerter, Marktplätze sowie Integratoren – mit sauberer Mandantentrennung und nachvollziehbaren Prüfentscheidungen.
Zwei Einstiegspfade, ein konsistenter Teile-Datensatz.
01 · Idealprozess
Zwei sichere Wege zur Teileidentität
Die Pfade können einzeln funktionieren. Liegen Etikett und Spenderfahrzeug vor, werden sie zusammengeführt: Die OE-Nummer identifiziert das Teil, die VIN liefert den Fahrzeugkontext.
A
Etikett → OE-Abfrage
Optimal für ausgebaute, gelagerte oder einzeln angelieferte Teile.
Bild erfassenEtikett gerade, scharf und vollständig fotografieren; Bildrecht und Übermittlungsbefugnis sicherstellen.
Alle Merkmale extrahierenPOST /scanner/label/extract-all mit quality=low starten; nur bei unzureichendem Ergebnis höher gehen.
Nummern als Kandidaten behandelnprimary_part_number, weitere Teilenummern, Hersteller, Variante und Produktionsdaten getrennt übernehmen.
OE-Kandidaten bestätigenJede plausible Nummer über GET /parts/oe/{oeNumber} abgleichen und Ersetzungsketten beachten.
Optional anreichernAftermarket-Referenzen, Preisbewertung und SEO nur nach erfolgreicher OE-Bestätigung abrufen.
Prüfstatus setzenTreffer, Widersprüche und verwendete Quellen am Mandanten-Datensatz protokollieren; unklare Fälle in die manuelle Prüfung geben.
B
Fahrzeugschein → VIN & VIN-Teile
Optimal für Verwerter, Fahrzeugannahme und Teile aus bekanntem Spenderfahrzeug.
Dokument erfassenFahrzeugschein nur mit gültiger Berechtigung scannen; personenbezogene Felder im Kundensystem minimieren.
VIN extrahieren und prüfenPOST /scanner/vin/extract für Fahrzeugfotos oder POST /scanner/registration-document für Fahrzeugschein-Bild/PDF; VIN auf 17 Zeichen und Lesefehler prüfen.
Fahrzeug abgleichenGET /vin/{vin}/vehicle. Provider 1 nutzt den dokumentierten Browser-Redirect, Provider 2 und 3 den Direktabruf.
Stabile Referenz sicherntapiId, Fahrzeuganzeige und die tatsächlich verwendete Provider-Bindung am Mandanten-Fahrzeug speichern.
VIN-Fahrzeug, dann VIN-TeileGET /vin/{vin}/parts ohne abweichenden Provider. Bei Provider 1 schließt der Job zwingend zuerst den Fahrzeugabgleich ab und ermittelt erst danach die Teile. Bei 202 die Job-URL gemäß Retry-After abfragen.
Treffercharakter bewertenmatchLevel, fehlende Kategorien und Varianten berücksichtigen; Kandidaten sind nicht automatisch Einbaugarantien.
✓
Zusammenführung: OE-Treffer ∩ VIN-Kontext
Übereinstimmung von bestätigter OE-Nummer und VIN-Teileliste ist das stärkste Signal. Bei Abweichung nicht automatisch korrigieren, sondern Quelle, Variante, Ersetzungskette und Teilfoto prüfen.
02 · Zielgruppen
Ein Prozess, vier Betriebsmodelle
Der fachliche Kern bleibt gleich. Verantwortlichkeit, Speichertiefe und Übergabepunkt unterscheiden sich je nach Rolle im Ökosystem.
ERP
ERP-Anbieter
Orchestriert den Prozess und speichert operative Daten strikt auf Mandantenebene.
Jeden ERP-Mandanten auf einen eigenen tapinoma-Workspace/API-Key und eigene Nutzungsgrenzen abbilden.
Hub-Konditionen nur aktiv und endpunktspezifisch über PUT /client/sponsorship-grants/{grantReference} freigeben.
tenant_id bei Fahrzeug, Teil, Scan-Auftrag, Prüfentscheidung und Export erzwingen.
Globale Stammdaten nur dort teilen, wo Vertrag und Rechte dies erlauben; keine Rohdokumente mandantenübergreifend cachen.
Idempotente Importjobs und fachliche Statuswerte statt bloßer „API erfolgreich“-Flags verwenden.
DMS
Teilehändler & Verwerter
Arbeitet im eigenen System; der Hub ergänzt den bestehenden Artikel- und Demontageprozess.
Etikettfoto direkt am Lagerplatz oder während der Demontage aufnehmen und mit interner Artikel-ID verknüpfen.
Spender-VIN einmal am Fahrzeug erfassen; tapiId und geprüfte Fahrzeugdaten für alle zugehörigen Teile wiederverwenden.
Zustand, Laufleistung, Lagerplatz und eigene Bilder bleiben führend im Händlersystem.
Nur grüne Treffer automatisch freigeben; Varianten, Sicherheitsbauteile und Widersprüche durch Fachpersonal prüfen.
Market
Marktplätze
Übernimmt bereits geprüfte Angebote oder bietet eine geführte Erfassung für Verkäufer.
Mandant ist der Verkäufer bzw. Händler; Angebote, Kontingente und Herkunftsnachweise bleiben getrennt.
Veröffentlichung erst nach fachlicher Freigabe und mit sichtbarer Unterscheidung zwischen fahrzeugspezifischem Treffer und Typ-Kandidat.
Keine Kompatibilitätsbehauptung aus einer Aftermarket-Referenz allein ableiten.
Kanalspezifische Titel und SEO von der geprüften Teileidentität ableiten, nicht umgekehrt.
Connect
Integratoren
Übersetzt zwischen Hub-Prozess und den Objekt-/Jobmodellen angebundener Systeme.
Connector hält Hub-Antworten in einer versionsfesten Zwischenschicht; Feldmapping nicht direkt an UI-Felder koppeln.
Account/Mandant eindeutig einem Hub-Unter-Nutzer zuordnen und API-Keys niemals gemeinsam über Kunden hinweg nutzen.
202-Jobs asynchron und mit Retry-After verarbeiten; keine kurzen Dauer-Polling-Schleifen.
Original-Antwort, Mapping-Version und Exportstatus nachvollziehbar, aber datensparsam protokollieren.
03 · Daten & Mandanten
Klare Grenzen statt Datenkopien
Das Kundensystem bleibt führend für Bestand und Angebot. Hub-Ergebnisse werden als belegte Anreicherung mit Quelle und Prüfstatus gespeichert.
04 · PrüfungverificationAmpel, Gründe, Prüfer oder Automatikregel
05 · Ausgabechannel_offerPreis, Text, Kanalstatus und Exportversion
04 · API-Rezepte
Der Prozess als konkrete Aufrufkette
Die Beispiele zeigen die Orchestrierung. Pflichtfelder, vollständige Antwortschemata, Nutzungsbedingungen und aktuelle Preise stehen in der API-Dokumentation.
GET4. Fahrzeug binden, Teile abrufen, Job verfolgen/vin/{vin}/vehicle → /vin/{vin}/parts
Zweck: Stabile Fahrzeugreferenz und Teileliste mit maschinenlesbarem Treffercharakter erhalten.
Provider 1 kann den Browser-Redirect erfordern.
Bei Provider 1 gilt auch im asynchronen Job zwingend: erst erfolgreicher Fahrzeugabgleich mit tapiId, dann Teileabruf. Ohne Fahrzeugkontext wird kein Teileergebnis freigegeben.
Nach der Fahrzeugabfrage Provider bei der Teileabfrage weglassen.
Bei 202Location und Retry-After beachten; Status über GET /vin/parts/jobs/{jobId} abrufen.
# Direktabruf-Beispiel mit Provider 2
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/vehicle?country=de&provider=2'
# Gebundenen Provider automatisch wiederverwenden
curl -i -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/parts?country=de'
# Nur bei 202: Status-URL aus der Antwort abfragen
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/parts/jobs/<JOB_ID>'
PUT5. Hub-Konditionen aktiv sponsern/client/sponsorship-grants/{grantReference}
Zweck: Ein ERP gibt ausgewählten tapinoma-Workspaces seine Konditionen ausdrücklich für Hub-Abfragen frei.
Der ERP-Master ruft den Endpunkt mit dem eigenen API-Key auf.
Workspace, Endpunkte, Kanal hub und Laufzeit werden explizit festgelegt.
Die Oberfläche liest eingehende Grants über GET /client/sponsorship-grants/received und zeigt Sponsor, Umfang und Status an.
Ein Widerruf beendet nur die künftige Kostenübernahme, nicht den direkten tapinoma-Account oder vorhandene Ergebnisse.
Die Ampel ist eine Empfehlung für das Kundensystem, kein Feld der Hub-API. Sie muss aus belegbaren Signalen und fachlichen Regeln entstehen.
Grün · automatisch freigabefähig
OE-Treffer bestätigt, Nummer eindeutig, Label-Hersteller plausibel und – falls vorhanden – Übereinstimmung mit einer fahrzeugspezifischen VIN-Teileliste. Keine ungeklärte Variante.
Gelb · Fachprüfung
Mehrere Nummernkandidaten, Ersetzungskette, VIN-Typkandidaten, unbestätigte Fahrzeugzuordnung, fehlende Kategorie oder abweichende Variantenmerkmale.
Rot · nicht veröffentlichen
Kein bestätigbarer OE-Treffer, widersprüchliche Hersteller/Nummern, unlesbares Bild, Provider-Mismatch oder fehlende Berechtigung zur Verarbeitung.
Definition of Done
Ein Teil ist prozessual fertig, wenn:
Mandant und interne Artikel-ID eindeutig sind.
OE-Nummer normalisiert und bestätigt ist.
Quelle, Zeitpunkt und API-/Mapping-Version feststehen.
VIN-Kontext samt matchLevel berücksichtigt wurde, falls vorhanden.
Zustand, Bilder und kommerzielle Angaben vom Händler stammen.
Freigabegrund und Kanalstatus nachvollziehbar sind.
Häufige Fehlmuster
Diese Abkürzungen erzeugen später teure Rückläufer:
OCR-Ergebnis direkt als Artikelnummer speichern.
Aftermarket-Referenz als Einbaugarantie darstellen.
Provider nach erfolgter VIN-Bindung wechseln.
202 als Fehler oder als fertige Teileliste behandeln.
Dokumentbilder dauerhaft und mandantenübergreifend cachen.
SEO-Text vor der Teileidentität erzeugen.
06 · Betrieb
Statuscodes werden zu Arbeitszuständen
Integrationen sollten HTTP-Antworten in fachliche Zustände übersetzen. So bleiben ERP, Connector und Marktplatz auch bei asynchronen Antworten konsistent.
Job-ID und Status-URL speichern; erst nach Retry-After erneut abfragen.
Ja, asynchron.
409
Interaktion oder Klärung nötig
Bei redirect_required Redirect-Session starten; bei Provider-Mismatch Bindung respektieren.
Geführt, nicht blind wiederholen.
404
Kein bestätigter Treffer
Kandidaten prüfen, Eingabe korrigieren oder manuelle Recherche anstoßen.
Keine Veröffentlichung.
429
Limit erreicht
Mandantenspezifisch verzögern; Kontingent und Plan sichtbar machen.
Backoff, kein Parallelsturm.
5xx
Temporär nicht verfügbar
Begrenzt und idempotent wiederholen; nach Schwellenwert in Supportzustand wechseln.
Mit Backoff und Obergrenze.
Bereit für die technische Umsetzung?
In der API-Dokumentation stehen alle Endpunkte, Schemas, Antwortfelder und verbindlichen Nutzungshinweise. Dieser Leitfaden beschreibt die empfohlene Orchestrierung im Kundensystem.
A dependable end-to-end process for ERP vendors, parts dealers and dismantlers, marketplaces, and integrators—with strict tenant separation and explainable verification decisions.
Either path can work on its own. When both the label and donor vehicle are available, merge them: the OE number identifies the part while the VIN provides the vehicle context.
A
Label → OE lookup
Best for removed, stored, or individually delivered parts.
Capture the imagePhotograph the label straight-on, sharply and in full; confirm image rights and authority to transmit it.
Extract all attributesStart POST /scanner/label/extract-all with quality=low; increase quality only when needed.
Treat numbers as candidatesKeep primary_part_number, other numbers, manufacturer, variant and production information separate.
Confirm OE candidatesCheck each plausible number using GET /parts/oe/{oeNumber} and account for replacement chains.
Enrich when usefulRequest aftermarket references, price evaluation and SEO only after a successful OE confirmation.
Set a verification stateRecord matches, conflicts and sources on the tenant record; route ambiguous cases to manual review.
B
Registration document → VIN & VIN parts
Best for dismantlers, vehicle intake and parts from a known donor vehicle.
Capture the documentScan only with valid authority; minimise personal fields retained by the customer system.
Extract and validate the VINUse POST /scanner/vin/extract for a vehicle photo or POST /scanner/registration-document for a registration-document image/PDF; check all 17 characters.
Match the vehicleUse GET /vin/{vin}/vehicle. Provider 1 uses the documented browser redirect; providers 2 and 3 allow direct lookup.
Keep the stable referenceStore tapiId, vehicle display data and the actual provider binding on the tenant vehicle.
VIN vehicle, then VIN partsCall GET /vin/{vin}/parts without a conflicting provider. For provider 1, the job must finish the vehicle lookup first and only then determine parts. On 202, poll the job URL according to Retry-After.
Evaluate the match characterAccount for matchLevel, missing categories and variants; candidates are not installation guarantees.
✓
Merge: OE match ∩ VIN context
A confirmed OE number also found in the VIN parts list is the strongest signal. If sources disagree, do not auto-correct: inspect the source, variant, replacement chain and part image.
02 · Audiences
One process, four operating models
The subject-matter core stays the same. Ownership, storage depth and hand-off points differ by role in the ecosystem.
ERP
ERP vendors
Orchestrate the process and store operational data strictly at tenant level.
Map each ERP tenant to its own tapinoma workspace/API key and usage limits.
Explicitly enable Hub conditions per endpoint through PUT /client/sponsorship-grants/{grantReference}.
Enforce tenant_id on vehicles, parts, scans, decisions and exports.
Share master references only where contract and rights permit it; never cache raw documents across tenants.
Use idempotent import jobs and business states rather than simple “API succeeded” flags.
DMS
Parts dealers & dismantlers
Work in their own system while the Hub enriches the existing stock and dismantling flow.
Capture the label at the storage bin or during dismantling and link it to the internal part ID.
Capture the donor VIN once; reuse tapiId and verified vehicle data for its parts.
Condition, mileage, location and own photos remain authoritative in the dealer system.
Auto-release green matches only; variants, safety parts and conflicts require a specialist.
Market
Marketplaces
Accept verified offers or provide sellers with a guided capture flow.
The tenant is the seller or dealer; offers, quotas and evidence remain separate.
Publish only after business approval and distinguish vehicle-specific matches from type candidates.
Never infer an installation guarantee from an aftermarket reference alone.
Derive channel titles and SEO from the verified part identity—not the other way around.
Connect
Integrators
Translate between the Hub workflow and connected systems’ object and job models.
Keep Hub responses in a versioned adapter layer; do not map them directly to UI fields.
Map every account/tenant to one Hub sub-user and never share API keys across customers.
Process 202 jobs asynchronously and honour Retry-After; avoid tight polling loops.
Record original response, mapping version and export state in a traceable but data-minimised way.
03 · Data & tenants
Clear boundaries instead of uncontrolled copies
The customer system remains authoritative for inventory and offers. Hub results are stored as sourced enrichment with a verification state.
Tenant-scoped
Never mix between customers
Internal part and vehicle IDs
Scan job and image reference
Condition, location, purchase, seller
Verification decision and export state
Usage, quota and cost centre
Referenceable
Only to the extent contractually permitted
Normalised OE number
tapiId as stable vehicle reference
Replacement chain and catalogue response
Technical designations
API and mapping version
Temporary / minimised
Short retention, narrow purpose
Raw registration-document image
Personal document fields
Publicly retrievable scan URL
Error payloads containing inputs
Debug and support exports
01 · Intakesource_captureTenant, internal ID, image reference, purpose, time
02 · Candidatepart_candidateRecognised numbers and attributes, not released yet
GET4. Bind the vehicle, request parts, track the job/vin/{vin}/vehicle → /vin/{vin}/parts
Purpose: Receive a stable vehicle reference and parts list with a machine-readable match character.
Provider 1 may require the browser redirect.
For provider 1, the asynchronous job must complete the vehicle lookup and create a tapiId before it starts parts lookup. No parts result is released without vehicle context.
After the vehicle lookup, omit the provider from the parts request.
On 202, honour Location and Retry-After; query GET /vin/parts/jobs/{jobId}.
# Direct lookup example using provider 2
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/vehicle?country=gb&provider=2'
# Automatically reuse the bound provider
curl -i -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/parts?country=gb'
# On 202 only: query the status URL from the response
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/parts/jobs/<JOB_ID>'
Purpose: An ERP explicitly makes its conditions available to selected tapinoma workspaces for Hub requests.
The ERP master calls the endpoint with its own API key.
Workspace, endpoints, the hub channel and period are explicit.
The UI reads incoming grants from GET /client/sponsorship-grants/received and displays sponsor, coverage and status.
Revocation stops only future sponsorship; it does not remove the direct tapinoma account or existing results.
05 · Quality
A traffic light with explainable reasons
The traffic light is a recommendation for the customer system, not a Hub API field. It must be derived from evidence and business rules.
Green · eligible for auto-release
Confirmed, unambiguous OE match; plausible label manufacturer and—where available—a match in a vehicle-specific VIN parts list. No unresolved variant.
Amber · specialist review
Multiple number candidates, replacement chain, VIN type candidates, unverified vehicle assignment, missing category or conflicting variant attributes.
Red · do not publish
No confirmable OE match, conflicting manufacturer/number, unreadable image, provider mismatch or missing authority to process the data.
Definition of done
A part is complete when:
Tenant and internal part ID are unambiguous.
The OE number is normalised and confirmed.
Source, time and API/mapping version are recorded.
VIN context and matchLevel have been considered where available.
Condition, images and commercial data come from the dealer.
Release reason and channel state are traceable.
Common anti-patterns
These shortcuts create expensive returns:
Saving OCR output directly as the part number.
Presenting an aftermarket reference as an installation guarantee.
Changing provider after the VIN has been bound.
Treating 202 as an error or completed parts list.
Caching document images permanently or across tenants.
Generating SEO copy before identifying the part.
06 · Operations
Turn HTTP status into work states
Integrations should translate HTTP responses into domain states. ERP, connector and marketplace then remain consistent across asynchronous operations.
Response
Business state
Customer-system action
Automation
200
Result available
Store response, run rules, update verification light.
Yes, when business criteria pass.
202
VIN parts job accepted
Store job ID and status URL; retry only after Retry-After.
Yes, asynchronously.
409
Interaction or clarification needed
Start redirect session for redirect_required; respect binding on provider mismatch.
Guided, never blind retries.
404
No confirmed result
Review candidates, correct input or start manual research.
Do not publish.
429
Limit reached
Delay per tenant; surface quota and plan.
Backoff, no retry storm.
5xx
Temporarily unavailable
Retry idempotently with a cap; enter support state after threshold.
Backoff with an upper limit.
Ready for the technical implementation?
The API documentation contains every endpoint, schema, response field and binding usage notice. This guide describes the recommended customer-system orchestration.
Un processus de bout en bout fiable pour les éditeurs d’ERP, négociants et recycleurs, places de marché et intégrateurs, avec séparation stricte des mandants et décisions de contrôle explicables.
Chaque parcours peut fonctionner seul. Si l’étiquette et le véhicule donneur sont disponibles, fusionnez-les : le numéro OE identifie la pièce et le VIN fournit le contexte véhicule.
A
Étiquette → requête OE
Idéal pour les pièces déposées, stockées ou livrées individuellement.
Capturer l’imagePhotographier l’étiquette de face, nettement et en entier ; vérifier les droits sur l’image et l’autorisation de transmission.
Extraire tous les attributsCommencer par POST /scanner/label/extract-all avec quality=low ; augmenter seulement si nécessaire.
Traiter les numéros comme candidatsConserver séparément primary_part_number, les autres numéros, le fabricant, la variante et les données de production.
Confirmer les candidats OEContrôler chaque numéro plausible avec GET /parts/oe/{oeNumber} et tenir compte des chaînes de remplacement.
Enrichir si utileNe demander références aftermarket, évaluation de prix et SEO qu’après confirmation OE.
Définir l’état de contrôleConsigner correspondances, contradictions et sources sur la fiche du mandant ; transmettre les cas ambigus au contrôle manuel.
B
Carte grise → VIN & pièces VIN
Idéal pour les recycleurs, la réception de véhicules et les pièces d’un véhicule donneur connu.
Capturer le documentScanner uniquement avec une autorisation valable ; minimiser les champs personnels conservés par le système client.
Extraire et valider le VINUtiliser POST /scanner/vin/extract pour une photo du véhicule ou POST /scanner/registration-document pour une image/PDF de la carte grise ; vérifier les 17 caractères.
Identifier le véhiculeUtiliser GET /vin/{vin}/vehicle. Le provider 1 suit la redirection navigateur documentée ; les providers 2 et 3 permettent l’accès direct.
Conserver la référence stableEnregistrer tapiId, l’affichage véhicule et le provider réellement lié sur le véhicule du mandant.
Véhicule VIN, puis pièces VINAppeler GET /vin/{vin}/parts sans provider contradictoire. Pour le provider 1, le job termine d’abord la recherche véhicule avant de déterminer les pièces. Sur 202, interroger l’URL du job selon Retry-After.
Évaluer la nature du résultatPrendre en compte matchLevel, catégories manquantes et variantes ; un candidat n’est pas une garantie de montage.
✓
Fusion : correspondance OE ∩ contexte VIN
Un numéro OE confirmé également présent dans la liste VIN constitue le signal le plus fort. En cas de divergence, ne pas corriger automatiquement : contrôler source, variante, chaîne de remplacement et photo de la pièce.
02 · Publics
Un processus, quatre modèles opérationnels
Le cœur métier reste identique. La responsabilité, la profondeur de stockage et le point de transfert diffèrent selon le rôle dans l’écosystème.
ERP
Éditeurs d’ERP
Orchestrent le processus et stockent les données opérationnelles strictement au niveau du mandant.
Associer chaque mandant ERP à son propre workspace tapinoma/clé API et à ses limites.
Activer explicitement les conditions Hub par endpoint avec PUT /client/sponsorship-grants/{grantReference}.
Imposer tenant_id aux véhicules, pièces, scans, décisions et exports.
Partager les références maîtres uniquement si contrat et droits l’autorisent ; ne jamais mettre en cache les documents bruts entre mandants.
Utiliser des imports idempotents et des états métier plutôt qu’un simple indicateur « API réussie ».
DMS
Négociants & recycleurs
Travaillent dans leur propre système ; le Hub enrichit le processus d’article et de démontage existant.
Photographier l’étiquette au lieu de stockage ou pendant le démontage et la relier à l’ID interne.
Saisir une fois le VIN donneur ; réutiliser tapiId et les données véhicule vérifiées pour ses pièces.
État, kilométrage, emplacement et photos propres restent maîtres dans le système du négociant.
Automatiser seulement les résultats verts ; variantes, pièces de sécurité et contradictions exigent un spécialiste.
Market
Places de marché
Reçoivent des offres déjà contrôlées ou proposent une saisie guidée aux vendeurs.
Le mandant est le vendeur ou négociant ; offres, quotas et justificatifs restent séparés.
Publier après validation métier en distinguant résultat spécifique au véhicule et candidat au niveau du type.
Ne jamais déduire une garantie de montage d’une seule référence aftermarket.
Dériver titres de canal et SEO de l’identité vérifiée de la pièce, jamais l’inverse.
Connect
Intégrateurs
Traduisent entre le workflow Hub et les modèles d’objets et de jobs des systèmes connectés.
Conserver les réponses Hub dans une couche d’adaptation versionnée ; ne pas les lier directement aux champs d’interface.
Associer chaque compte/mandant à un sous-utilisateur Hub et ne jamais partager les clés API entre clients.
Traiter les jobs 202 de façon asynchrone en respectant Retry-After ; éviter les boucles de polling serrées.
Tracer réponse d’origine, version du mapping et état d’export de manière compréhensible mais minimisée.
03 · Données & mandants
Des frontières claires plutôt que des copies incontrôlées
Le système client reste maître du stock et des offres. Les résultats Hub sont enregistrés comme enrichissements sourcés avec un état de contrôle.
Lié au mandant
Ne jamais mélanger entre clients
IDs internes de pièce et véhicule
Job de scan et référence d’image
État, emplacement, achat, vendeur
Décision de contrôle et état d’export
Utilisation, quota et centre de coûts
Référençable
Seulement dans le cadre contractuel
Numéro OE normalisé
tapiId comme référence véhicule stable
Chaîne de remplacement et réponse catalogue
Désignations techniques
Versions API et mapping
Temporaire / minimisé
Durée courte, finalité étroite
Image brute de la carte grise
Champs personnels du document
URL de scan publiquement accessible
Payloads d’erreur contenant les entrées
Exports de débogage et support
01 · Entréesource_captureMandant, ID interne, référence d’image, finalité, date
02 · Candidatpart_candidateNuméros et attributs reconnus, pas encore validés
04 · ContrôleverificationFeu, motifs, contrôleur ou règle automatique
05 · Sortiechannel_offerPrix, contenu, état canal et version d’export
04 · Recettes API
Le processus sous forme d’une chaîne d’appels
Ces exemples montrent l’orchestration. Les champs obligatoires, schémas complets, conditions d’utilisation et prix actuels figurent dans la documentation API.
GET4. Lier le véhicule, demander les pièces, suivre le job/vin/{vin}/vehicle → /vin/{vin}/parts
Objectif : recevoir une référence véhicule stable et une liste de pièces avec une nature de résultat lisible par machine.
Le provider 1 peut exiger la redirection navigateur.
Pour le provider 1, le job asynchrone doit terminer la recherche véhicule et créer un tapiId avant la recherche de pièces. Aucun résultat de pièces n’est publié sans contexte véhicule.
Après la requête véhicule, omettre le provider dans la requête pièces.
Sur 202, respecter Location et Retry-After ; interroger GET /vin/parts/jobs/{jobId}.
# Exemple d’accès direct avec le provider 2
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/vehicle?country=fr&provider=2'
# Réutiliser automatiquement le provider lié
curl -i -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/WVWZZZ1JZXW000001/parts?country=fr'
# Sur 202 uniquement : interroger l’URL d’état de la réponse
curl -H 'X-Api-Key: <API_KEY>' \
'https://api.core.gobecom.com/hub/index.php/vin/parts/jobs/<JOB_ID>'
PUT5. Prendre activement en charge les conditions Hub/client/sponsorship-grants/{grantReference}
Objectif : un ERP met explicitement ses conditions à disposition de workspaces tapinoma sélectionnés pour les requêtes Hub.
Le client maître ERP appelle l’endpoint avec sa propre clé API.
Workspace, endpoints, canal hub et période sont explicites.
L’interface lit les prises en charge reçues avec GET /client/sponsorship-grants/received et affiche sponsor, périmètre et état.
La révocation arrête uniquement les futures prises en charge sans supprimer le compte tapinoma direct ni les résultats existants.
05 · Qualité
Un feu dont les motifs sont explicables
Le feu est une recommandation pour le système client, pas un champ de l’API Hub. Il doit découler de signaux prouvables et de règles métier.
Vert · publiable automatiquement
Correspondance OE confirmée et sans ambiguïté, fabricant plausible et, si disponible, correspondance dans une liste VIN spécifique au véhicule. Aucune variante non résolue.
Orange · contrôle spécialiste
Plusieurs numéros candidats, chaîne de remplacement, candidats VIN au niveau du type, affectation véhicule non vérifiée, catégorie manquante ou variante contradictoire.
Rouge · ne pas publier
Aucun résultat OE confirmable, fabricant/numéro contradictoire, image illisible, conflit de provider ou absence d’autorisation de traitement.
Définition de terminé
Une pièce est prête lorsque :
Mandant et ID interne sont sans ambiguïté.
Le numéro OE est normalisé et confirmé.
Source, date et versions API/mapping sont enregistrées.
Le contexte VIN et matchLevel ont été pris en compte si disponibles.
État, images et données commerciales proviennent du négociant.
Motif de validation et état canal sont traçables.
Erreurs fréquentes
Ces raccourcis génèrent des retours coûteux :
Enregistrer directement le résultat OCR comme numéro de pièce.
Présenter une référence aftermarket comme garantie de montage.
Changer de provider après la liaison VIN.
Traiter 202 comme erreur ou liste terminée.
Mettre les images de documents en cache durable ou inter-mandants.
Générer le SEO avant d’identifier la pièce.
06 · Exploitation
Transformer les statuts HTTP en états de travail
Les intégrations doivent traduire les réponses HTTP en états métier. ERP, connecteur et place de marché restent ainsi cohérents pendant les opérations asynchrones.
Réponse
État métier
Action du système client
Automatisation
200
Résultat disponible
Enregistrer la réponse, appliquer les règles, actualiser le feu.
Oui, si les critères métier passent.
202
Job pièces VIN accepté
Enregistrer ID et URL d’état ; réessayer après Retry-After.
Oui, de façon asynchrone.
409
Interaction ou clarification nécessaire
Démarrer la session pour redirect_required ; respecter la liaison lors d’un conflit de provider.
Guidé, sans répétition aveugle.
404
Aucun résultat confirmé
Contrôler les candidats, corriger l’entrée ou lancer une recherche manuelle.
Ne pas publier.
429
Limite atteinte
Temporiser par mandant ; afficher quota et forfait.
Backoff, pas de tempête.
5xx
Indisponibilité temporaire
Répéter de façon idempotente et limitée ; passer en support après le seuil.
Backoff avec plafond.
Prêt pour l’implémentation technique ?
La documentation API contient tous les endpoints, schémas, champs de réponse et mentions d’utilisation obligatoires. Ce guide décrit l’orchestration recommandée dans le système client.
