Scope
Use Cases, Datenzweck, Zielsysteme, Rollen und Nicht-Ziele dokumentieren.
Integration · Onboarding · Go-live
Vom Vertrag zum verlässlichen Betrieb.
Ein gemeinsamer Lebenszyklus für Scope, Mandanten, Zugänge, VIN, OE, Scanner und Warenkorb – mit visuellen Integrationsabläufen, belastbarer Abnahme und kontrolliertem Go-live.
Ein Einstieg, ein Integrationsvertrag, sieben überprüfbare Gates.
00 · Gemeinsamer Lebenszyklus
Sieben Gates vom Scope bis zum Betrieb
Integration und Onboarding sind ein gemeinsamer Prozess. Jeder Übergang besitzt einen konkreten Nachweis und eine verantwortliche Freigabe.
Mandant & Zugriff
Workspace, Master-/Client-Key, Rechte, Limits und Kosten eindeutig zuordnen.
Mapping
Objekte, IDs, Statuswerte, Quellen und Mapping-Versionen festlegen.
Integration
VIN, OE, Scanner oder Warenkorb mit sicheren Fehlerpfaden anbinden.
Prozessabnahme
Referenz-, Negativ- und 202-Fälle nachvollziehbar protokollieren.
Go-live
Produktiv-Key, Monitoring, Supportweg und Rückfallplan aktivieren.
Betrieb & Offboarding
Versionen, Rotation, Reviews, Migrationen und Abschaltung kontrollieren.
Gate-Regel: Kein Produktionszugang ohne eindeutigen Mandanten, getesteten Integrationsprozess, fachliche Abnahme und geklärte Betriebsverantwortung.
ERP
ERP-Anbieter
Provisioniert und orchestriert mehrere Kundenmandanten.
- Workspace, Key, Limits und Sponsoring pro Mandant testen.
- Objekt- und Statusmapping unabhängig von UI-Feldern versionieren.
- Nachweis: Zwei Testmandanten können nicht vermischt werden.
DMS
Teilehändler & Verwerter
Bindet Artikelanlage, Demontage und Lager an.
- Einen realen Musterartikel vom Foto bis zur internen Artikel-ID durchlaufen.
- Spenderfahrzeug einmal erfassen und
tapiIdfür weitere Teile verwenden. - Zustand, Lagerplatz und interne IDs bleiben im Händlersystem führend.
Market
Marktplätze
Onboardet Verkäufer und kontrolliert Veröffentlichungen.
- Verkäufer, Kontingent, Angebot und Herkunft getrennt halten.
- Freigabegrenzen für Treffer und Typ-Kandidaten testen.
- Ungeprüfte oder widersprüchliche Daten bleiben unveröffentlicht.
Connect
Integratoren
Betreibt einen versionsfesten Connector.
202,Location,Retry-After, Abbruch und Wiederaufnahme nachweisen.- Kunden trennen und Mapping-Versionen nachvollziehbar protokollieren.
- Keys ohne Kundenausfall rotieren können.
01 · Start & Zugänge
Vom Vertrag zum ersten produktiven Aufruf
Ein Master-Key genügt für den direkten Start. Client-Keys werden nur benötigt, wenn Kunden, Mandanten, Anwendungen oder Nutzungsgrenzen getrennt werden sollen.
Onboarding als Aktivitätsdiagramm
Der Partner entscheidet über das Mandantenmodell; der Hub stellt die passenden Zugänge und API-Verträge bereit.
VertragspartnerVertrag abschließenLeistungen, Verantwortliche und Abrechnung festlegen.
tapinoma hubMaster-Zugang bereitstellenMaster-Client und Master-Key werden übergeben.
VertragspartnerGetrennte Clients nötig?Nur bei mehreren Kunden, Mandanten, Apps oder eigenen Limits.
KundenbackendOptional Clients anlegen
POST /client/users und bei Bedarf weitere Keys.KundenbackendProzesse anbindenVIN, OE, Scanner und Warenkorb unabhängig kombinieren.
GemeinsamReferenzfälle prüfenErfolg, Fehler und asynchrone Antworten abnehmen.
ProduktionGo-liveNutzung und Status sind über die Client-Endpunkte sichtbar.
iEinfacher Start: Ohne Untermandanten entfällt die Client-Verwaltung vollständig. Der Master-Key bleibt ausschließlich im Server-Backend.
X-Api-Key für alle freigeschalteten Prozesse.
Eigene Keys, Limits, Pläne und Nutzung je Client.
Direkte Ergebnisse oder standardisierte 202-Jobs.
Guthaben, Planverbrauch und Endpunktnutzung abrufbar.
02 · VIN-Prozesse
Drei Datenwege, ein konsistenter API-Vertrag
Der Datenweg wird beim Fahrzeugabgleich gewählt. Für dieselbe VIN übernimmt der Teileabruf diese Bindung automatisch; das Kundensystem muss keine zweite Auswahl synchronisieren.
Provider 1 · Geführter Browser-Abgleich
Für Fahrzeugkontext mit sichtbarer Bestätigung und anschließendem fahrzeugbezogenem Teileprozess.
1. Session serverseitig erstellen
POST /vin/redirect-sessions mit VIN, HTTPS-Return-URL und optionalem state.
2. Browser weiterleiten
Nur die erhaltene redirectUrl wird geöffnet; der API-Key bleibt im Backend.
3. Fahrzeug im Kundenfrontend abgleichen
Fahrzeug- und Ausstattungsinformationen werden angezeigt und bestätigt.
4. Callback empfangen
status, stabile tapiId und optional unveränderten state übernehmen.
5. Teile abrufen
GET /vin/{vin}/parts; bei 202 Status-URL nach Retry-After abfragen.
Ergebnis: bestmögliche fahrzeugbezogene Liste, maschinenlesbar als
vehicle_specific_best_available.Provider 2 · Direkter Typabgleich
Server-zu-Server ohne Browserunterbrechung; geeignet für schnelle technische Typzuordnung.
1. Fahrzeug direkt abfragen
GET /vin/{vin}/vehicle?provider=2.
2. Fahrzeugreferenz übernehmen
Antwort mit tapiId und verfügbaren technischen Fahrzeugmerkmalen.
3. Teile ohne Providerparameter abrufen
GET /vin/{vin}/parts verwendet automatisch Provider 2.
4. Varianten fachlich behandeln
Mehrere mögliche Bauteilvarianten können gleichzeitig zurückkommen.
Ergebnis: mögliche Teile auf Fahrzeugtypebene, gekennzeichnet als
vehicle_type_candidates.Provider 3 · Direkter Fahrzeugabgleich
Server-zu-Server für eine breite fahrzeugbezogene Teilenummernmenge.
1. Fahrzeug direkt abfragen
GET /vin/{vin}/vehicle?provider=3.
2. Fahrzeugreferenz übernehmen
tapiId und verfügbare Fahrzeugbezeichnung im Kundensystem zuordnen.
3. Teile ohne Providerparameter abrufen
Die bestehende Bindung wird automatisch wiederverwendet.
4. Ergebnischarakter anzeigen
Die konkrete Fahrzeugzuordnung der Teile ist nicht verifiziert.
Ergebnis: fahrzeugbezogene, unverifizierte Liste mit
vehicle_specific_unverified.Technischer Vereinfacher: Nach dem erfolgreichen Fahrzeugabgleich wird
provider bei /vin/{vin}/parts weggelassen. Der Hub hält die Bindung konsistent und weist einen widersprüchlichen expliziten Wert ab.03 · OE-Prozesse
Eine Nummer wird zum belastbaren Teilekontext
Der Basisabgleich bestätigt die OE-Nummer und liefert die Ersetzungskette. Weitere Anreicherungen werden nur aufgerufen, wenn der jeweilige Geschäftsprozess sie benötigt.
OE-Abgleich und optionale Anreicherung
Die Kernidentifikation bleibt von Preis-, Referenz- und Textprozessen getrennt.
KundensystemOE-Nummer übernehmenAus Artikelstamm, Scan oder manueller Eingabe.
KundensystemBasisabgleich aufrufen
GET /parts/oe/{oeNumber}.tapinoma hubTeil und Ersetzungen abgleichenNormalisierte Nummer, Bezeichnung und dokumentierte Ersetzungskette.
KundensystemAnreicherung nötig?Je Use Case Referenzen, Preisbewertung oder SEO wählen.
KundensystemOptionale Endpunkte aufrufen
/parts/oe/{oeNumber}/aftermarket-references, /parts/oe/{oeNumber}/price-evaluation oder /parts/oe/{oeNumber}/seo.KundensystemErgebnis verwendenFachliche Prüfung und Freigabe bleiben im führenden System.
iEffektiv: Ein bestätigter OE-Treffer kann unabhängig für Einkauf, Verkauf, Suche, Preisunterstützung und Content weiterverwendet werden.
04 · Scanprozesse
Aus Bildern werden direkt nutzbare Folgeprozesse
Der Scan ist kein isoliertes OCR-Ergebnis: Jeder Dokumenttyp führt gezielt in den passenden VIN-, OE- oder Dokumentprozess.
Fahrzeugfoto oder Fahrzeugschein → VIN
VIN direkt aus einem Foto oder zusammen mit technischen Feldern aus einem Fahrzeugschein-Bild/PDF erfassen.
Datei bereitstellen · berechtigte HTTPS-URL
POST /scanner/vin/extract oder POST /scanner/registration-documentVIN plausibilisieren · 17 Zeichen und Lesefehler
VIN-Fahrzeugabgleich starten · Provider 1, 2 oder 3
Teileetikett → OE
Je gewünschter Tiefe Text, Teilenummern oder alle erkennbaren Merkmale extrahieren.
Etikett fotografieren · scharf und vollständig
/scanner/label/basic, /scanner/label/extract-partnumbers oder /scanner/label/extract-allNummern als Kandidaten übernehmen
Über den OE-Prozess bestätigen
Dokument → strukturierte Felder
Allgemeine Dokumente nach einer definierten Feldbeschreibung automatisiert strukturieren.
Dokument bereitstellen
POST /scanner/document/extractStrukturierte Antwort prüfen
In den eigenen Workflow übergeben
Ein Integrationsmuster: Bild-URL plus Qualitätsstufe senden, JSON-Ergebnis übernehmen, danach den fachlichen Folgeprozess aufrufen. Dadurch bleiben Upload, Analyse und Geschäftsvorgang sauber getrennt.
05 · Warenkorbprozesse
Bis zu 30 OE-Positionen in einem Vorgang prüfen
Der Warenkorb behält Reihenfolge und Duplikate bei. Das Kundensystem erhält je Position eine klare Übereinstimmung und zusätzlich die Information, ob die zugrunde liegende Teileliste vollständig war.
VIN-Warenkorbprüfung
mode=type prüft auf Fahrzeugtypebene; mode=vehicle verwendet den konkreten Fahrzeugkontext.
KundensystemWarenkorb vorbereitenVIN, Modus, Land und 1–30 OE-Positionen.
KundensystemPrüfung starten
POST /vin/cart-check.tapinoma hubDirekt abschließbar?
200 liefert Ergebnis; 202 liefert Job-ID und Status-URL.KundenbackendNur bei 202 warten
Retry-After beachten und GET /vin/cart-check/jobs/{jobId} abrufen.tapinoma hubPositionen zuordnenFormatvarianten und dokumentierte Ersetzungen werden berücksichtigt.
KundensystemWarenkorb anzeigen
fits je Position und complete für die Aussagekraft auswerten.!Entscheidungsregel:
fits=false bei complete=false ist kein abschließender Ausschluss. Das Kundensystem kann die Position sichtbar zur Prüfung markieren, statt sie fälschlich abzulehnen.06 · Integrationsumfang
Das Kundensystem bleibt schlank
Der Partner baut nur die Übergabepunkte, die sein Use Case tatsächlich benötigt. Providerabläufe, Normalisierung und Ergebnischarakter werden über konsistente API-Verträge abstrahiert.
Das implementiert der Vertragspartner
Ein kleiner, klar begrenzter technischer Umfang.
- Serverseitigen HTTP-Client mit
X-Api-Key - Mapping der benötigten JSON-Antworten
- Optional eine HTTPS-Callback-Route für Provider 1
- Optional einen begrenzten Worker für
202-Jobs - Fachliche Anzeige und Freigabe im eigenen System
Das übernimmt tapinoma hub
Die wiederkehrende technische Orchestrierung hinter einem Vertrag.
- Einheitliche Authentifizierung und Client-Trennung
- Providerbindung zwischen VIN-Fahrzeug und VIN-Teilen
- Redirect-Sessions und sichere Rückgabe der
tapiId - OE-Normalisierung, Ersetzungsketten und optionale Anreicherungen
- Standardisierte Jobs, Status-URLs und Ergebniskennzeichnungen
07 · Abnahme, Go-live & Betrieb
Mit Belegen produktionsreif
Die Integration ist erst fertig, wenn Mandantentrennung, Referenzprozesse, Wartezustände, Fehlerbehandlung und Betriebswege gemeinsam abgenommen sind.
Identität & Mandant
Falsche, gesperrte und fremde Keys werden abgewiesen; Nutzung bleibt dem richtigen Mandanten zugeordnet.
Referenzprozess
Ein gewählter VIN-, OE-, Scan- oder Warenkorbvorgang läuft vom Eingang bis zum fachlichen Ergebnis.
Asynchron & Fehler
202, Retry-After, 429, 5xx, Timeout und Wiederaufnahme erzeugen korrekte Zustände.
Mapping & Veröffentlichung
Mapping-Version, Ergebnischarakter und Freigaberegel verhindern ungeprüfte automatische Ausgaben.
Nutzung & Kosten
Plan, Kontingent, Sponsoring und Nutzung sind mit dem vorgesehenen Workspace geprüft.
Erste Produktionsläufe
Mit einem bekannten Mandanten starten, Antwort, Mapping, Speicherung und Ausgabe gemeinsam prüfen und Volumen erst danach stufenweise erhöhen.
Supportfähige Meldung
Zeitpunkt, Endpunkt, HTTP-Status, Korrelation-ID, Auswirkung und erwartetes Ergebnis übergeben – niemals API-Key oder unnötige Dokumentdaten.
Regelmäßiger Review
Mandanten, Keys, Rechte, Limits, Nutzung, Fehlerquoten und manuelle Prüfungen kontrollieren.
Änderung & Migration
API- oder Mapping-Version in der Sandbox prüfen, Referenzfälle wiederholen und kontrolliert umschalten.
Offboarding
Keys sperren, Jobs beenden, Sponsoring widerrufen, Daten fristgerecht behandeln und Abschluss protokollieren.
Mit einem Referenzprozess beginnen.
Wähle VIN, OE, Scanner oder Warenkorb als ersten Use Case und führe ihn durch alle sieben Gates bis zum kontrollierten Betrieb.
Integration · Onboarding · Go-live
From agreement to reliable operations.
One lifecycle for scope, tenants, access, VIN, OE, scanning and cart checks—with visual integration workflows, evidence-based acceptance, and a controlled go-live.
One entry point, one integration contract, seven auditable gates.
00 · Shared lifecycle
Seven gates from scope to operations
Integration and onboarding are one process. Every transition has concrete evidence and an accountable approval.
Scope
Document use cases, data purpose, target systems, roles, and non-goals.
Tenant & access
Assign workspace, master/client key, rights, limits, and cost unambiguously.
Mapping
Define objects, IDs, states, sources, and mapping versions.
Integration
Connect VIN, OE, scanning, or cart with safe failure paths.
Process acceptance
Record reference, negative, and 202 cases traceably.
Go-live
Activate production key, monitoring, support path, and fallback.
Operations & offboarding
Control versions, rotation, reviews, migrations, and shutdown.
Gate rule: no production access without an unambiguous tenant, tested integration workflow, business acceptance, and assigned operational responsibility.
ERP
ERP vendors
Provision and orchestrate multiple customer tenants.
- Test workspace, key, limits, and sponsorship per tenant.
- Version object and state mappings independently of UI fields.
- Evidence: two test tenants cannot be mixed.
DMS
Parts dealers & dismantlers
Connect article creation, dismantling, and inventory.
- Run one real sample part from photo to internal article ID.
- Capture one donor vehicle and reuse its
tapiIdfor more parts. - Condition, location, and internal IDs remain led by the dealer system.
Market
Marketplaces
Onboard sellers and control publication.
- Keep seller, quota, offer, and provenance separate.
- Test release thresholds for matches and type candidates.
- Unchecked or contradictory data remains unpublished.
Connect
Integrators
Operate a versioned connector.
- Prove
202,Location,Retry-After, cancellation, and resume. - Separate customers and record mapping versions traceably.
- Rotate keys without customer downtime.
01 · Start & access
From agreement to the first production call
A master key is enough to start directly. Client keys are only needed when customers, tenants, applications or usage limits must be separated.
Onboarding activity diagram
The partner chooses the tenant model; the Hub supplies the matching access and API contracts.
PartnerConclude agreementDefine services, owners and billing.
tapinoma hubProvide master accessMaster client and master key are supplied.
PartnerSeparate clients?Only for multiple customers, tenants, apps or limits.
Customer backendOptionally create clients
POST /client/users and additional keys as needed.Customer backendConnect workflowsCombine VIN, OE, scanning and cart independently.
TogetherVerify reference casesAccept success, errors and asynchronous responses.
ProductionGo liveUsage and status remain visible through client endpoints.
iSimple start: without sub-tenants, client management disappears completely. The master key remains server-side only.
X-Api-Key for every enabled workflow.
Keys, limits, plans and usage per client.
Direct results or standard 202 jobs.
Balance, plan consumption and endpoint usage.
02 · VIN workflows
Three routes, one consistent API contract
The route is selected during vehicle lookup. Parts lookup automatically reuses it for the same VIN, so the customer system does not synchronize a second choice.
Provider 1 · Guided browser lookup
Visible confirmation followed by a vehicle-related parts process.
1. Create a server-side session
POST /vin/redirect-sessions with VIN, HTTPS return URL and optional state.
2. Redirect the browser
Open only redirectUrl; the API key stays in the backend.
3. Confirm the vehicle
Vehicle and equipment information is displayed in the customer frontend.
4. Receive the callback
Accept status, stable tapiId and unchanged optional state.
5. Request parts
GET /vin/{vin}/parts; on 202, poll after Retry-After.
Result: best available vehicle-related list as
vehicle_specific_best_available.Provider 2 · Direct type lookup
Server-to-server without a browser interruption.
1. Request the vehicle
GET /vin/{vin}/vehicle?provider=2.
2. Accept the vehicle reference
Response includes tapiId and available technical attributes.
3. Request parts without provider
GET /vin/{vin}/parts reuses provider 2.
4. Handle variants
Several possible component variants may be returned together.
Result: vehicle-type candidates as
vehicle_type_candidates.Provider 3 · Direct vehicle lookup
Server-to-server for a broad vehicle-related part-number set.
1. Request the vehicle
GET /vin/{vin}/vehicle?provider=3.
2. Accept the reference
Assign tapiId and the available vehicle label.
3. Request parts without provider
The existing binding is reused automatically.
4. Display result character
The concrete vehicle assignment of parts is not verified.
Result: unverified vehicle-related list as
vehicle_specific_unverified.Technical simplifier: after vehicle lookup, omit
provider from /vin/{vin}/parts. The Hub preserves the binding and rejects contradictory explicit values.03 · OE workflows
A number becomes reliable parts context
The base lookup confirms the OE number and replacement chain. Further enrichment is requested only when the business process needs it.
OE lookup and optional enrichment
Core identification remains separate from price, reference and content workflows.
Customer systemReceive OE numberFrom inventory, scan or manual input.
Customer systemCall base lookup
GET /parts/oe/{oeNumber}.tapinoma hubMatch part and replacementsNormalized number, label and documented chain.
Customer systemNeed enrichment?Select references, price evaluation or SEO per use case.
Customer systemCall optional endpoints
/parts/oe/{oeNumber}/aftermarket-references, /parts/oe/{oeNumber}/price-evaluation or /parts/oe/{oeNumber}/seo.Customer systemUse the resultBusiness validation stays in the leading system.
iEfficient: one confirmed OE match can support purchasing, sales, search, pricing and content independently.
04 · Scanning workflows
Images lead directly into usable workflows
A scan is not an isolated OCR result: each document type continues into the right VIN, OE or document process.
Vehicle photo or registration document → VIN
Read the VIN directly from a photo or capture it with technical fields from a registration-document image/PDF.
Provide file · authorised HTTPS URL
POST /scanner/vin/extract or POST /scanner/registration-documentValidate VIN · 17 characters and reading errors
Start vehicle lookup · provider 1, 2 or 3
Parts label → OE
Extract text, part numbers or all visible attributes.
Photograph label
/scanner/label/basic, /scanner/label/extract-partnumbers or /scanner/label/extract-allAccept numbers as candidates
Confirm through OE lookup
Document → structured fields
Structure general documents using a defined field description.
Provide document
POST /scanner/document/extractCheck structured response
Continue customer workflow
One integration pattern: send file URL and quality level, accept JSON, then call the relevant business workflow.
05 · Cart workflows
Check up to 30 OE positions in one operation
Input order and duplicates are preserved. Each line receives a match plus an indication whether the usable parts list was complete.
VIN cart check
mode=type checks vehicle type; mode=vehicle uses the concrete vehicle context.
Customer systemPrepare cartVIN, mode, country and 1–30 OE positions.
Customer systemStart check
POST /vin/cart-check.tapinoma hubImmediate?
200 returns result; 202 returns job and status URL.Customer backendWait only on 202Observe
Retry-After and call the job endpoint.tapinoma hubMatch positionsFormatting variants and documented replacements are considered.
Customer systemDisplay cartEvaluate line-level
fits and overall complete.!Decision rule:
fits=false with complete=false is not a definitive exclusion.06 · Integration scope
The customer system stays lean
Partners build only the hand-offs required by their use case. Provider workflows, normalization and result character are abstracted behind consistent contracts.
The partner implements
A small and bounded technical surface.
- Server-side HTTP client with
X-Api-Key - Mapping of required JSON responses
- Optional HTTPS callback route for provider 1
- Optional bounded worker for
202jobs - Business display and approval in the customer system
tapinoma hub handles
Recurring technical orchestration behind one contract.
- Consistent authentication and client separation
- Provider binding between VIN vehicle and VIN parts
- Redirect sessions and safe return of
tapiId - OE normalization, replacements and optional enrichment
- Standard jobs, status URLs and result labels
07 · Acceptance, go-live & operations
Production-ready with evidence
Integration is complete only when tenant separation, reference workflows, waiting states, failure handling, and operating paths have been accepted together.
Identity & tenant
Wrong, suspended, and foreign keys are rejected; usage remains assigned to the correct tenant.
Reference workflow
One selected VIN, OE, scan, or cart flow runs from input to business outcome.
Async & failures
202, Retry-After, 429, 5xx, timeout, and resume create correct states.
Mapping & publication
Mapping version, result character, and release rules prevent unchecked automatic output.
Usage & cost
Plan, quota, sponsorship, and usage are verified with the intended workspace.
First production runs
Start with one known tenant, review response, mapping, persistence, and output together, then increase volume gradually.
Supportable report
Provide time, endpoint, HTTP status, correlation ID, impact, and expected outcome—never the API key or unnecessary document data.
Regular review
Review tenants, keys, rights, limits, usage, failure rates, and manual checks.
Change & migration
Test API or mapping versions in sandbox, rerun reference cases, then switch under control.
Offboarding
Revoke keys, end jobs, withdraw sponsorship, handle data by retention, and record completion.
Start with one reference workflow.
Choose VIN, OE, scanning, or cart first and take it through all seven gates into controlled operations.
Intégration · Onboarding · Mise en production
Du contrat à une exploitation fiable.
Un cycle commun pour le périmètre, les mandants, les accès, le VIN, l’OE, le scan et le panier, avec processus visuels, recette probante et mise en production contrôlée.
Un point d’entrée, un contrat d’intégration, sept jalons vérifiables.
00 · Cycle commun
Sept jalons du périmètre à l’exploitation
Intégration et onboarding forment un seul processus. Chaque transition possède une preuve concrète et une validation responsable.
Périmètre
Documenter usages, finalité, systèmes cibles, rôles et exclusions.
Mandant & accès
Affecter workspace, clé master/client, droits, limites et coûts.
Mapping
Définir objets, IDs, statuts, sources et versions de mapping.
Intégration
Raccorder VIN, OE, scan ou panier avec des erreurs sûres.
Recette
Consigner les cas de référence, négatifs et 202.
Production
Activer clé, supervision, support et plan de repli.
Exploitation & sortie
Maîtriser versions, rotation, revues, migrations et arrêt.
Règle de jalon : aucune production sans mandant univoque, intégration testée, recette métier et responsabilité d’exploitation attribuée.
ERP
Éditeurs d’ERP
Provisionnent et orchestrent plusieurs mandants clients.
- Tester workspace, clé, limites et sponsoring par mandant.
- Versionner objets et statuts indépendamment des champs UI.
- Preuve : deux mandants de test ne peuvent être mélangés.
DMS
Négociants & recycleurs
Relient création d’article, démontage et stock.
- Traiter une pièce réelle de la photo jusqu’à l’ID article.
- Saisir un véhicule donneur et réutiliser son
tapiId. - État, emplacement et IDs restent pilotés par leur système.
Market
Places de marché
Onboardent les vendeurs et contrôlent la publication.
- Séparer vendeur, quota, offre et provenance.
- Tester les seuils des résultats et candidats de type.
- Les données non contrôlées restent non publiées.
Connect
Intégrateurs
Exploitent un connecteur versionné.
- Prouver
202,Location,Retry-After, interruption et reprise. - Séparer les clients et tracer les versions de mapping.
- Renouveler les clés sans coupure client.
01 · Démarrage & accès
Du contrat au premier appel de production
Une clé master suffit pour démarrer. Les clés client ne sont nécessaires que pour séparer clients, mandants, applications ou limites d’usage.
Onboarding sous forme de diagramme d’activité
Le partenaire choisit son modèle de mandants ; le Hub fournit les accès et contrats API correspondants.
PartenaireConclure le contratDéfinir services, responsables et facturation.
tapinoma hubFournir l’accès masterLe client master et sa clé sont remis.
PartenaireClients séparés ?Seulement pour plusieurs clients, apps ou limites.
Backend clientCréer les clients si besoin
POST /client/users et clés supplémentaires.Backend clientRaccorder les processusCombiner librement VIN, OE, scan et panier.
EnsembleTester les cas de référenceValider succès, erreurs et réponses asynchrones.
ProductionMise en productionUsage et statut restent consultables.
iDémarrage simple : sans sous-mandants, la gestion des clients disparaît. La clé master reste exclusivement côté serveur.
X-Api-Key pour tous les processus autorisés.
Clés, limites, forfaits et usage par client.
Résultats directs ou jobs 202.
Solde, forfaits et usage des endpoints.
02 · Processus VIN
Trois voies, un contrat API cohérent
La voie est choisie lors de la recherche véhicule. La recherche de pièces la reprend automatiquement pour le même VIN.
Provider 1 · Recherche guidée dans le navigateur
Confirmation visible suivie du processus pièces lié au véhicule.
1. Créer la session côté serveur
POST /vin/redirect-sessions avec VIN, URL HTTPS et state facultatif.
2. Rediriger le navigateur
Ouvrir redirectUrl ; la clé API reste dans le backend.
3. Confirmer le véhicule
Les informations véhicule et équipement sont affichées dans le frontend client.
4. Recevoir le callback
Récupérer status, tapiId stable et state.
5. Demander les pièces
GET /vin/{vin}/parts ; en 202, attendre Retry-After.
Résultat : meilleure liste liée au véhicule,
vehicle_specific_best_available.Provider 2 · Recherche directe du type
Serveur à serveur, sans interruption navigateur.
1. Demander le véhicule
GET /vin/{vin}/vehicle?provider=2.
2. Reprendre la référence
La réponse contient tapiId et les attributs disponibles.
3. Demander les pièces sans provider
GET /vin/{vin}/parts reprend le provider 2.
4. Traiter les variantes
Plusieurs variantes possibles peuvent être renvoyées ensemble.
Résultat : candidats au niveau du type,
vehicle_type_candidates.Provider 3 · Recherche directe du véhicule
Serveur à serveur pour une liste étendue de références.
1. Demander le véhicule
GET /vin/{vin}/vehicle?provider=3.
2. Reprendre la référence
Associer tapiId et la désignation disponible.
3. Demander les pièces sans provider
La liaison existante est reprise automatiquement.
4. Afficher la nature du résultat
L’affectation concrète des pièces au véhicule n’est pas vérifiée.
Résultat : liste véhicule non vérifiée,
vehicle_specific_unverified.Simplification technique : après la recherche véhicule, omettre
provider dans /vin/{vin}/parts. Le Hub conserve la liaison.03 · Processus OE
Une référence devient un contexte pièce fiable
La recherche de base confirme la référence OE et sa chaîne de remplacement. Les enrichissements ne sont appelés qu’en fonction du besoin métier.
Recherche OE et enrichissement facultatif
L’identification reste séparée des processus prix, références et contenu.
Système clientRecevoir la référence OEStock, scan ou saisie manuelle.
Système clientAppeler la recherche de base
GET /parts/oe/{oeNumber}.tapinoma hubRapprocher pièce et remplacementsRéférence normalisée, nom et chaîne documentée.
Système clientEnrichissement requis ?Choisir références, évaluation du prix ou SEO.
Système clientAppeler les endpoints facultatifs
/parts/oe/{oeNumber}/aftermarket-references, /parts/oe/{oeNumber}/price-evaluation ou /parts/oe/{oeNumber}/seo.Système clientUtiliser le résultatLa validation métier reste dans le système principal.
iEfficace : un résultat OE confirmé sert indépendamment les achats, ventes, recherches, prix et contenus.
04 · Processus de scan
Les images alimentent directement les processus utiles
Un scan n’est pas un résultat OCR isolé : chaque document continue vers le bon processus VIN, OE ou documentaire.
Photo du véhicule ou carte grise → VIN
Lire le VIN directement sur une photo ou avec les champs techniques d’une image/PDF de la carte grise.
Fournir le fichier · URL HTTPS autorisée
POST /scanner/vin/extract ou POST /scanner/registration-documentValider le VIN · 17 caractères
Démarrer la recherche VIN
Étiquette pièce → OE
Extraire texte, références ou toutes les caractéristiques.
Photographier l’étiquette
/scanner/label/basic, /scanner/label/extract-partnumbers ou /scanner/label/extract-allReprendre les références candidates
Confirmer par la recherche OE
Document → champs structurés
Structurer des documents généraux selon une description de champs.
Fournir le document
POST /scanner/document/extractContrôler la réponse
Poursuivre le workflow client
Un modèle d’intégration : envoyer l’URL du fichier et le niveau de qualité, reprendre le JSON, puis appeler le processus métier adapté.
05 · Processus panier
Contrôler jusqu’à 30 positions OE en une opération
L’ordre et les doublons sont conservés. Chaque ligne reçoit un résultat et l’indication de complétude de la liste utilisée.
Contrôle du panier par VIN
mode=type contrôle le type ; mode=vehicle utilise le véhicule concret.
Système clientPréparer le panierVIN, mode, pays et 1 à 30 positions OE.
Système clientLancer le contrôle
POST /vin/cart-check.tapinoma hubRésultat immédiat ?
200 renvoie le résultat ; 202 renvoie un job.Backend clientAttendre seulement en 202Respecter
Retry-After et appeler le statut.tapinoma hubRapprocher les positionsVariantes de format et remplacements documentés sont pris en compte.
Système clientAfficher le panierÉvaluer
fits et complete.!Règle :
fits=false avec complete=false n’est pas une exclusion définitive.06 · Périmètre d’intégration
Le système client reste léger
Le partenaire n’implémente que les points de passage utiles à son cas. Les processus provider, normalisations et types de résultat sont abstraits par des contrats cohérents.
Le partenaire implémente
Une surface technique réduite et délimitée.
- Client HTTP serveur avec
X-Api-Key - Mapping des réponses JSON nécessaires
- Route callback HTTPS facultative pour le provider 1
- Worker borné facultatif pour les jobs
202 - Affichage et validation métier dans son système
tapinoma hub prend en charge
L’orchestration technique récurrente derrière un contrat.
- Authentification uniforme et séparation des clients
- Liaison provider entre véhicule VIN et pièces VIN
- Sessions redirect et retour sûr de
tapiId - Normalisation OE, remplacements et enrichissements
- Jobs, URLs de statut et qualification des résultats
07 · Recette, production & exploitation
Prêt pour la production, preuves à l’appui
L’intégration n’est terminée que lorsque séparation des mandants, processus de référence, attentes, erreurs et exploitation sont validés ensemble.
Identité & mandant
Les clés erronées, bloquées ou étrangères sont refusées ; l’usage reste au bon mandant.
Processus de référence
Un flux VIN, OE, scan ou panier va de l’entrée au résultat métier.
Asynchrone & erreurs
202, Retry-After, 429, 5xx, timeout et reprise créent les bons statuts.
Mapping & publication
Version de mapping, nature du résultat et règle de validation bloquent les sorties non contrôlées.
Usage & coûts
Forfait, quota, sponsoring et usage sont vérifiés avec le workspace prévu.
Premiers flux de production
Démarrer avec un mandant connu, contrôler réponse, mapping, stockage et sortie, puis augmenter progressivement le volume.
Signalement exploitable
Fournir date, endpoint, statut HTTP, ID de corrélation, impact et résultat attendu, jamais la clé API ni des données inutiles.
Revue régulière
Contrôler mandants, clés, droits, limites, usage, erreurs et vérifications manuelles.
Changement & migration
Tester versions API ou mapping en sandbox, rejouer les références puis basculer sous contrôle.
Offboarding
Révoquer les clés, finir les jobs, retirer le sponsoring, traiter les données et consigner la clôture.
Commencer avec un processus de référence.
Choisissez VIN, OE, scan ou panier et faites-le passer par les sept jalons jusqu’à une exploitation contrôlée.