Integration recipes

These recipes translate the published OpenAPI 1.71.0 contract into implementable integration sequences. The OpenAPI document remains authoritative for every schema, enum, status and error code.

Use the server URL https://api.tapinomahub.com and append the paths shown below. Send Accept: application/json and keep X-Api-Key in a server-side secret store. A sandbox key uses the same server URL and follows the documented sandbox behaviour.

Rules shared by every recipe

Tenant and concurrency rules

• The API has no tenant field. A Tenant is separated by assigning it its own Client, normally a Sub-user or partner-workspace response, and using that Client's API key.
• Never select a tenant by request-body data, VIN, OE number or a caller-supplied header. Resolve the authenticated tenant to one stored API-key secret before constructing the request.
• The contract allows one active API request per Client. Serialize calls for the same Client. Different Clients may run in parallel.
• A tapiId is accessible only with the Client key used for the documented VIN flow. A foreign or unknown tapiId returns 404.
• Never send an API key to browser code. The browser redirect flow returns a redirectUrl; the server-side API key is not part of that redirect.

Error and retry rules

• Parse the HTTP status first and the stable top-level error value second. Do not branch on the human-readable message.
• Treat 400, 404 and 422 as data or workflow decisions. Correct or reconcile the input before another attempt.
• Treat 401 and 403 as authentication, authorisation, Client-state or sandbox-availability decisions. Do not rotate or replace a key automatically.
• Treat 402 as a billing or coverage decision. Do not loop while the plan, balance or sponsorship state is unchanged.
• For 409, branch on the documented error. In particular, never hide vin_provider_mismatch, redirect_required or an idempotency conflict behind a generic retry.
• For 429, honour Retry-After. client_request_in_progress also means the Client queue is not correctly serialised.
• Retry 500, 502 and 503 only when the corresponding error-catalogue entry is retryable, and use a bounded backoff. A write retry must reuse its original Idempotency-Key.
• The contract states that a pre-charged call ending at HTTP 400 or above is refunded automatically, subject to the explicitly documented combined-VIN exceptions. A refund does not turn a failed result into a success.
• Capture X-Tapinoma-Billing-Source, X-Tapinoma-Billing-Bundle, X-Tapinoma-Sponsorship-Grant and X-Tapinoma-Usage-Warning when present. Warning text is for people and is not stable program input.

Idempotency rules

• Send Idempotency-Key only to operations that declare it and follow that operation's schema. Intelligence explicitly requires it on GET /parts/intelligence, GET /parts/clusters/{clusterId}/intelligence and GET /parts/clusters/{clusterId}/history as well as its VIN POST; neither Intelligence status poll declares it.
• Persist the key before the network call. The same Client, operation and canonical request body must reuse the same key after a timeout.
• A first stored success reports X-Tapinoma-Idempotency-Stored: true; a replay reports X-Tapinoma-Idempotent-Replay: true. Successful replay records are retained for 24 hours.
• On 409 idempotency_request_in_progress, wait for Retry-After and repeat with the same key. On 409 idempotency_key_conflict, stop because the key was used for different input. On 409 idempotency_result_unavailable, do not substitute a new key automatically.
• Treat the preceding stored/in-progress/result-unavailable rules as operation-specific. The four initiating Intelligence pilot operations document only the replay header and 409 idempotency_key_conflict; they do not declare the stored header, the other two central 409 states or a 24-hour retention promise.
• createClientUser, createClientUserApiKey and createPartnerWorkspace issue a raw API key and reject Idempotency-Key. After an uncertain response, do not repeat them blindly.

Asynchronous rules

• Six documented job families have a polling contract: VIN parts, cart check, VIN economic evaluation, part-image generation, part-cluster refresh and VIN Economic Intelligence.
• A 202 is an accepted job, not a business result. Persist jobId, statusUrl, createdAt, the originating operation and the original business key before acknowledging the request locally.
• Honour both the Retry-After header and the retryAfterSeconds body value. If both are present and differ, wait for the longer interval and record the discrepancy. Use the required full statusUrl; compare Location and quarantine a mismatch rather than origin-resolving its current root-relative example. Do not resubmit the initiating operation merely because it returned 202.
• Continue for queued and running. Older status resources can express those states inside HTTP 200; the two Intelligence status operations return HTTP 202 while pending and HTTP 200 with the final result. Require the workflow's usable result before completion and quarantine invalid state/result combinations. A required vdi array that is present as [] is a complete VIN-parts field value, not a reason to continue polling.
• Polling belongs to the original order and does not create a second order; rate limits and the single-active-request rule still apply.

Storage and retention

Operation-specific expiry and refresh behaviour does not grant a general right to retain request or response data.

Storage and retention: The public contract does not grant a general right to retain submitted content or returned data. The integrating system must apply an approved retention policy, minimise personal data and copy an output asset only when that policy permits it.

Recipe 1: ERP vehicle, parts and cart integration

Goal and non-goals

Goal: enrich an ERP vehicle record, retrieve the correctly characterised parts set and optionally check one to 30 ERP cart positions against a VIN.

Non-goals: creating orders, changing stock, proving installation compatibility from a type-level or incomplete result, or treating tapinomahub content as the ERP's accounting record.

Prerequisites

• One server-side API key per ERP tenant or end customer.
• A legal basis for transmitting the VIN and using the returned data.
• A configured numeric provider value permitted by the Client's contract.
• For browser-assisted route 1, an HTTPS returnUrl without credentials or fragment and a server-side correlation store. The ERP should generate an opaque state and enforce one-time use locally; the API contract only promises to return the value unchanged. Any continuation to VIN-dependent operations additionally requires a full 17-character VIN known independently of the callback.
• An ERP business key for the vehicle and, for cart checks, a stable request key and an ordered list of at most 30 OE positions.

System-of-record boundary

The ERP remains authoritative for customers, the individual physical vehicle, work orders, cart lines, quantities, stock, negotiated prices and accounting. The tapinomahub API supplies derived vehicle, parts and comparison data. Subject to the approved data policy, keep the VIN and ERP vehicle ID distinct from tapiId: tapiId identifies a technical vehicle type and several VINs may share it.

Operation sequence

1. Optionally verify connectivity with GET /ping (getSystemStatus). Do not send Idempotency-Key to this read operation.
2. Establish vehicle context with exactly one of these entry branches:
   • Direct server-to-server branch: call GET /vin/{vin}/vehicle (getVehicleByVin) with explicit provider=2 or provider=3, the two-letter country, and explicit choices for the optional includeEquipments, includeColors and includeTechnical flags, or deliberately accept their true defaults. Carry forward the returned vin, tapiId, provider and incomplete values.
   • Browser-assisted branch: server-side, call POST /vin/redirect-sessions (createVinRedirectSession) with a 3–17-character vin input, HTTPS returnUrl and an opaque state. Use an Idempotency-Key. Redirect only the user agent to the returned redirectUrl before expiresAt. On the callback, require the original state and, as a local anti-forgery control, reject a state already consumed by the ERP; accept tapiId only when status=completed. A cancellation has no tapiId. The callback does not contain the VIN completed in the browser. Fetch technical type data with GET /vehicles/{tapiId} (getVehicleByTapiId), but treat an original 3–16-character input as a terminal boundary for later VIN-dependent calls until a full VIN is obtained independently.
3. Only with a known full 17-character VIN, retrieve parts through route 1 with GET /vin/{vin}/parts (getPartsByVin). Omit the optional provider field unless the integration explicitly needs it; if it is sent, use the documented value consistently.
   • On 200, consume vin, tapiId, provider, matchLevel, allCategorySigns, missingCategories and parts; every part contains required tapiGenArt and vdi fields, and vdi=[] is valid when no mapping is available.
   • On 202, persist jobId, statusUrl, vin, provider, createdAt and retry timing, then poll GET /vin/parts/jobs/{jobId} (getVinPartsJob).
4. If the ERP needs cart verification, call POST /vin/cart-check (checkVinCart) with {vin, country?, mode, oeNumbers} and an Idempotency-Key. mode is exactly type or vehicle; preserve request order and duplicates.
   • On 200, map results back to cart lines by array position and keep complete with every result.
   • On 202, persist the returned cart-check jobId and statusUrl, then poll only GET /vin/cart-check/jobs/{jobId} (getVinCartCheckJob).
5. Optionally read monthly usage with GET /client/usage (getClientUsage) using the same tenant key. This is monitoring data, not an ERP financial posting.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• Reject an empty or unauthorised VIN before the API call. Do not infer missing VIN characters. Permit the documented 3–16-character input only for redirect-session creation; require an independently confirmed full 17-character VIN before parts, cart, economic or recall continuation.
• Before continuing, require the business identifiers used by the next step. In particular, quarantine a successful direct-vehicle payload that lacks vin, tapiId or provider; the current VinVehicleResponse schema does not mark these properties as required.
• Likewise, validate a VinPartsResponse before use. Quarantine a successful payload that lacks vin, provider, matchLevel, allCategorySigns, missingCategories or parts; the current schema describes these top-level properties but marks none of them as required. tapiId is explicitly nullable. Every returned part must contain a valid tapiGenArt and a vdi array; preserve an empty array instead of treating the position or job as incomplete.
• A direct vehicle request with provider=1 can return 409 redirect_required; start the documented redirect flow instead of retrying the same direct request.
• On 409 vin_provider_mismatch, use the numeric route documented for the operation. Never silently switch the route.
• incomplete=true means the vehicle response is not an exact single-vehicle resolution. matchLevel must remain attached to the parts data.
• A non-empty missingCategories list means the parts list is incomplete. In a cart response, fits=false combined with complete=false is not a definitive exclusion.
• Use idempotency for redirect-session creation and cart checks. The VIN and parts reads are GETs and must not receive the header.
• Queue all initiating calls and their polls per Client. Use the same Client key throughout the documented VIN flow.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: local tenant ID, ERP vehicle ID, API Client ID or secret reference, VIN input and confirmed VIN, tapiId, returned provider, incomplete, matchLevel, category completeness, approved parts result fields including required per-position tapiGenArt and vdi, cart request positions, cart complete and results, originating operationId, OpenAPI version 1.71.0, request hash, idempotency key where applicable, HTTP status, job fields, response timestamps, billing headers and structured error status/code. This list defines integration state, not permission to retain a complete response. Keep only the minimum permitted subset for the approved duration, and never persist the raw API key in business tables.

Acceptance tests

1. A documented sandbox VIN completes the direct branch and stores distinct VIN and tapiId fields.
2. The redirect branch rejects a callback with wrong or reused state, accepts status=completed, and handles status=cancelled without creating a vehicle mapping.
3. A 200 parts result preserves provider, matchLevel, category completeness, quantities, every tapiGenArt and every required vdi array, including [].
4. A sandbox 202 parts job survives a process restart and reaches succeeded without resubmitting the initiating call.
5. A unit test built from the documented production failed job example treats nested error.code as terminal even though polling returned HTTP 200.
6. A completed redirect that began with a partial VIN can use its tapiId routes but cannot enter parts or cart calls because the callback supplies no completed VIN.
7. A schema-valid but incomplete VIN-parts payload enters quarantine instead of creating an ERP parts list.
8. Duplicate OE cart positions remain distinct and in order.
9. fits=false plus complete=false is rendered as unresolved, not incompatible.
10. Repeating a cart check with the same idempotency key produces no duplicate local operation and accepts X-Tapinoma-Idempotent-Replay: true.
11. Calls for two Clients can run concurrently, while two calls for one Client are serialised.

Operational boundary

The ERP must remain the recovery authority for policy-approved data and must not use API-side persistence as its recovery store. Retain data only under an approved policy.

Recipe 2: DMS document extraction

Goal and non-goals

Goal: extract a stable international vehicle-registration structure, rich source-backed vehicle/equipment data or the documented generic automotive document structure and attach the derivative result to a DMS record.

Non-goals: replacing the original document, proving authenticity, making OCR output legally authoritative, or using a generic document response as a vehicle-registration standard.

Prerequisites

• A DMS document ID, immutable source version and checksum.
• A publicly retrievable fileUrl that the caller is authorised to transmit and process.
• A per-tenant API key and a data-minimisation decision for holder data.
• quality=standard for personal-document operations; no other processing level is currently offered by the contract.
• Parsers generated from the pinned OpenAPI schemas RegistrationDocumentV2Response, DocumentCalculationResponse, the deprecated 11-field DocumentExtractionResponse and, when rich vehicle/equipment extraction is required, VehicleDocumentExtractionResponse.

System-of-record boundary

The DMS owns the original bytes, access control, legal hold, source checksum, document version and deletion policy. The tapinomahub response is a derived extraction. Human corrections belong in a separate DMS layer; never overwrite the original document, and retain an unmodified response only when the approved policy explicitly permits it.

Operation sequence

1. For an international vehicle registration document, call POST /scanner/document/registration/international (extractInternationalRegistrationDocument) with {fileUrl, quality?} and an Idempotency-Key. New integrations should use fileUrl, not request-property or path aliases. Use POST /scanner/document/registration (extractRegistrationDocument) only when the national {status,data} response contract is explicitly required.
2. Require HTTP 200 and format="tapinoma.vehicle-registration.v2". Persist the document, registration, holder, inspection, vehicle, fields and warnings blocks as one versioned result.
3. Index fields[] using the canonical code. Keep sourceCode, canonical English name, normalized value and sourceValue together. Do not replace proper names, addresses or identifiers with translated guesses.
4. For a repair cost calculation, appraisal, invoice or similar calculation document, call POST /scanner/document/calculation (extractCalculationDocument) with {fileUrl, quality?} and a separate Idempotency-Key. Its fixed DocumentCalculationResponse has 12 required top-level fields: documentType, documentSubType, source, document, vehicle, financials, repairAssessment, parts, labor, paint, notes and equipment. There is no request field for a caller-defined output schema. Preserve equipment[].codes[].value as a string together with equipmentKind, sourceSection and sourcePage.
5. For a vehicle order or configuration where detailed identifiers, powertrain, equipment, warnings or the explicit sensitive-data boundary are needed, call POST /scanner/document/vehicle (extractVehicleDocument) with {fileUrl, quality?, includeSensitiveData?}. Keep includeSensitiveData=false unless the caller has an approved, purpose-bound need for the omitted personal, bank, payment or contract fields. Validate schemaVersion="1.0" and persist only the approved subset of document, vehicle, equipment, sensitiveData and warnings.
6. The four old paths are deprecated compatibility aliases and never HTTP redirects: /scanner/document/extract, /scanner/vehicle-document/extract, /scanner/registration-document and /scanner/registration-document/v2. Follow the documented response and idempotency behaviour for each path.
7. If the input is a photograph whose sole purpose is VIN reading, call POST /scanner/vin/extract (extractVinFromImage) with {imageUrl, quality?}. Continue only when the returned vin is non-null and has all 17 characters.
8. If DMS workflow explicitly requires vehicle enrichment, pass the confirmed VIN into the ERP recipe's documented VIN entry branch. Keep the extraction result and vehicle lookup result as separate records.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• Ensure the source URL is an authorised absolute URL and keep it available until the synchronous response completes. The contract does not promise that inaccessible private storage can be fetched.
• Validate the whole response against the named schema before indexing any field. Null and empty arrays are valid documented outcomes; do not manufacture missing values.
• Treat documentType and documentSubType from extractCalculationDocument or the deprecated extractDocument path as uncontrolled strings, not enums.
• In extractVehicleDocument, validate equipmentKind and availability independently. Preserve standard, variant and special as the documented kind axis and do not derive availability or pricing from it.
• A null VIN is a successful "not reliably readable" outcome, not a transport failure.
• Use a different idempotency key for the registration, rich vehicle-document, calculation and VIN-image business operations, even when they refer to the same source file. Reuse a key only for an identical retry. The canonical and deprecated paths for national registration, international registration and rich vehicle extraction share idempotency because their responses are identical. Never move one key between canonical calculation and deprecated document extraction: the latter omits equipment, so cross-contract reuse fails with HTTP 409. Do not send an idempotency key when extractVehicleDocument.includeSensitiveData=true; the endpoint rejects it and never stores that sensitive response for replay.
• Route the request with the source document's tenant key. Never select the key from data extracted from the document.
• Apply the shared error policy. In particular, do not retry an unfetchable URL indefinitely; first restore authorised reachability or issue a new URL.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: tenant ID, DMS document ID and version, source checksum, a policy-permitted source reference, operation ID, OpenAPI version, quality, sensitive-data opt-in state, request hash, idempotency key where permitted, response format or schemaVersion where present, only the response fields approved by the mapping, source-preserving vehicle/equipment code strings, warnings, extraction timestamp, validation status, human-review status, HTTP status, billing headers and structured error. This list is not permission to retain the raw response or source document. Minimise and field-restrict holder and other personal data; block production persistence until purpose, duration, deletion and access rules are approved.

Acceptance tests

1. A sandbox international-registration call validates against its named OpenAPI response and maps every fields[] element without losing sourceCode or sourceValue.
2. A missing optional value remains null; the adapter does not populate it from another field.
3. Calculation extraction maps empty parts, labor, paint and notes arrays without converting them to null and always returns the twelfth top-level equipment field.
4. A multi-page calculation example preserves every documented equipment entry, keeps codes[].value as a string including leading zeroes, and does not mix entries from another section into equipment.
5. Rich vehicle-document extraction keeps leading-zero equipment codes as strings and never infers availability from equipmentKind.
6. Vehicle-document extraction with includeSensitiveData=true sends no idempotency key and persists no replayable raw response.
7. Replaying one key and body through either path of the national-registration, international-registration or rich-vehicle alias pair produces the same result without a second execution or charge.
8. Reusing a legacy document-extraction key on canonical calculation extraction, or the reverse, returns HTTP 409; the adapter neither accepts an 11/12-field cross-contract replay nor invents a replacement key.
9. A VIN-image result with vin=null creates a review outcome and does not start a vehicle lookup.
10. A source-version change creates a new idempotency key; a network retry of the same version reuses the previous key where the operation permits it.
11. The same document ID in two tenants produces isolated calls with two different Client keys.
12. Logs and support payloads exclude the API key and unnecessary document content.

Operational boundary

Apply the DMS's approved retention and deletion policy to source files, extracted holder data and scanner results. Do not infer a retention period from the API response.

Recipe 3: marketplace or shop catalogue enrichment

Goal and non-goals

Goal: turn a confirmed OE number into traceable part master data, indicative pricing, a publication-ready marketplace article — eBay listing title, category, item specifics, keywords and shop SEO text — and optional synthetic publication images; optionally generate text for a vehicle already identified by tapiId.

Non-goals: automatically publishing unchecked content, setting the seller's final price, proving vehicle fitment from references, or presenting a generated image as a photograph of the stock item.

Prerequisites

• A shop item ID and the original OE-number input.
• A configured manufacturer hint where available, target language, vehicleType, currency and a contract-supported marketplaceId enum value. The documented marketplaces are the eBay sites EBAY_AT, EBAY_AU, EBAY_BE, EBAY_CA, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_HK, EBAY_IE, EBAY_IT, EBAY_NL, EBAY_PL, EBAY_SG and EBAY_US, with EBAY_DE as the default. SEO languages are de, en, fr, es, it, nl, pl and zh; do not invent enum values.
• Publication rules for minimum content quality, live availability, synthetic disclosure and human review.
• Authorised reference-image URLs if image generation uses them.

System-of-record boundary

The shop owns SKU identity, stock, tax, final price, offer state, publication approval, customer orders and its stored media. The tapinomahub API supplies normalized references, documented type-level fitment, descriptive enrichment, an indicative price evaluation and generated assets. fitment, references, referenceNumbers, replacementChain, aftermarket references, VDI codes and generated visuals remain evidence or enrichment, not a stock identity or installation guarantee.

Operation sequence

1. Call GET /parts/oe/normalize?oeNumber={raw}&manufacturer={optional} (normalizeOeNumber). Continue automatically only when status=matched and normalizedOeNumber is non-null. Persist version, matchRule, confidence, replacement-family metadata and candidates even when the outcome is not matched.
2. Call GET /parts/oe/{oeNumber} (getOePart) with the confirmed normalizedOeNumber. Carry forward response normalizedOeNumber, tapiGenArt, vdi, part, fitment, replacementChain, references and referenceNumbers. Preserve part.name exactly as returned, including null. Treat tapiGenArt and vdi as independent best-effort enrichments: accept null and [] without discarding the confirmed base part or the other classification. Keep vehicleTypeKey opaque and preserve every fitment entry's criteria with it. fitment contains the available type-level assignments and can be empty. Preserve each {manufacturer, numbers} reference group and the exact closed referenceNumbers.oe_oem_reference_numbers[] list. Read relationship direction only from replacementChain; do not derive either reference view from that chain or the chain from those views.
3. For an indicative market range, call GET /parts/oe/{oeNumber}/price (getOePrice) with explicit condition, ISO 4217 currency and vehicleType. Persist the returned parameters, result, new, used and priceRecommendation together.
4. For the marketplace article itself, call GET /parts/oe/{oeNumber}/seo (getPartSeo) with the configured marketplaceId, language and vehicleType, and map the response onto the listing form: content.ebayTitle onto the eBay listing headline within its 80-character limit, categoryId onto the marketplace category of the requested marketplaceId, itemSpecifics[] onto the article's item-specific fields as {name, value[]}, keywords[] onto search terms, product onto product naming, and content.title, content.h1, content.metaTitle, content.metaDescription, content.slug and content.bulletPoints onto the shop page. Persist the returned publication fields with the generated text. 404 seo_no_exact_match is a documented no-match for that OE number and marketplace, not a failure of the item flow.
5. If a standalone part designation needs translation, call GET /translation/translations?sourceLanguage={language}&text={one-part-designation} (translatePartName). The text parameter must contain exactly one part designation, not a title, sentence, list or description.
6. For synthetic publication images, call POST /vision/part/generate (generatePartImagesFromOeNumber) with an Idempotency-Key and VisionPartGenerationRequest:
   • oeNumber is required.
   • angles contains one to six values from front, rear, left, right, left_45 and right_45 when supplied.
   • surfaceFinish=manufacturer_color requires colorCode; supplying colorCode with auto selects that finish.
   • referenceImageUrls contains at most eight authorised URLs.
   • sourceMode is one of references_required, references_preferred or knowledge_only; knowledge_only must not be combined with reference URLs.
   • generateBaseModel defaults to true. Set it explicitly to false unless the shop needs the optional model asset and has a storage policy for it.
7. The generation call returns 202. Retain the job reference and poll GET /vision/part/generation-jobs/{jobId} (getPartImageGenerationJob) until terminal. On success, validate every required VisionPartGenerationResult block: format, oeNumber, coverage, basis, synthetic, disclosure, finish, part, dimensions, materials, paintableSurface, baseModel, views, identifierProtection, limitations and generatedAt. Copy every required views[].imageUrl into the customer workflow and verify views[].sha256. When baseModel.status=generated and baseModel.modelUrl is non-null, process that asset too and verify baseModel.sha256 when the field is present.
8. For a vehicle listing, only when the Client already owns a valid tapiId, call POST /vehicles/{tapiId}/listing (composeVehicleListing) with {quality?, language?, notes?} and an Idempotency-Key. language is de, en or fr. Persist format, tapiId, language, title, description, highlights, documentedEquipmentCount and truncated.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• Stop or request review for unresolved, ambiguous or invalid normalization. valid=true alone proves syntax, not existence.
• A base-part 404 or ambiguous 422 blocks the automatic enrichment chain.
• In a validated 200, treat an empty fitment list as “no assignments returned”, not as global negative proof. Do not manufacture additional assignments locally. Use POST /vin/cart-check for a specific VIN.
• Validate references[] as closed {manufacturer, numbers} groups and referenceNumbers as the closed {oe_oem_reference_numbers} object. Do not infer direction, interchangeability or fitment from either reference view, and do not derive either view from replacementChain.
• Read a zero price range through result: no_listings_found means no listing was usable, not that the part is worth nothing. A range is only evidenced when result is priced. If the evaluation could not be carried out at all, the endpoint answers with an error status rather than zeros. The returned currency is a filter, not evidence of conversion.
• Use the returned SEO content and live-availability metadata as publication gates. A successful response still requires editorial review before publication.
• Every generated view is synthetic. Retain basis, disclosure, identity-verification flags, verificationConfidence, skipped angles and limitations with the asset. Do not claim that it depicts the actual stock item's wear or condition.
• Use idempotency for image-generation and vehicle-listing POSTs. GET normalization, base data, price, SEO, translation and job polling must not receive the header.
• Run the complete item flow under one tenant key. The idempotency namespace and tapiId scope are per Client.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: tenant ID, shop item ID/SKU, raw and normalized OE values, manufacturer hint, normalization rule-set version/status/rule/confidence, tapiGenArt, VDI codes, policy-permitted base-part, fitment, reference-family and directed replacement facts, price request dimensions and response ranges, SEO request dimensions and returned publication/content fields, translation source text/language and result, image-generation request, job state, required generation provenance, copied asset locator and checksum, tapiId for vehicle listings, idempotency keys, operation IDs, OpenAPI version, timestamps, billing headers, publication-review decision and structured errors. Retain only the minimum approved subset; no complete payload or generated asset has an implied storage or redistribution right.

Acceptance tests

1. matched normalization proceeds with the returned normalizedOeNumber; all other statuses stop before the base-part call.
2. The adapter accepts both populated and empty fitment lists, keeps every criteria[] value with its vehicleTypeKey and never manufactures assignments locally.
3. A reference or comparison number, replacement edge, aftermarket reference or VDI code never creates a compatibility claim by itself; returned fitment[] remains type-level evidence rather than a VIN-specific guarantee.
4. The price adapter preserves condition, currency, vehicleType, result and confidence with the range.
5. The SEO adapter accepts the documented publication fields, fills the listing title, category and item specifics from content.ebayTitle, categoryId and itemSpecifics[], tolerates a null categoryId and an empty itemSpecifics[], and handles optional live-availability metadata separately.
6. Image generation persists 202 before polling, resumes after restart and verifies each downloaded asset against sha256.
7. A generated base-model asset is copied to controlled storage and its checksum is verified when present; generateBaseModel=false creates no dependency on modelUrl.
8. knowledge_only plus referenceImageUrls is rejected before transmission.
9. The published image is visibly governed by the returned synthetic disclosure and never labelled as a stock photograph.
10. Replaying the generation request with its original idempotency key does not create a second local job or media set.

Operational boundary

When the approved data policy permits copying an accepted generated asset, move it to controlled storage before publication and verify its checksum. Do not treat a returned asset URL as permanent storage.

Recipe 4: parts inventory and dismantling

Goal and non-goals

Goal: identify photographed parts, normalize candidate OE numbers, attach public part classifications, evaluate inventory and recall context, and optionally rank expected dismantling value for a VIN.

Non-goals: certifying a physical part's identity from OCR alone, proving that a reference fits a particular vehicle, replacing a dismantler's inspection, or turning an economic evaluation into an automatic purchase decision.

Prerequisites

• A unique local stock-unit ID for every physical part and, when applicable, a local vehicle-unit ID.
• Authorised, publicly retrievable label or part-image URLs.
• A configured condition and vehicleType for pricing, and explicit economic assumptions for vehicle evaluation.
• A review queue for multiple OCR candidates, ambiguous normalization, incomplete VIN parts and recall matches.

System-of-record boundary

The inventory or dismantling system owns the physical unit, provenance, serial/instance identifiers, measured condition, location, quantity, cost, sale state and disposal decision. The tapinomahub API provides OCR candidates, OE reference data, classification codes, indicative price data, series-level recall context and a modelled economic evaluation.

Operation sequence

Part-unit intake

1. Call POST /scanner/label/extract-partnumbers (extractLabelPartNumbers) with {imageUrl, quality?} and an Idempotency-Key.
2. Read partNumbers[]; production and sandbox use the same response shape. Preserve every candidate and do not select one only because it appears first.
3. For each candidate, call GET /parts/oe/normalize (normalizeOeNumber) with oeNumber and an optional manufacturer hint. Proceed only with a confirmed matched result.
4. Call GET /parts/oe/{oeNumber} (getOePart) for the confirmed normalized number. Store tapiGenArt, vdi[], part, fitment, replacementChain, references and referenceNumbers as distinct reference data linked to the physical stock unit. Preserve part.name as the returned string or null. Treat tapiGenArt: null and vdi: [] as independent missing enrichments, not as a failed base lookup. Keep criteria[] attached to its opaque vehicleTypeKey. fitment contains the available type-level assignments and can be empty. Preserve grouped and consolidated references as returned, and never derive them from the replacement chain or turn them into an undirected substitution rule.
5. Load the classification catalogue with GET /vdi (getVdiCatalog). Prefer the unpaginated response when feasible. If paging is required, use limit from 1 to 500, advance offset by page.returned, and stop on page.hasMore=false. Version the local index by stand.catalogVersion. This catalogue does not return part mappings; use only VDI codes already returned by getOePart or by a successful VIN-parts position for the link.
6. Optionally call GET /parts/oe/{oeNumber}/aftermarket-references (getOeAftermarketReferences). These are reference records, not interchange or fitment guarantees. Prefer an unpaginated response; if paging, use page.returned and page.hasMore.
7. Optionally call GET /parts/oe/{oeNumber}/price (getOePrice) with explicit condition, currency and vehicleType.
8. For cluster-level market evidence, call GET /parts/intelligence (resolvePartIntelligence) with the confirmed OE number, explicit market dimensions and its required Idempotency-Key. On 202, persist and poll only GET /parts/intelligence/jobs/{jobId} (getPartIntelligenceJob). On completion, keep the returned clusterId, clusterVersion, scope and snapshot metadata together.
9. With a known cluster, read current Intelligence through GET /parts/clusters/{clusterId}/intelligence (getPartClusterIntelligence) or materialized snapshots through GET /parts/clusters/{clusterId}/history (getPartClusterIntelligenceHistory). Both require their own idempotency key; history also requires from and to and never starts a job.
10. For recall context, batch one to 100 stock positions into POST /recalls/parts (matchPartRecalls). Send each as {oeNumber, reference, vehicle?} where reference is the local stock-unit key, and use an Idempotency-Key. Map results by returned reference and preserve register data versions and the scope notice.

Vehicle-level dismantling evaluation

1. Call GET /vin/{vin}/economic-evaluation (getVinEconomicEvaluation) with a known full VIN and the documented business parameters such as country, condition, vehicleType, maxPricedParts, recoveryRate and costPerPart.
2. On 200, persist the result. On 202, persist the job and poll GET /vin/economic-evaluation/jobs/{jobId} (getVinEconomicEvaluationJob).
3. Consume the echoed assumptions, coverage, revenuePotential, purchaseRecommendation and ranked parts together. Preserve warnings and liveAvailability when present; both are optional. Incomplete coverage makes the totals a lower bound.
4. If the workflow needs the underlying vehicle-related parts without an economic model, call GET /vin/{vin}/parts (getPartsByVin) and follow its 200/202 branch via GET /vin/parts/jobs/{jobId} (getVinPartsJob). Retain matchLevel and missingCategories.
5. When cluster-based valuation is required, call POST /vin/economic-intelligence (createVinEconomicIntelligence) with VIN, market country, currency, condition and a separate Idempotency-Key. On 202, poll only GET /vin/economic-intelligence/jobs/{jobId} (getVinEconomicIntelligenceJob). Keep final evaluationId, pipeline, portfolio, candidates, confidence, provenance and warnings together; do not substitute this response for the legacy evaluation shape.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• OCR output is a candidate set. Require normalization and, where business risk warrants it, human confirmation against the physical label.
• Treat normalization ambiguous and unresolved as review states. Do not join on lookupKey as if it were a confirmed OE number.
• An empty VDI list means no confirmed mapping. An empty replacement chain means no documented replacement. Neither permits a locally invented classification.
• Because the aftermarket response has conflicting wording around count and paginated list length, do not use count == aftermarketReferences.length as a paging invariant. Use page.returned and page.hasMore, or omit pagination.
• Validate every VIN-parts success before consuming it. A response missing expected public fields must enter quarantine rather than producing an incomplete stock record.
• Recall results are series-level information as of the returned register data version. They do not prove whether a specific physical vehicle or part is affected or remediated.
• Economic output is valid only with its returned assumptions and coverage; retain and apply any warnings that are present. Do not compare evaluations that used different dimensions without normalising them in the inventory system.
• Use idempotency wherever the selected operation declares it. The three Intelligence data GETs require the header; their status polls do not. Serialize calls per tenant Client, including polls.
• Keep observedSupply, verifiedSales and internalUsage separate. Supply listings are not sales. Block automated pricing, dismantling or acquisition when publishable=false, evidence is insufficient, or confidence violates the configured review threshold.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: tenant ID, stock-unit and vehicle-unit IDs, a policy-permitted source image reference/checksum, OCR response variant and candidates, normalization input and approved result fields, confirmed normalized OE number, tapiGenArt, VDI codes and catalogue version, permitted part/replacement/reference facts, price dimensions and result, recall position reference/status/measures/register versions/notice, VIN, tapiId, parts matchLevel and completeness, cluster ID/version, market scope, asOf, snapshot ID, separated evidence blocks, prices, standtime, trend, scores and confidence, VIN Intelligence evaluationId, pipeline/portfolio/candidates/provenance/warnings, job family/state, idempotency keys, operation IDs, OpenAPI version, timestamps, billing headers, review decisions and structured errors. Retain only the minimum approved subset for its stated purpose and duration; this model is not permission to retain images or full responses.

Acceptance tests

1. The adapter accepts both declared label-response property names and preserves each candidate as a separate value.
2. Two OCR candidates remain separate until each normalization result is evaluated.
3. A VDI catalogue refresh is keyed by catalogVersion; an OE mapping is never inferred from catalogue content.
4. Unpaginated and paginated classification loads produce the same ordered entry set; pagination stops by page.hasMore.
5. Recall batch responses map back to duplicate OE numbers by unique local reference, not by number alone.
6. A 202 economic job resumes after restart, and a nested failed status never creates a recommendation.
7. A response with incomplete coverage is labelled as a lower bound and cannot pass an automatic purchase threshold without the configured review rule.
8. Two tenants using the same stock-unit string remain isolated by Client key.
9. A resolver 202 survives restart and polls only the part-Intelligence status route; its jobId fails safely on the VIN status route.
10. History never creates a job or a synthetic missing point, and cluster version, snapshot ID, scope and asOf remain attached to every stored point.
11. Observed-supply counts never populate verified-sale counts, and publishable=false cannot trigger automated pricing or acquisition.
12. Final VIN polling yields an evaluationId equal to the preceding jobId and requestId in the current pilot; the adapter retains the three field roles and never generalises this intentional alias to another job family.

Operational boundary

Retain submitted images, OCR results, jobs and evaluation evidence only as permitted by the approved policy. Do not rely on API-side history as the integrating system's recovery store.

Recipe 5: vehicle intake

Goal and non-goals

Goal: create a vehicle file from a registration-document URL, optionally add a visual condition report, preserve partial component outcomes and continue with technical data, recalls or listing text.

Non-goals: transferring ownership of the original document, performing a roadworthiness test, creating an expert appraisal, or treating tapiId as the physical vehicle's unique identifier.

Prerequisites

• A local intake ID for the physical vehicle.
• An authorised public fileUrl and, optionally, one to five authorised photoUrls of the same vehicle.
• A two-letter country and an explicit decision whether holder data is necessary. Default to includeOwner=false.
• A tenant Client key and an idempotency key persisted before submission.

System-of-record boundary

The intake system owns the physical vehicle, source documents and photos, consent/legal basis, custody, workflow status, human inspection, keeper-data policy and sale decision. The tapinomahub API returns a document extraction, matched vehicle-type data and an optional visual-only condition report.

Operation sequence

1. Call POST /vehicles/intake (intakeVehicle) with {fileUrl, photoUrls?, country?, includeOwner?} and an Idempotency-Key.
2. A successful intake is synchronous HTTP 200; this operation has no 202 branch. Validate format, registrationDocument, vin, provider, tapiId, vehicle, conditionReport, components and complete.
3. Evaluate each component independently:
   • components.registrationDocument is delivered on every successful response.
   • components.vehicle is delivered, vin_not_readable or unavailable.
   • components.conditionReport is delivered, failed or not_requested.
   • complete=true only when every requested component was delivered.
4. If tapiId is non-null, optionally call GET /vehicles/{tapiId} (getVehicleByTapiId) to retrieve the technical vehicle-type record.
5. If a new or larger photo set must be assessed independently, call POST /vision/condition-report (reportVehicleCondition) with one to eight imageUrls, optional quality and a new Idempotency-Key. Preserve gradable, grade, reason, all eight zones, limitations, imageCount and visualOnly.
6. If VIN is non-null, optionally call GET /recalls/vehicles/{vin} (matchVehicleRecalls) and preserve measures, register versions and the scope notice.
7. If tapiId is non-null and publication text is required, call POST /vehicles/{tapiId}/listing (composeVehicleListing) with {quality?, language?, notes?} and a separate Idempotency-Key; language is de, en or fr.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• Verify that all photo URLs refer to the same vehicle before calling the API.
• Do not request holder data unless the intake purpose requires it. When includeOwner=false, keep the returned owner block null and do not enrich it elsewhere.
• A successful HTTP 200 can still be a partial vehicle file. Never require non-null vin, tapiId, vehicle or conditionReport without checking components.
• visualOnly=true means the condition report is not an expert appraisal, measurement or functional test. A null grade with gradable=false is a valid outcome; retain reason and limitations.
• Use separate idempotency keys for intake, a later condition report and listing generation. Retry the same timed-out write with its original key and identical body.
• Use the same tenant Client for the intake and every tapiId continuation. A 404 from a continuation can mean the reference is unknown or foreign; do not copy data across tenants.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: tenant ID, local intake ID, policy-permitted document/photo references and checksums, includeOwner, country, request hash, intake idempotency key, response format, approved registration-document fields, VIN, tapiId, numeric provider, approved vehicle and condition fields, each component status, complete, permitted later technical/recall/listing facts, separate idempotency keys, operation IDs, OpenAPI version, timestamps, billing headers, human-review status and structured errors. Retain only the minimum approved subset and block production persistence until document, photo and holder-data rules are approved.

Acceptance tests

1. A complete sandbox intake validates all required response fields and links the local intake ID, VIN and tapiId without conflating them.
2. A fixture with components.vehicle=vin_not_readable persists the document result, leaves vehicle fields nullable and does not call VIN-dependent endpoints.
3. A fixture with components.conditionReport=failed records a partial success and does not discard delivered document or vehicle data.
4. includeOwner=false never produces a locally populated owner record.
5. A condition report with gradable=false and grade=null enters review and preserves all limitations.
6. Replaying the intake key produces one local intake result and recognises the idempotent response headers.
7. A tapiId obtained under one Client is not resolved using another tenant's key.

Operational boundary

The intake system must remain the recovery and retention authority for the vehicle file, source document, photos, holder data and condition report. Apply an approved retention policy to every stored field.

Recipe 6: multi-tenant middleware

Goal and non-goals

Goal: provide a controlled server-side adapter that provisions isolated workspaces, routes calls with the correct key, serialises per-Client work, normalises retries and polling, and exposes usage to operations.

Non-goals: exposing the master key, accepting arbitrary pass-through paths, inventing endpoint keys, combining tenant data, or becoming the system of record for ERP, DMS, marketplace, inventory or vehicle workflows.

Prerequisites

• A Master client API key kept in a privileged secret store and unavailable to normal business-call workers.
• A durable tenant registry with a unique local tenant ID and immutable externalReference matching ^[A-Za-z0-9._:-]{1,80}$.
• A contractually supplied allowlist of valid endpointKeys. OpenAPI does not publish a complete operation-to-endpoint-key mapping, so middleware configuration must not derive one from paths.
• A per-Client queue, idempotency ledger, async-job store, secret manager and audit log.

System-of-record boundary

The middleware owns Tenant-to-Client mapping, secret references, request correlation, idempotency state, queue state, job state and transport audit. The calling business system owns its source and result records. tapinomahub owns API authentication, Client-level billing/limits and the returned service result. The middleware must not merge results merely because two Tenants used the same VIN, OE number, jobId or local reference.

Operation sequence

Tenant provisioning

1. Reserve the local externalReference in a pending provisioning record before any network call.
2. With the master key, call POST /client/partner-workspaces (createPartnerWorkspace) with no Idempotency-Key. Send:
   • required name, externalReference and one to 50 contract-approved endpointKeys;
   • optional sponsorship and applicationLabel.
   • Omit rateLimits in this call: OpenAPI exposes that array but does not define its item fields. Apply limits through the typed operation in step 4.
3. On 201, validate that workspace.id and workspace.externalReference are present before activating the tenant; the top-level workspace is required but its inner properties are not marked required by the current schema. Then atomically persist those values, apiKey.id, a secret-manager reference to the one-time raw apiKey.key, allowlist and sponsorshipGrant. The apiKey object's id, label, key and createdAt are required. Never write the raw key to logs or ordinary database columns.
4. If limits were not final at provisioning, call PUT /client/users/{clientId}/rate-limits (replaceClientUserRateLimits) only after contractual clarification or controlled onboarding configuration has established the Client ID independently of workspace.id. Use the Master client key, {rateLimits} and an Idempotency-Key. Each RateLimitInput supplies endpointKey, windowSeconds, maxRequests, optional apiKeyId and optional isActive.
5. If sponsorship terms require a later explicit grant, call PUT /client/sponsorship-grants/{grantReference} (upsertSponsorshipGrant) with the Master client key, a stable grantReference, an explicitly sourced beneficiaryClientId, approved endpointKeys and optional contract fields. Use an Idempotency-Key; do not infer beneficiaryClientId from workspace.id.
6. If the beneficiary is authorised to choose sponsor terms, use its own tenant key for PUT /client/sponsorship-grants/received/{grantReference}/billing-mode (chooseSponsorshipBillingMode) with {mode, sponsorClientId?} and an Idempotency-Key.

Runtime routing

1. Authenticate the middleware caller and resolve exactly one local tenant record.
2. Reject any requested capability outside that Tenant's local allowlist before selecting a tapinomahub path.
3. Load only that Tenant's API-key secret and enqueue the call by the stable local Tenant record that represents exactly one tapinomahub Client, or by the explicitly established Client ID. Never partition concurrency by API-key ID: several keys can belong to one Client and must share its single queue. Then construct a request for an explicitly supported operation.
4. Obtain or create a durable business-operation idempotency key only when the selected operation declares it. This includes the three Intelligence data GETs; omit it from both Intelligence status polls and other GETs that do not declare it.
5. Apply the shared status/error policy. Persist a 202 before releasing the Client queue; schedule the documented poll through the same per-Client queue and matching tenant key.
6. Expose operational consumption using either GET /client/usage (getClientUsage) with the Tenant key or, only when the {clientId} mapping is explicitly established, GET /client/users/{clientId}/usage (getClientUserUsage) with the Master client key. GET /client/credits (getClientCredits) reports the authenticated Client's current balance or partner billing mode.

Key and Client lifecycle

1. Create an additional Tenant key with POST /client/users/{clientId}/keys (createClientUserApiKey) only for an explicitly established Client ID, using the Master client key and optional {label}. Do not send Idempotency-Key. Before cutover, require apiKey.id, apiKey.label, apiKey.key and apiKey.createdAt; neither the response wrapper nor ApiKeyCreateResponse currently marks these fields as required. If any is missing, enter reconciliation_required and do not repeat the call automatically. Store a complete raw key once as for initial provisioning.
2. Move traffic to the new secret only after a successful authentication test such as GET /ping (getSystemStatus).
3. Deactivate a Tenant with PATCH /client/users/{clientId} (updateClientUser) only for an explicitly established Client ID and {isActive:false} using an Idempotency-Key. Confirm subsequent Tenant-key calls are rejected before marking offboarding complete locally.

Identifiers carried forward

Validation, errors, idempotency and tenant handling

• Treat the API key as the effective tapinomahub Client selector. Never permit a caller to supply or override X-Api-Key.
• Enforce allowlisted operation IDs and paths locally; do not operate as a transparent arbitrary-path proxy.
• Provisioning and additional-key creation are not replay-safe. On timeout or lost response, mark provisioning reconciliation_required and do not call again automatically. A duplicate externalReference prevents a second partner workspace, but the public contract has no lookup-by-external-reference or raw-key recovery operation.
• RateLimitInput requires endpointKey, windowSeconds and maxRequests in its schema. Always send all three even though descriptions mention defaults. Validate allowed endpoint keys and windows against supplied contract configuration.
• On 429 client_request_in_progress, retain the same tenant job and fix or drain its Client queue. Do not move the call to another tenant key.
• On idempotency 409, apply the shared exact branches. Idempotency keys are per Client, so the same textual value in two Clients is not a cross-tenant correlation key.
• Keep master administration, tenant business calls and beneficiary billing-mode changes in separate credential scopes.

Persistence fields

Subject to an approved data-class policy, model the following logical fields: local tenant ID, provisioning state, externalReference, separately sourced Client/workspace identifiers, parent/master relation, active state, allowed operation IDs, contract-supplied endpoint keys, API-key ID/label/created time and secret reference, never the raw key, rate-limit facts, sponsorship reference and state, billing mode, queue lease/state, request correlation ID, canonical request hash, operation ID/path/method, idempotency key and replay flags, HTTP status, job fields, retry schedule, response schema version, billing/warning headers, permitted usage facts, structured error and audit timestamps. Persist only the minimum approved subset; key-secret handling follows the secret-store rule independently of business-data retention.

Acceptance tests

1. Provisioning returns one Client and stores the one-time raw key only in the secret manager; logs and database exports contain no secret.
2. A workspace success missing workspace.id or workspace.externalReference and an additional-key success missing raw key material both enter reconciliation rather than activation.
3. Provisioning omits untyped rateLimits; the subsequent typed replacement call persists the returned limit set.
4. An uncertain provisioning response enters reconciliation and is not automatically repeated.
5. A caller cannot override its resolved Client key or invoke an operation outside the local allowlist.
6. Two tenants run in parallel, while two requests for one Client execute serially.
7. A 202 job remains tenant-partitioned, survives restart and polls with the same Client key.
8. Every operation declaring idempotency has a durable pre-dispatch record; Intelligence data GETs carry the header and GET status polls do not.
9. 409 idempotency_key_conflict, 409 idempotency_request_in_progress and 409 idempotency_result_unavailable reach distinct middleware states.
10. Once a Client ID is explicitly established, usage obtained with the Master client key for {clientId} is assigned to the same Tenant as usage obtained with that Tenant's own key; without that mapping, the master-side assertion remains blocked.
11. New-key cutover succeeds only after a tenant-key health call; deactivation makes the old tenant key fail authentication.

Operational boundaries

Use only documented lifecycle operations and fields. Supply endpoint-key mappings and recovery procedures as controlled configuration, quarantine incomplete provisioning responses, and apply the calling system's authorised retention policy to business data.