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.

Lebenszyklus starten Integrationsabläufe ansehen

Ein Einstieg, ein Integrationsvertrag, sieben überprüfbare Gates.

DE EN FR

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.

Gate 0

Scope

Use Cases, Datenzweck, Zielsysteme, Rollen und Nicht-Ziele dokumentieren.

Gate 1

Mandant & Zugriff

Workspace, Master-/Client-Key, Rechte, Limits und Kosten eindeutig zuordnen.

Gate 2

Mapping

Objekte, IDs, Statuswerte und Mapping-Versionen festlegen.

Gate 3

Integration

VIN, OE, Scanner oder Warenkorb mit sicheren Fehlerpfaden anbinden — zuerst gegen einen Sandbox-Key, dann produktiv.

Gate 4

Prozessabnahme

Referenz-, Negativ- und 202-Fälle nachvollziehbar protokollieren.

Gate 5

Go-live

Produktiv-Key, Monitoring, Supportweg und Rückfallplan aktivieren.

Gate 6

Betrieb & Offboarding

Versionen, Rotation, Reviews, Migrationen und Abschaltung kontrollieren.

Gate-Regel: Kein Produktionszugang ohne eindeutigen Mandanten, getesteten Integrationsprozess, fachliche Abnahme und geklärte Betriebsverantwortung.

Market

Marktplätze

Onboarden Verkäufer und kontrollieren 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.

Recycling

Verwerter

Verwerter und Teilehändler binden Artikelanlage, Demontage und Bestand an.

Einen realen Musterartikel vom Foto bis zur internen Artikel-ID durchlaufen.
Spenderfahrzeug einmal erfassen und tapiId für weitere Teile verwenden.
Zustand, Lagerplatz und interne IDs bleiben im Händlersystem führend.

ERP

ERP-Anbieter provisionieren und orchestrieren mehrere Kundenmandanten.

Workspace, Key, Limits und Sponsoring pro Mandant testen. Aufrufe innerhalb desselben Clients müssen serialisiert werden; bei `429` ist `Retry-After` zu beachten.
Objekt- und Statusmapping unabhängig von UI-Feldern versionieren.
Nachweis: Zwei Testmandanten können nicht vermischt werden.

Dealer

Autohändler

Nehmen Gebrauchtwagen mit einem Aufruf herein.

Fahrzeugschein-Foto über POST /vehicles/intake in eine Fahrzeugakte überführen.
Rundgang-Fotos mit POST /vision/condition-report als strukturierten Zustandsbericht abnehmen.
Inseratstext über POST /vehicles/{tapiId}/listing aus den dokumentierten Fahrzeugdaten erzeugen.

DMS

Bettet die API als White-Label-Baustein für die eigenen Händler ein.

Je Händler mit POST /client/partner-workspaces einen kompletten Workspace anlegen: Unter-Client, API-Key, Endpunkt-Freischaltung, optional Kostenübernahme.
Wie Integratoren einen versionsfesten Connector betreiben: 202, Location, Retry-After, Abbruch und Wiederaufnahme nachweisen.
Kunden trennen, Mapping-Versionen protokollieren und Keys ohne Kundenausfall rotieren.

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.

Aktivitätsdiagramm

VertragspartnerVertrag abschließenLeistungen, Verantwortliche und Abrechnung festlegen.

tapinomahubMaster-Zugang bereitstellenMaster-Client und Master-Key werden übergeben.

VertragspartnerGetrennte Clients nötig?Nur bei mehreren Kunden, Mandanten, Apps oder eigenen Limits.

KundensystemOptional Clients anlegenPOST /client/users und bei Bedarf weitere Keys.

KundensystemProzesse 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 in der serverseitigen Umgebung.

Idempotenz und Schlüsselausgabe: Eine Schreiboperation unterstützt Idempotenz ausschließlich dann, wenn die API-Referenz den Request-Parameter Idempotency-Key ausweist. POST /client/users, POST /client/users/{clientId}/keys und POST /client/partner-workspaces akzeptieren den Header nicht; wird er gesendet, antworten sie mit HTTP 400 und error: idempotency_key_not_supported. Nach Timeout, Verbindungsabbruch oder anderem unklaren Ausgang nicht erneut posten, sondern den Client-, Workspace- und Schlüsselbestand über die dokumentierten GET-/Listen-Endpunkte abgleichen. Ein in einer verlorenen Antwort ausgegebener Klartext-Key ist nicht wieder abrufbar; eine Ersatz- oder Rotationsaktion darf erst nach diesem Abgleich bewusst gestartet werden.

AuthentifizierungEin Header

X-Api-Key für alle freigeschalteten Prozesse.

MandantenOptional getrennt

Eigene Keys, Limits, Pläne und Nutzung je Client.

AntwortenJSON und HTTP

Direkte Ergebnisse oder standardisierte 202-Jobs.

BetriebMessbar

Guthaben, Planverbrauch und Endpunktnutzung abrufbar.

02 · VIN-Prozesse

Drei Auswahlwerte, ein konsistenter API-Vertrag

Der numerische provider-Wert wird beim Fahrzeugabgleich gewählt. Beim anschließenden Teileabruf für dieselbe VIN wird er nicht erneut gesendet.

Auswahlwert 1

Öffentlicher Auswahlwert des Fahrzeugaufrufs mit dokumentiertem Redirect-Zustand.

1. Fahrzeug abfragen

GET /vin/{vin}/vehicle?provider=1.

2. Antwortzustand auswerten

Bei redirect_required eine Session über POST /vin/redirect-sessions mit VIN, HTTPS-Return-URL und optionalem state erstellen.

3. Redirect öffnen

Nur die erhaltene redirectUrl wird geöffnet; der API-Key bleibt serverseitig.

4. Rückgabe übernehmen

status, tapiId und optional den unveränderten state verarbeiten.

5. Teile abrufen

GET /vin/{vin}/parts ohne erneuten Auswahlwert; bei 202 die Job-Status-URL nach Retry-After abfragen.

Ergebnis: Den fachlichen Ergebnischarakter ausschließlich anhand des zurückgegebenen matchLevel auswerten.

Auswahlwert 2

Öffentlicher Auswahlwert des Fahrzeugaufrufs.

1. Fahrzeug abfragen

GET /vin/{vin}/vehicle?provider=2.

2. Antwort übernehmen

tapiId und die verfügbaren Antwortfelder im Kundensystem speichern.

3. Teile abrufen

GET /vin/{vin}/parts ohne erneuten Auswahlwert aufrufen.

4. Ergebnis auswerten

matchLevel und gegebenenfalls mehrere zurückgegebene Varianten fachlich behandeln.

Ergebnis: Maßgeblich sind ausschließlich die tatsächlich zurückgegebenen Felder und matchLevel.

Auswahlwert 3

Öffentlicher Auswahlwert des Fahrzeugaufrufs.

1. Fahrzeug abfragen

GET /vin/{vin}/vehicle?provider=3.

2. Antwort übernehmen

tapiId und die verfügbaren Antwortfelder im Kundensystem speichern.

3. Teile abrufen

GET /vin/{vin}/parts ohne erneuten Auswahlwert aufrufen.

4. Ergebnis auswerten

Den zurückgegebenen Ergebnischarakter und gegebenenfalls mehrere Varianten sichtbar behandeln.

Ergebnis: Maßgeblich sind ausschließlich die tatsächlich zurückgegebenen Felder und matchLevel.

Auswahlvertrag: provider wird nur beim Fahrzeugabgleich gesetzt und beim Teileabruf weggelassen. Ein widersprüchlicher Wert wird mit vin_provider_mismatch abgewiesen.

Teilevertrag: Jede Position in parts[] enthält die Pflichtfelder tapiGenArt und parts[].vdi. parts[].vdi enthält bestätigte vollständige VDI-4081-Codes und bleibt ohne gültige Zuordnung als [] vorhanden. Der fachliche Ergebnischarakter wird über matchLevel ausgewertet.

Job- und Abrechnungsgrenze: Einen laufenden Job über seine ID weiter abfragen, nicht neu bestellen; der Statusabruf gehört zum ursprünglichen Auftrag und löst keine zweite Bestellung aus. Abrechnung und Erstattungen richten sich nach den dokumentierten Antwortzuständen und den vertraglich vereinbarten Konditionen.

03 · OE-Prozesse

Eine Nummer wird zum belastbaren Teilekontext

Der Basisabgleich liefert HTTP 200 für einen bestätigten OE-Treffer. tapiGenArt und vdi ergänzen diesen Treffer; ohne Treffer antwortet die API mit 404. Weitere Anreicherungen werden nur nach einem bestätigten Treffer aufgerufen.

OE-Abgleich und optionale Anreicherung

Die Kernidentifikation bleibt von Preis-, Aftermarket-Referenz- und Textprozessen getrennt.

Aktivitätsdiagramm

KundensystemOE-Nummer übernehmenAus Artikelstamm, Scan oder manueller Eingabe.

KundensystemBasisabgleich aufrufenGET /parts/oe/{oeNumber}.

tapinomahubAntwortzustand bestimmenBestätigter OE-Treffer: HTTP 200. Kein Treffer: 404.

KundensystemAnreicherung nötig?Je Use Case Referenzen, Preisbewertung oder SEO wählen.

KundensystemOptionale Endpunkte aufrufen/parts/oe/{oeNumber}/aftermarket-references, /parts/oe/{oeNumber}/price 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.

OE-Ergebnis: HTTP 200 liefert einen bestätigten OE-Treffer im Pflichtfeld part. Die geschlossene Antwort enthält genau oeNumber, normalizedOeNumber, tapiGenArt, vdi, part, fitment, replacementChain, references und referenceNumbers. part.name kann null und fitment leer sein. references gruppiert bestätigte Vergleichsnummern in Objekten aus manufacturer und numbers; referenceNumbers.oe_oem_reference_numbers führt sie als deduplizierte Liste einschließlich der bestätigten OE-Nummer. Nur replacementChain dokumentiert gerichtete from/to-Kanten. tapiGenArt und vdi sind Best-Effort-Anreicherungen und bleiben als null beziehungsweise [] vorhanden, ohne den Basistreffer zu blockieren. 404 bedeutet, dass kein OE-Treffer vorliegt; 422 wird ohne stille Kandidatenauswahl zur Fachprüfung gegeben.

Artikeloptimierung für eBay und Marktplätze: GET /parts/oe/{oeNumber}/seo erzeugt aus der bestätigten OE-Nummer den veröffentlichungsfertigen Artikel. marketplaceId wählt den Marktplatz — dokumentiert sind die eBay-Marktplätze EBAY_AT bis EBAY_US mit EBAY_DE als Standard —, language die Inhaltssprache. Die Antwort liefert den Angebotstitel in content.ebayTitle innerhalb der dokumentierten 80-Zeichen-Grenze, die Marktplatzkategorie in categoryId, die Artikelmerkmale in itemSpecifics als {name, value[]}, Suchbegriffe in keywords, die Produktbenennung in product sowie den Shop-SEO-Text in content.title, content.h1, content.metaTitle, content.metaDescription, content.slug und content.bulletPoints. 404 seo_no_exact_match ist die dokumentierte Nichttreffer-Antwort. Der Inhalt ist Veröffentlichungstext und vor der Veröffentlichung zu prüfen; eine Passungsaussage entsteht daraus nicht.

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 normalisierten, länderspezifischen Feldern aus einem Fahrzeugschein-Bild/PDF erfassen.

Datei bereitstellen · berechtigte HTTPS-URL

POST /scanner/vin/extract oder international POST /scanner/document/registration/international

fileUrl verwenden · nationaler Vertrag unter POST /scanner/document/registration

VIN plausibilisieren · 17 Zeichen und Lesefehler

VIN-Fahrzeugabgleich starten · provider-Auswahlwert 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-all

Nummern als Kandidaten übernehmen

Über den OE-Prozess bestätigen

Kalkulation oder Fahrzeugdokument → strukturierte Felder

Kalkulationen mit zwölf festen Feldern einschließlich Ausstattung auslesen oder den reichhaltigen Fahrzeugvertrag gezielt wählen.

Kalkulation: POST /scanner/document/calculation

Reiches Fahrzeugmodell: POST /scanner/document/vehicle

Ausstattung prüfen · Code als String, Art und Quellseite bewahren

In den eigenen Workflow übergeben

Qualitätsgrenze und Pfadmigration: Persönliche Dokumentanalysen über Kalkulations-, Fahrzeugdokument- und Zulassungsrouten bieten ausschließlich quality=standard; enhanced und maximum sind dort keine gültigen Auswahlwerte. Pfadmigration ohne doppelten POST: Die bisherigen Pfade /scanner/document/extract, /scanner/vehicle-document/extract, /scanner/registration-document und /scanner/registration-document/v2 bleiben als veraltete Kompatibilitätsaliase ohne HTTP-Weiterleitung erhalten. Fahrzeug- und Zulassungspaare liefern identische Antworten und teilen Idempotenz pfadübergreifend. Nur die alte Dokumentroute behält bewusst elf Felder ohne equipment; ein Schlüsselwechsel zwischen ihr und der zwölfteiligen Kalkulationsantwort endet mit HTTP 409.

04b · Vision-Bildprozess

OE-basierte Teileansichten nachvollziehbar erzeugen

Der veröffentlichte Generierungsprozess liefert sechs Standardansichten als asynchronen Job. Eingabemodus, Evidenzbasis und Identitätsverifikation bleiben in der Antwort explizit.

OE-Nummer → sechs Standardansichten

sourceMode=references_required ist die Vorgabe: Nur referenzbelegte Ansichten werden ausgegeben; fehlen belastbare Bilder, endet der Job mit insufficient_reference_images und wird erstattet. references_preferred nutzt Referenzen, falls vorhanden, und leitet sonst aus der Teilenummer ab. knowledge_only verzichtet ausdrücklich auf Referenzen und darf nicht mit referenceImageUrls kombiniert werden. Sobald einer dieser beiden Modi aus der Teilenummer ableitet, gilt basis=knowledge, partIdentityVerified=false und verificationConfidence=limited; die Bilder tragen keine Beschriftung. Maßwerte ohne skalierte Evidenz bleiben leer.

OE, Winkel, optional Farbcode und bewussten sourceMode senden

POST /vision/part/generate

202 und Retry-After beachten

GET /vision/part/generation-jobs/{jobId}

basis, Ansichten, Unsicherheiten und Verifikation prüfen

Veröffentlichungsregel: Der OE-Generierungsjob wendet die Kennungsrichtlinie automatisch an und veröffentlicht nur Bilder mit bestätigtem Kennungsschutz; bei einer Ableitung aus der Teilenummer bleibt partIdentityVerified=false. MAC endet in XX:XX:XX, IMEI in sieben X, VIN in acht X. Freie Seriennummern bleiben nur dann teilweise sichtbar, wenn ein typenbezogenes Präfix sicher erkannt wurde; sonst wird die gesamte Kennung maskiert.

04c · Direkte Vision-Bildprozesse

Montieren, sichtbare Schäden übertragen und Kennungen sicher anonymisieren

Alle drei Prozesse sind synchrone POST-Aufrufe. Sie liefern nur nach vollständiger Prüfung HTTP 200; Teilresultate werden nie veröffentlicht.

Teil in Hintergrund montieren

POST /vision/part/composite erwartet partImageUrl und backgroundImageUrl. partMaskUrl, eine normalisierte targetBox, Hinweise bis 1.000 Zeichen und Ausgabeformat/-größe sind optional. Die Antwort enthält genau ein asset, partIdentityPreserved=true und limitations. Nur Übergang, Lichtangleichung und Kontaktschatten dürfen generativ entstehen. Die Abrechnung je Ergebnis richtet sich für standard, enhanced und maximum ausschließlich nach den vertraglich vereinbarten Konditionen.

Sichtbare Schäden auf Zielansichten übertragen

POST /vision/part/damage-transfer nimmt 1–5 sources und 1–6 targets mit eindeutiger Zielansicht entgegen; optionale Masken grenzen das konkrete Bauteil ab. findings nennt Quellindizes, Konfidenz und tatsächlich bearbeitete Ansichten, notTransferred alles nicht belastbar Übertragene. Verdeckte oder nicht fotografierte Schäden werden nie ergänzt. Der gesamte Auftrag wird als Bundle abgerechnet, nicht pro Zielbild; maßgeblich sind ausschließlich die vertraglich vereinbarten Konditionen.

Instanzkennungen vor Veröffentlichung anonymisieren

POST /vision/identifiers/redact verarbeitet 1–10 imageUrls als ein Paket. Die Abrechnung richtet sich ausschließlich nach den vertraglich vereinbarten Konditionen. Die feste Richtlinie tapinoma.public-asset-identifiers.v1 erhält bei MAC nur das OUI, bei IMEI den TAC und bei VIN die ersten neun Zeichen; Seriennummern und sonstige Instanz-IDs werden vollständig maskiert, maschinenlesbare Codes vollständig entwertet. Bestätigte OE-/Typ-/Revisionskennungen bleiben erhalten. Die Ergebnisbilder sind synthetic=false.

Verbindliche Veröffentlichungs- und Wiederholungsgrenze: Für alle drei synchronen Workflows den HTTP-Client-Request-/Read-Timeout auf mindestens 300 Sekunden setzen. Jeder neue Geschäftsvorgang erhält einen neuen Idempotency-Key; bei jeder Wiederholung dieses Vorgangs bleibt derselbe Idempotency-Key unverändert. Der erste Erfolg liefert X-Tapinoma-Idempotency-Stored: true oder false. Bei false führt ein späterer Aufruf mit demselben Idempotency-Key zu 409 idempotency_result_unavailable: Zustand abgleichen und niemals automatisch einen neuen Idempotency-Key erzeugen. Läuft derselbe Idempotency-Key noch, 409 idempotency_request_in_progress samt Retry-After abwarten und den Vorgang mit demselben Idempotency-Key wiederholen. part_segmentation_failed, damage_not_transferable, image_edit_unverified oder identifier_redaction_unverified führen zu 422, automatischer Erstattung und null Assets; 422 ist endgültig und darf weder mit demselben noch mit einem neuen Idempotency-Key wiederholt werden. 503 weist auf eine vorübergehende Nichtverfügbarkeit hin; eine Wiederholung darf ausschließlich mit demselben Idempotency-Key erfolgen. Erfolgreiche Assets enthalten tapinoma.vision-provenance.v1, einen sichtbaren Hinweis und identifierRedaction.verified=true.

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.

Aktivitätsdiagramm

KundensystemWarenkorb vorbereitenVIN, Modus, Land und 1–30 OE-Positionen.

KundensystemPrüfung startenPOST /vin/cart-check.

tapinomahubDirekt abschließbar?200 liefert Ergebnis; 202 liefert Job-ID und Status-URL.

KundensystemNur bei 202 wartenRetry-After beachten und GET /vin/cart-check/jobs/{jobId} abrufen; der Statusabruf gehört zum ursprünglichen Auftrag und ist keine zweite Bestellung.

tapinomahubPositionen zuordnenPositionen anhand der dokumentierten Antwort auswerten.

KundensystemWarenkorb anzeigenfits 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. Auswahlwerte, Normalisierung und Ergebnischarakter folgen konsistenten API-Verträgen.

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 redirect_required
Optional einen begrenzten Worker für 202-Jobs
Fachliche Anzeige und Freigabe im eigenen System

Das übernimmt tapinomahub

Der öffentliche Vertrag deckt die wiederkehrenden Integrationsaufgaben ab.

Einheitliche Authentifizierung und Client-Trennung
Fortführung des gewählten VIN-Ablaufs
Redirect-Sessions und sichere Rückgabe der tapiId
OE-Normalisierung, Ersetzungsketten und optionale Anreicherungen
Standardisierte Jobs, Status-URLs und Ergebniskennzeichnungen

Weitere Dienste entdecken: Der API-Vertrag dokumentiert außerdem Rückrufe, Wirtschaftlichkeitsanalysen, Fahrzeugannahme und Inserate sowie Zustands-, Freistellungs-, Kennzeichen- und Altfahrzeug-Workflows. Die vollständige Endpunktliste steht in der API-Dokumentation.

07 · Abnahme, Go-live & Betrieb

Mit Belegen produktionsreif

Die Integration ist erst fertig, wenn Mandantentrennung, repräsentative End-to-End-Abläufe, Wartezustände, Fehlerbehandlung und Betriebswege gemeinsam abgenommen sind.

Identität & Mandant

Falsche, gesperrte und fremde Keys werden abgewiesen; Nutzung bleibt dem richtigen Mandanten zugeordnet.

Repräsentativer Ablauf

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

Neue API- oder Mapping-Version zuerst mit einem Sandbox-Key prüfen, Referenzfälle wiederholen und dann kontrolliert umschalten. Der Sandbox-Key nutzt dieselbe Basis-URL und ausschließlich synthetische Testdaten; seine Nutzung richtet sich nach den vereinbarten Konditionen.

Offboarding

Keys sperren, Jobs beenden, Sponsoring widerrufen, Daten fristgerecht behandeln und Abschluss protokollieren.

Mit einem repräsentativen Ablauf beginnen.

Wähle VIN, OE, Scanner oder Warenkorb als ersten Use Case und führe ihn durch alle sieben Gates bis zum kontrollierten Betrieb.

API-Vertrag öffnen Teileprozess ansehen

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.

Start the lifecycle View integration workflows

One entry point, one integration contract, seven auditable gates.

DE EN FR

00 · Shared lifecycle

Seven gates from scope to operations

Integration and onboarding are one process. Every transition has concrete evidence and an accountable approval.

Gate 0

Scope

Document use cases, data purpose, target systems, roles, and non-goals.

Gate 1

Tenant & access

Assign workspace, master/client key, rights, limits, and cost unambiguously.

Gate 2

Mapping

Define objects, IDs, states, sources, and mapping versions.

Gate 3

Integration

Connect VIN, OE, scanning, or cart with safe failure paths — against a sandbox key first, then in production.

Gate 4

Process acceptance

Record reference, negative, and 202 cases traceably.

Gate 5

Go-live

Activate production key, monitoring, support path, and fallback.

Gate 6

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.

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.

Recycling

Dismantlers

Dismantlers and parts dealers connect article creation, dismantling, and inventory.

Run one real sample part from photo to internal article ID.
Capture one donor vehicle and reuse its tapiId for more parts.
Condition, location, and internal IDs remain led by the dealer system.

ERP

ERP vendors provision and orchestrate multiple customer tenants.

Test workspace, key, limits, and sponsorship per tenant. Calls within the same client must be serialised; on `429`, observe `Retry-After`.
Version object and state mappings independently of UI fields.
Evidence: two test tenants cannot be mixed.

Dealer

Car dealers

Take in used vehicles with a single call.

Turn a registration-document photo into a vehicle file via POST /vehicles/intake.
Accept walkaround photos as a structured condition report via POST /vision/condition-report.
Generate listing-ready copy from the documented vehicle data via POST /vehicles/{tapiId}/listing.

DMS

Embed the API as a white-label building block for their dealers.

Create one complete workspace per dealer via POST /client/partner-workspaces: sub-client, API key, endpoint enablement, optional cost coverage.
Operate a versioned connector like integrators: prove 202, Location, Retry-After, cancellation, and resume.
Separate customers, record mapping versions, and 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.

Activity diagram

PartnerConclude agreementDefine services, owners and billing.

tapinomahubProvide master accessMaster client and master key are supplied.

PartnerSeparate clients?Only for multiple customers, tenants, apps or limits.

Customer systemOptionally create clientsPOST /client/users and additional keys as needed.

Customer systemConnect 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.

Idempotency support and raw-key issuance: A write operation supports idempotency only when the API reference declares the Idempotency-Key request parameter for that operation; this declared parameter is the sole support signal. POST /client/users, POST /client/users/{clientId}/keys, and POST /client/partner-workspaces issue plaintext keys and do not declare or accept Idempotency-Key; sending the header returns HTTP 400 with error: idempotency_key_not_supported. After a timeout, connection loss, or any other ambiguous outcome, do not post again; reconcile client, workspace, and key state through the documented GET/list operations. A plaintext key issued in a lost response cannot be retrieved; start a replacement or rotation deliberately only after reconciliation.

AuthenticationOne header

X-Api-Key for every enabled workflow.

TenantsOptional separation

Keys, limits, plans and usage per client.

ResponsesJSON and HTTP

Direct results or standard 202 jobs.

OperationsMeasurable

Balance, plan consumption and endpoint usage.

02 · VIN workflows

Three selection values, one consistent API contract

Choose the numeric provider value on the vehicle request. Do not send it again on the parts request for the same VIN.

Selection value 1

Public selection value for the vehicle request.

1. Request the vehicle

GET /vin/{vin}/vehicle?provider=1.

2. Follow the documented response

If the response is redirect_required, create a session with POST /vin/redirect-sessions.

3. Complete the redirect flow

Open redirectUrl; keep the API key server-side and accept status, tapiId, and optional state on return.

4. Request parts

GET /vin/{vin}/parts without provider; on 202, poll the returned status URL after Retry-After.

Result: evaluate the returned fields and matchLevel.

Selection value 2

Public selection value for the vehicle request.

1. Request the vehicle

GET /vin/{vin}/vehicle?provider=2.

2. Store the result

Use tapiId and the response fields that are present.

3. Request parts

GET /vin/{vin}/parts without provider.

4. Evaluate the response

Use matchLevel and any returned variants for the business decision.

Result: evaluate only the documented response fields.

Selection value 3

Public selection value for the vehicle request.

1. Request the vehicle

GET /vin/{vin}/vehicle?provider=3.

2. Store the result

Use tapiId and the response fields that are present.

3. Request parts

GET /vin/{vin}/parts without provider.

4. Evaluate the response

Use matchLevel and any returned variants for the business decision.

Result: evaluate only the documented response fields.

Selection contract: set provider only on the vehicle request and omit it from /vin/{vin}/parts. A conflicting explicit value is rejected as vin_provider_mismatch.

Parts contract: every parts[] item contains the required tapiGenArt and parts[].vdi fields. parts[].vdi contains confirmed full VDI 4081 codes and remains present as [] when no valid mapping is available. Use the returned fields and matchLevel to interpret the result.

Job and billing boundary: Keep polling a running job by ID instead of ordering it again; status retrieval belongs to the original order and does not create a second order. Billing and refunds follow the documented response states and the agreed contractual terms.

03 · OE workflows

A number becomes reliable parts context

The base lookup returns HTTP 200 for a confirmed OE match. tapiGenArt and VDI enrich that match; without a match, the Hub returns 404. Further enrichment is requested only after a confirmed match.

OE lookup and optional enrichment

Core identification remains separate from price, aftermarket-reference and content workflows.

Activity diagram

Customer systemReceive OE numberFrom inventory, scan or manual input.

Customer systemCall base lookupGET /parts/oe/{oeNumber}.

tapinomahubClassify the outcomeConfirmed OE match: HTTP 200. No match: 404.

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 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.

OE result: HTTP 200 returns a confirmed OE match in the required part field. The closed response contains exactly oeNumber, normalizedOeNumber, tapiGenArt, vdi, part, fitment, replacementChain, references, and referenceNumbers. part.name may be null and fitment may be empty. references groups confirmed comparison numbers in objects containing manufacturer and numbers; referenceNumbers.oe_oem_reference_numbers provides the deduplicated list including the confirmed OE number. Only replacementChain documents directed from/to edges. tapiGenArt and vdi are best-effort enrichments and remain present as null and [] without blocking the base match. Route 404 and 422 to specialist review without silently selecting a candidate.

eBay and marketplace article optimisation: GET /parts/oe/{oeNumber}/seo turns the confirmed OE number into a publication-ready article. marketplaceId selects the marketplace — the documented values are the eBay marketplaces EBAY_AT through EBAY_US, with EBAY_DE as the default — and language selects the content language. The response supplies the listing title in content.ebayTitle within the documented 80-character limit, the marketplace category in categoryId, the item specifics in itemSpecifics as {name, value[]}, search terms in keywords, product naming in product, and the shop SEO text in content.title, content.h1, content.metaTitle, content.metaDescription, content.slug and content.bulletPoints. 404 seo_no_exact_match is the documented no-match answer. The content is publication copy to be reviewed before it goes live; it never becomes a fitment statement.

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 normalised, country-specific fields from a registration-document image/PDF.

Provide file · authorised HTTPS URL

POST /scanner/vin/extract or internationally POST /scanner/document/registration/international

Use fileUrl · national contract at POST /scanner/document/registration

Validate VIN · 17 characters and reading errors

Start vehicle lookup · provider selection value 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-all

Accept numbers as candidates

Confirm through OE lookup

Calculation or vehicle document → structured fields

Extract a calculation's twelve fixed fields including equipment, or deliberately choose the rich vehicle contract.

Calculation: POST /scanner/document/calculation

Rich vehicle model: POST /scanner/document/vehicle

Validate equipment · preserve code as string, kind and source page

Continue customer workflow

Quality boundary and path migration: Personal-document analysis through the calculation, vehicle-document and registration routes supports only quality=standard; enhanced and maximum are not valid choices there. Path migration without a second POST: /scanner/document/extract, /scanner/vehicle-document/extract, /scanner/registration-document and /scanner/registration-document/v2 remain deprecated compatibility aliases without HTTP redirects. Vehicle and registration pairs return identical responses and share cross-path idempotency. Only the old document path deliberately retains eleven fields without equipment; moving its key to the twelve-field calculation contract returns HTTP 409.

04b · Vision image workflows

Generate traceable OE-based part views

The published generation workflow returns six standard views as an asynchronous job. Input mode, evidence basis, and identity verification remain explicit in the response.

OE number → six standard views

sourceMode=references_required is the default: only reference-evidenced views are returned; without reliable images, the job ends with insufficient_reference_images and is refunded. references_preferred uses references when available and otherwise derives from the part number. knowledge_only explicitly avoids references and cannot be combined with referenceImageUrls. Whenever either of these modes derives from the part number, basis=knowledge, partIdentityVerified=false, and verificationConfidence=limited; images carry no labels. Measurements without scaled evidence remain empty.

Send OE, angles, optional colour code, and a deliberate sourceMode

POST /vision/part/generate

Observe 202 and Retry-After

GET /vision/part/generation-jobs/{jobId}

Check basis, generated views, uncertainty, and verification

Publication rule: The OE generation job applies identifier protection automatically and publishes only images with verified identifier protection; when deriving from the part number, partIdentityVerified=false remains explicit. MAC ends in XX:XX:XX, IMEI in seven X, and VIN in eight X. A free-form serial remains partly visible only if a type-level prefix is identified safely; otherwise the whole identifier is masked.

04c · Direct Vision image workflows

Composite, transfer visible damage, and redact identifiers safely

All three workflows are synchronous POST calls. They return HTTP 200 only after the complete output has passed verification; partial results are never published.

Composite a part into a background

POST /vision/part/composite requires partImageUrl and backgroundImageUrl. An exact partMaskUrl, normalised targetBox, instructions of up to 1,000 characters, and output format/size are optional. The response has exactly one asset, partIdentityPreserved=true, and limitations. Only transitions, light matching, and contact shadow may be generated. Billing per result for standard, enhanced, and maximum is governed exclusively by the contractually agreed terms.

Transfer visible damage to target views

POST /vision/part/damage-transfer accepts 1–5 sources and 1–6 targets with unique target views; optional masks isolate the actual part. findings identifies source indexes, confidence, and views actually edited, while notTransferred lists unsupported transfers. Hidden or unphotographed damage is never inferred. The whole request is billed as one bundle, not per target image; only the contractually agreed terms apply.

Redact instance identifiers before publication

POST /vision/identifiers/redact processes 1–10 imageUrls as one bundle. Billing is governed exclusively by the contractually agreed terms. The immutable tapinoma.public-asset-identifiers.v1 policy preserves only the OUI of a MAC, the TAC of an IMEI, and the first nine VIN characters; serials and other instance IDs are fully masked and machine-readable codes are fully invalidated. Confirmed OE/type/revision identifiers remain visible. Result images have synthetic=false.

Binding publication and retry boundary: Configure the HTTP client request/read timeout to at least 300 seconds for all three synchronous workflows. Give each new business operation a new Idempotency-Key, and keep that same idempotency key unchanged for every retry of the operation. The first success returns X-Tapinoma-Idempotency-Stored: true or false. With false, a later call with the same idempotency key returns 409 idempotency_result_unavailable: reconcile state and never generate a new idempotency key automatically. While the operation is still running, wait for Retry-After from 409 idempotency_request_in_progress, then retry with the same idempotency key. part_segmentation_failed, damage_not_transferable, image_edit_unverified, or identifier_redaction_unverified returns 422, is automatically refunded, and returns zero assets; 422 is terminal and must never be retried with either the same or a fresh idempotency key. 503 indicates temporary unavailability and may be retried only with the same idempotency key. Successful assets contain tapinoma.vision-provenance.v1, a visible disclosure, and identifierRedaction.verified=true.

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.

Activity diagram

Customer systemPrepare cartVIN, mode, country and 1–30 OE positions.

Customer systemStart checkPOST /vin/cart-check.

tapinomahubImmediate?200 returns result; 202 returns job and status URL.

Customer systemWait only on 202Observe Retry-After and call GET /vin/cart-check/jobs/{jobId}; status retrieval belongs to the original order and is not a second order.

tapinomahubMatch positionsEvaluate positions from the documented response.

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. Selection values, normalization, and result semantics follow consistent API 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 redirect_required
Optional bounded worker for 202 jobs
Business display and approval in the customer system

tapinomahub handles

The public contract covers the complete request lifecycle.

Consistent authentication and client separation
Continuation of the selected VIN workflow
Redirect sessions and return of tapiId
OE normalization, replacements and optional enrichment
Jobs, status URLs and result labels

Discover further services: The API contract also documents recalls, economic evaluations, vehicle intake and listings, plus condition, background-removal, licence-plate, and end-of-life vehicle workflows. See the complete API documentation.

07 · Acceptance, go-live & operations

Production-ready with evidence

Integration is complete only when tenant separation, representative end-to-end 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.

Representative 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

Verify a new API or mapping version with a sandbox key first, rerun the reference cases, then switch under control. The sandbox key uses the same base URL and only synthetic test data; its use is governed by the agreed terms.

Offboarding

Revoke keys, end jobs, withdraw sponsorship, handle data by retention, and record completion.

Start with one representative workflow.

Choose VIN, OE, scanning, or cart first and take it through all seven gates into controlled operations.

Open API contract View parts process

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.

Démarrer le cycle Voir les intégrations

Un point d’entrée, un contrat d’intégration, sept jalons vérifiables.

DE EN FR

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.

Jalon 0

Périmètre

Documenter usages, finalité, systèmes cibles, rôles et exclusions.

Jalon 1

Mandant & accès

Affecter workspace, clé master/client, droits, limites et coûts.

Jalon 2

Mapping

Définir objets, IDs, statuts, sources et versions de mapping.

Jalon 3

Intégration

Raccorder VIN, OE, scan ou panier avec des erreurs sûres — d’abord avec une clé sandbox, puis en production.

Jalon 4

Recette

Consigner les cas de référence, négatifs et 202.

Jalon 5

Production

Activer clé, supervision, support et plan de repli.

Jalon 6

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.

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.

Recycling

Recycleurs

Recycleurs et négociants en pièces 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.

ERP

Les éditeurs d’ERP provisionnent et orchestrent plusieurs mandants clients.

Tester workspace, clé, limites et sponsoring par mandant. Les appels d’un même client doivent être sérialisés ; en cas de `429`, respecter `Retry-After`.
Versionner objets et statuts indépendamment des champs UI.
Preuve : deux mandants de test ne peuvent être mélangés.

Dealer

Négociants automobiles

Réceptionnent les véhicules d’occasion en un seul appel.

Transformer la photo de la carte grise en dossier véhicule avec POST /vehicles/intake.
Recevoir les photos du tour du véhicule comme rapport d’état structuré avec POST /vision/condition-report.
Générer un texte d’annonce prêt à publier avec POST /vehicles/{tapiId}/listing.

DMS

Intègrent l’API comme brique en marque blanche pour leurs négociants.

Créer un workspace complet par négociant avec POST /client/partner-workspaces : sous-client, clé API, activation des endpoints, prise en charge des coûts en option.
Exploiter un connecteur versionné comme les intégrateurs : prouver 202, Location, Retry-After, interruption et reprise.
Séparer les clients, tracer les versions de mapping et renouveler les clés sans coupure.

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.

Diagramme d’activité

PartenaireConclure le contratDéfinir services, responsables et facturation.

tapinomahubFournir l’accès masterLe client master et sa clé sont remis.

PartenaireClients séparés ?Seulement pour plusieurs clients, apps ou limites.

Système clientCréer les clients si besoinPOST /client/users et clés supplémentaires.

Système 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.

Prise en charge de l’idempotence et délivrance de clés en clair : Une opération d’écriture ne prend en charge l’idempotence que si la référence API déclare pour cette opération le paramètre de requête Idempotency-Key ; ce paramètre déclaré est le seul signal de prise en charge. POST /client/users, POST /client/users/{clientId}/keys et POST /client/partner-workspaces délivrent des clés en clair et ne déclarent ni n’acceptent Idempotency-Key ; l’envoi de cet en-tête renvoie le statut HTTP 400 avec error: idempotency_key_not_supported. Après un délai d’attente, une perte de connexion ou toute autre issue incertaine, ne pas relancer le POST ; rapprocher l’état des clients, workspaces et clés au moyen des opérations GET et de liste documentées. Une clé en clair délivrée dans une réponse perdue ne peut pas être récupérée ; ne lancer délibérément un remplacement ou une rotation qu’après ce rapprochement.

AuthentificationUn en-tête

X-Api-Key pour tous les processus autorisés.

MandantsSéparation facultative

Clés, limites, forfaits et usage par client.

RéponsesJSON et HTTP

Résultats directs ou jobs 202.

ExploitationMesurable

Solde, forfaits et usage des endpoints.

02 · Processus VIN

Trois valeurs de sélection, un contrat API cohérent

Choisir la valeur numérique provider lors de l’appel véhicule. Ne pas la renvoyer lors de l’appel pièces pour le même VIN.

Valeur de sélection 1

Valeur publique de sélection pour l’appel véhicule.

1. Demander le véhicule

GET /vin/{vin}/vehicle?provider=1.

2. Suivre la réponse documentée

Si la réponse est redirect_required, créer une session avec POST /vin/redirect-sessions.

3. Terminer le parcours de redirection

Ouvrir redirectUrl, conserver la clé API côté serveur et accepter status, tapiId et state facultatif au retour.

4. Demander les pièces

GET /vin/{vin}/parts sans provider ; en 202, interroger l’URL d’état renvoyée après Retry-After.

Résultat : évaluer les champs renvoyés et matchLevel.

Valeur de sélection 2

Valeur publique de sélection pour l’appel véhicule.

1. Demander le véhicule

GET /vin/{vin}/vehicle?provider=2.

2. Conserver le résultat

Utiliser tapiId et les champs présents dans la réponse.

3. Demander les pièces

GET /vin/{vin}/parts sans provider.

4. Évaluer la réponse

Utiliser matchLevel et les éventuelles variantes renvoyées pour la décision métier.

Résultat : évaluer uniquement les champs de réponse documentés.

Valeur de sélection 3

Valeur publique de sélection pour l’appel véhicule.

1. Demander le véhicule

GET /vin/{vin}/vehicle?provider=3.

2. Conserver le résultat

Utiliser tapiId et les champs présents dans la réponse.

3. Demander les pièces

GET /vin/{vin}/parts sans provider.

4. Évaluer la réponse

Utiliser matchLevel et les éventuelles variantes renvoyées pour la décision métier.

Résultat : évaluer uniquement les champs de réponse documentés.

Contrat de sélection : définir provider uniquement sur l’appel véhicule et l’omettre dans /vin/{vin}/parts. Une valeur explicite contradictoire est rejetée avec vin_provider_mismatch.

Contrat pièces : chaque élément de parts[] contient les champs obligatoires tapiGenArt et parts[].vdi. parts[].vdi contient les codes VDI 4081 complets et confirmés et reste présent sous la forme [] lorsqu’aucune correspondance valide n’est disponible. Utiliser les champs renvoyés et matchLevel pour interpréter le résultat.

Frontière entre job et facturation : Continuer à interroger un job en cours par son ID au lieu de le commander à nouveau ; la consultation du statut appartient à la commande initiale et ne crée pas de seconde commande. La facturation et les remboursements suivent les états de réponse documentés et les conditions contractuelles convenues.

03 · Processus OE

Une référence devient un contexte pièce fiable

La recherche de base renvoie HTTP 200 pour un résultat OE confirmé. tapiGenArt et VDI enrichissent ce résultat ; sans correspondance, le Hub renvoie 404. Les autres enrichissements ne sont appelés qu’après un résultat confirmé.

Recherche OE et enrichissement facultatif

L’identification reste séparée des processus de prix, de références aftermarket et de contenu.

Diagramme d’activité

Système clientRecevoir la référence OEStock, scan ou saisie manuelle.

Système clientAppeler la recherche de baseGET /parts/oe/{oeNumber}.

tapinomahubClasser le résultatRésultat OE confirmé : HTTP 200. Aucun résultat : 404.

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 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.

Résultat OE : HTTP 200 renvoie un résultat OE confirmé dans le champ obligatoire part. La réponse fermée contient exactement oeNumber, normalizedOeNumber, tapiGenArt, vdi, part, fitment, replacementChain, references et referenceNumbers. part.name peut valoir null et fitment peut être vide. references regroupe les numéros de comparaison confirmés dans des objets contenant manufacturer et numbers ; referenceNumbers.oe_oem_reference_numbers fournit la liste dédoublonnée incluant le numéro OE confirmé. Seul replacementChain documente les arêtes orientées from/to. tapiGenArt et vdi sont des enrichissements best effort qui restent présents sous la forme null et [] sans bloquer le résultat de base. Transmettre 404 et 422 au contrôle spécialiste sans sélectionner silencieusement un candidat.

Optimisation des articles pour eBay et les marketplaces : GET /parts/oe/{oeNumber}/seo transforme le numéro OE confirmé en article prêt à publier. marketplaceId choisit la marketplace — les valeurs documentées sont les marketplaces eBay EBAY_AT à EBAY_US, avec EBAY_DE par défaut — et language la langue du contenu. La réponse fournit le titre d’annonce dans content.ebayTitle dans la limite documentée de 80 caractères, la catégorie de la marketplace dans categoryId, les caractéristiques de l’objet dans itemSpecifics sous forme {name, value[]}, les mots-clés dans keywords, la dénomination produit dans product ainsi que le texte SEO de la boutique dans content.title, content.h1, content.metaTitle, content.metaDescription, content.slug et content.bulletPoints. 404 seo_no_exact_match est la réponse documentée d’absence de correspondance. Le contenu est un texte de publication à vérifier avant diffusion ; il ne constitue jamais une affirmation de compatibilité.

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 normalisés propres au pays depuis une image/PDF de la carte grise.

Fournir le fichier · URL HTTPS autorisée

POST /scanner/vin/extract ou, à l’international, POST /scanner/document/registration/international

Utiliser fileUrl · contrat national sous POST /scanner/document/registration

Valider le VIN · 17 caractères

Démarrer la recherche VIN · valeur de sélection provider 1, 2 ou 3

É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-all

Reprendre les références candidates

Confirmer par la recherche OE

Calcul ou document véhicule → champs structurés

Extraire les douze champs fixes d’un calcul, équipement compris, ou choisir explicitement le contrat véhicule détaillé.

Calcul : POST /scanner/document/calculation

Modèle véhicule détaillé : POST /scanner/document/vehicle

Valider l’équipement · conserver le code comme chaîne, le type et la page source

Poursuivre le workflow client

Limite de qualité et migration de chemin : L’analyse de documents personnels par les routes de calcul, de document véhicule et d’immatriculation accepte uniquement quality=standard ; enhanced et maximum n’y sont pas des choix valides. Migration de chemin sans second POST : /scanner/document/extract, /scanner/vehicle-document/extract, /scanner/registration-document et /scanner/registration-document/v2 restent des alias POST de compatibilité obsolètes sans redirection HTTP. Les paires véhicule et immatriculation renvoient des réponses identiques et partagent l’idempotence entre chemins. Seul l’ancien chemin document conserve volontairement onze champs sans equipment ; déplacer sa clé vers le contrat de calcul à douze champs renvoie HTTP 409.

04b · Processus d’image Vision

Générer des vues de pièces OE traçables

Le processus de génération publié renvoie six vues standard sous forme de job asynchrone. Le mode d’entrée, la base de preuve et la vérification de l’identité restent explicites dans la réponse.

Référence OE → six vues standard

sourceMode=references_required est la valeur par défaut : seules les vues étayées par des références sont renvoyées ; sans images fiables, le job se termine par insufficient_reference_images et est remboursé. references_preferred utilise les références disponibles, puis déduit à partir du numéro de pièce à défaut. knowledge_only exclut volontairement les références et ne peut pas être combiné avec referenceImageUrls. Lorsque l’un de ces deux modes déduit le résultat du numéro de pièce, basis=knowledge, partIdentityVerified=false et verificationConfidence=limited ; les images ne portent aucun libellé. Les mesures sans preuve mise à l’échelle restent vides.

Envoyer OE, angles, code couleur facultatif et un sourceMode choisi explicitement

POST /vision/part/generate

Respecter 202 et Retry-After

GET /vision/part/generation-jobs/{jobId}

Contrôler basis, les vues générées, les incertitudes et la vérification

Règle de publication : Le traitement OE applique automatiquement la protection des identifiants et ne publie que les images dont cette protection est vérifiée ; lors d’une déduction à partir du numéro de pièce, partIdentityVerified=false reste explicite. MAC se termine par XX:XX:XX, IMEI par sept X et VIN par huit X. Un numéro de série libre ne reste partiellement visible que si un préfixe de type est identifié avec certitude ; sinon tout l’identifiant est masqué.

04c · Processus d’image Vision directs

Composer, transférer les dommages visibles et anonymiser les identifiants en sécurité

Les trois processus sont des appels POST synchrones. Ils ne renvoient HTTP 200 qu’après vérification de l’ensemble du résultat ; aucun résultat partiel n’est publié.

Intégrer une pièce dans un arrière-plan

POST /vision/part/composite exige partImageUrl et backgroundImageUrl. Un partMaskUrl précis, une targetBox normalisée, des instructions jusqu’à 1 000 caractères et le format/la taille de sortie sont facultatifs. La réponse contient exactement un asset, partIdentityPreserved=true et limitations. Seuls les raccords, l’harmonisation de la lumière et l’ombre de contact peuvent être générés. La facturation par résultat de standard, enhanced et maximum est régie exclusivement par les conditions convenues au contrat.

Transférer les dommages visibles vers les vues cibles

POST /vision/part/damage-transfer accepte 1–5 sources et 1–6 targets avec des vues cibles uniques ; des masques facultatifs isolent la pièce. findings indique les indices sources, la confiance et les vues réellement modifiées ; notTransferred recense les transferts non étayés. Aucun dommage caché ou non photographié n’est déduit. Toute la requête est facturée comme un lot, et non par image cible ; seules les conditions convenues au contrat s’appliquent.

Anonymiser les identifiants d’instance avant publication

POST /vision/identifiers/redact traite 1–10 imageUrls comme un lot. La facturation est régie exclusivement par les conditions convenues au contrat. La politique immuable tapinoma.public-asset-identifiers.v1 ne conserve que l’OUI d’une MAC, le TAC d’un IMEI et les neuf premiers caractères d’un VIN ; les numéros de série et autres identifiants d’instance sont entièrement masqués et les codes lisibles par machine entièrement invalidés. Les identifiants OE/type/révision confirmés restent visibles. Les images de résultat ont synthetic=false.

Limite impérative de publication et de reprise : Configurer le délai d’attente de requête/lecture du client HTTP à au moins 300 secondes pour les trois processus synchrones. Attribuer un nouveau Idempotency-Key à chaque nouvelle opération métier et conserver cette même clé d’idempotence pour toute reprise de l’opération. Le premier succès renvoie X-Tapinoma-Idempotency-Stored: true ou false. Avec false, un appel ultérieur avec la même clé d’idempotence renvoie 409 idempotency_result_unavailable : rapprocher l’état et ne jamais générer automatiquement une nouvelle clé d’idempotence. Tant que l’opération est en cours, attendre le Retry-After de 409 idempotency_request_in_progress, puis réessayer la requête avec la même clé d’idempotence. part_segmentation_failed, damage_not_transferable, image_edit_unverified ou identifier_redaction_unverified renvoie 422, est remboursé automatiquement et ne renvoie aucun asset ; 422 est définitif et ne doit jamais être retenté, ni avec la même clé d’idempotence ni avec une nouvelle. 503 indique une indisponibilité temporaire et ne peut être retenté qu’avec la même clé d’idempotence. Les assets réussis contiennent tapinoma.vision-provenance.v1, une mention visible et identifierRedaction.verified=true.

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.

Diagramme d’activité

Système clientPréparer le panierVIN, mode, pays et 1 à 30 positions OE.

Système clientLancer le contrôlePOST /vin/cart-check.

tapinomahubRésultat immédiat ?200 renvoie le résultat ; 202 renvoie un job.

Système clientAttendre seulement en 202Respecter Retry-After et appeler GET /vin/cart-check/jobs/{jobId} ; la consultation du statut appartient à la commande initiale et ne crée pas de seconde commande.

tapinomahubRapprocher les positionsÉvaluer les positions à partir de la réponse documentée.

Système clientAfficher 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 valeurs de sélection, la normalisation et la sémantique des résultats suivent des contrats API 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 redirect_required
Worker borné facultatif pour les jobs 202
Affichage et validation métier dans son système

tapinomahub prend en charge

Le contrat public couvre le cycle de requête complet.

Authentification uniforme et séparation des clients
Poursuite du processus VIN sélectionné
Sessions de redirection et retour de tapiId
Normalisation OE, remplacements et enrichissements
Jobs, URLs de statut et qualification des résultats

Découvrir d’autres services : Le contrat API documente également les rappels, les évaluations économiques, la réception et les annonces de véhicules, ainsi que les processus d’état, de détourage, de lecture des plaques et de classification des véhicules hors d’usage. Voir la documentation API complète.

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 bout en bout représentatifs, 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 représentatif

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

Vérifier d’abord une nouvelle version d’API ou de mapping avec une clé sandbox, rejouer les cas de référence, puis basculer sous contrôle. La clé sandbox utilise la même URL de base et uniquement des données de test synthétiques ; son utilisation suit les conditions convenues.

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 représentatif.

Choisissez VIN, OE, scan ou panier et faites-le passer par les sept jalons jusqu’à une exploitation contrôlée.

Ouvrir le contrat API Voir le processus pièces