Domain model and terminology

This page defines the public tapinomahub terms and API relationships that integrations need. Exact request and response shapes remain normative in the OpenAPI reference.

The machine-readable definitions are available as domain-dictionary.json.

Canonical account terms

Client

An account addressed by clientId. Every API key belongs to exactly one Client. Billing, credit, plans and rate limits attach to that Client, not to its parent.

Master client

A Client with no parent and with administrative rights. It can create and manage Sub-users and issue sponsorships. A directly contracted customer is a Master client.

Sub-user

A Client below one Master client. It has its own API keys, credit, plans and limits but cannot create another hierarchy level. Deactivating the Master client also deactivates its Sub-users.

Use Sub-user in English and Unter-Nutzer in German.

Workspace

workspace is the response field that groups the Client information returned by the corresponding workspace operation. It does not introduce a separate tenant resource.

Tenant

Not a tapinomahub object. It is the end customer inside the integrating system. There is no tenant field in the public API. Map each Tenant that needs isolation to its own Client, normally a Sub-user with its own API key. Keep the integrating system's tenant key in that system; never invent a tenantId request field.

Public contract concepts

VIN

vin is the vehicle identification number accepted by VIN operations and returned by several scanner and vehicle operations. The VIN is the starting input for vehicle lookup, vehicle-related parts, OE-cart checking, recall matching and economic evaluation. It is not a compatibility result and must not be used as a substitute for tapiId.

For exact producers and consumers, see VIN data flow.

`tapiId`

tapiId is the stable public vehicle reference returned by a successful vehicle lookup. The GET /vehicles/{tapiId} contract clarifies that it references the technical vehicle type, not the individual physical vehicle; several VINs can share one value. Store the VIN and tapiId in separate fields.

Use tapiId for subsequent technical vehicle data and listing-text calls where the operation explicitly requires it. Do not derive, parse or create it locally.

OE number

oeNumber is the submitted original-equipment part-number string used by OE operations. Different operations make different normalization promises. Preserve the original business input and also store normalizedOeNumber only when the selected operation returns a confirmed value.

An OE number may identify or reference a part, but by itself it does not prove that the part fits a particular vehicle.

Normalized OE number

normalizedOeNumber is a contract result, not a string transformation that clients should guess. In OeNormalizationResponse, it is non-null only when status is matched; in PartOeResponse, it is the confirmed normalized number to which the response applies.

Do not replace the API's normalization result with locally guessed formatting rules. Use GET /parts/oe/normalize when the workflow needs an explicit normalization decision, and treat the returned value as authoritative for that response.

OE part name

PartOeResponse.part.name is an optional nullable part designation. When available, its value is a string or null. Clients should preserve the returned value and must not reconstruct a missing name from another field.

tapinomahub GenArt

tapiGenArt is a stable public tapinomahub part-category identity in the format TGA- followed by at least six digits. Every successful base OE response contains the field, but its value is null when no valid classification is available. A successful VIN-parts position contains one non-null value.

Treat a returned code as opaque. Store it as a string, do not convert it to an integer, and do not infer equality with any external taxonomy. A null OE value does not invalidate the confirmed base part.

VDI 4081 code

The required vdi field of a successful base OE response and of every successful VIN-parts position contains only confirmed full codes matching VDI4081_<number> with an optional installation-location suffix. In the asynchronous VIN flow, the same field appears under result.parts[].vdi. [] means no valid mapping was available and is a complete terminal value, not a pending state. It does not mean the part is invalid and does not prove installation on a vehicle.

VDI 4081 is a classification system named by the public contract.

Asynchronous job and `jobId`

Some order operations may return HTTP 202 instead of a result. jobId identifies the accepted processing job; the required full statusUrl is the safe polling address, while Location must be compared rather than reconstructed from its current root-relative example. A job-status request returning HTTP 200 can still report the domain state failed. Branch on status; for the part-image family, locally require and validate the corresponding result or error because the released schema does not make those fields state-dependent.

Different workflows use different job resources. Never send a VIN-parts jobId to the cart-check or economic-evaluation status path.

OE replacement chain

replacementChain contains confirmed directional from/to edges in a base OE response. It is not a list of interchangeable inventory items and not a vehicle-fit guarantee. Preserve edge direction and validate the business use before substituting a part number.

OE fitment

PartOeResponse.fitment[] contains the available type-level vehicle assignments for a confirmed OE base part. The list can be empty; an empty list means that no assignments were returned and is not proof that the part fits no vehicle.

Every fitment entry contains an opaque vehicleTypeKey and the readable criteria[] recorded for that key. Criteria are unstructured display text: the contract defines no AND/OR relationship, polarity, vocabulary or executable rule, so clients must preserve them with their key and must not derive compatibility logic from the text. An empty criteria list means that no restriction is recorded for that assignment; it does not turn the assignment into an unconditional installation guarantee.

The key is neither a VIN nor a tapiId. Keep it as a string and use it only in the same external key space. API 1.71.0 does not expose a public operation that resolves vehicleTypeKey to make, model or tapiId.

OE reference numbers

PartOeResponse.references[] groups confirmed reference and comparison numbers by manufacturer; each group contains a non-empty numbers[] list. PartOeResponse.referenceNumbers is a closed object with exactly oe_oem_reference_numbers[], the consolidated confirmed numbers including the confirmed OE number.

These reference views do not state that every number is bidirectionally interchangeable and do not prove vehicle fitment. Read replacement direction only from replacementChain, and do not derive references from that chain or a chain from the references.

Vehicle data describes the matched vehicle or technical vehicle type. Vehicle-related parts describes part assignments or candidates returned in a VIN workflow. These are different results and different operations. A vehicle lookup can produce tapiId; a parts lookup can produce parts[] and matchLevel.

matchLevel communicates the documented strength of a VIN-parts assignment. It must be stored and interpreted with the result. Do not collapse every value into “fits”.

Vehicle–part compatibility

Two public evidence scopes for vehicle–part compatibility must remain separate:

GET /parts/oe/{oeNumber} returns the available type-level fitment[] assignments for a confirmed OE base part. It is the reverse OE-to-vehicle-type view, but its keys are opaque and the response makes no catalogue-wide completeness promise.
POST /vin/cart-check checks submitted OE-number positions against one concrete VIN at mode=type|vehicle. Interpret every line together with the response's completeness signal.

Neither result is an installation approval. Do not infer VIN-specific fitment from a type-level assignment, an OE family member, VDI or a replacement edge.

Marketplace article optimisation

Marketplace article optimisation is the publication-side counterpart to the part data: for one OE number it produces the content an article needs in a marketplace or shop — the listing title, the marketplace category, the item specifics, search keywords and the on-page SEO text. GET /parts/oe/{oeNumber}/seo implements it, and marketplaceId selects the target marketplace. The documented marketplaces are the eBay sites (EBAY_DE by default, through to EBAY_US), so "eBay article optimisation", "eBay listing title", "eBay category" and "eBay item specifics" all resolve to this one operation and its content.ebayTitle, categoryId and itemSpecifics[] fields.

The result is publication content, not compatibility evidence. It says how an article should be titled, categorised and described; it never states that the part fits a particular vehicle. Keep it separate from fitment[] and from a cart check, and review it before publishing.

Key relationships

VIN
  -> vehicle lookup
  -> tapiId
  -> technical vehicle data or listing text

VIN
  -> vehicle-related parts lookup
  -> parts[] + matchLevel + parts[].tapiGenArt + parts[].vdi[]

OE number
  -> optional normalization decision
  -> confirmed normalizedOeNumber
  -> base OE lookup
  -> part + tapiGenArt + vdi[] + fitment[] + replacementChain[] + references[] + referenceNumbers

OE number
  -> marketplace article optimisation (marketplaceId + language)
  -> ebayTitle + categoryId + itemSpecifics[] + keywords[] + shop SEO text

VIN + OE-number positions
  -> OE-cart check
  -> position results + completeness

registration-document file URL
  -> POST /scanner/document/registration/international
  -> normalized document fields, including a VIN when detected
  -> vehicle lookup or vehicle intake

calculation document file URL
  -> POST /scanner/document/calculation
  -> fixed calculation fields + source-backed equipment[]

rich vehicle document file URL
  -> POST /scanner/document/vehicle
  -> detailed vehicle + equipment[] + warnings

The graph is a routing model, not a claim that each arrow always succeeds. Exact success, null and error behaviour comes from the selected operation's OpenAPI responses.