Parts manufacturers, suppliers and data providers: validating OE references and enriching article data

Where data is missing in the process

A supplier's article carries its own number and a list of the OE numbers it replaces. That list is the anchor by which trade and workshops find the article — and the part of the record most often produced by hand, see OE number. The typical places:

• When the reference list is created. OE numbers come from engineering documents, dealer invoices and competitor catalogues — with spaces, with hyphens, without index letters. Whether 5Q0 919 275 C and 5Q0919275C are the same number is decided by a member of staff while reading.
• In classification. Article type and VDI 4081 position are picked per article from a dropdown. For wear parts that is quick; for electronics and body parts it is rarely consistent.
• In translation. Designations are translated by hand per target language or taken from an old catalogue; marketplace texts once more per country.
• In price orientation. Where an article sits in the market is derived from individual competitor prices, without date and without source.
• After delivery. Whether an OE number in the list has since been affected by a recall is checked by nobody — the registers are not connected to the master data.

What the API delivers

One process from start to finish

1. Prepare the classification once. GET /vdi returns the VDI 4081 catalogue with main groups and positions, plus its data state and check value. With it you map your product group scheme to VDI 4081 once; the catalogue holds no OE assignments, those come per number from the cross-check.
2. Clean up the reference list. Every OE number in the list goes through GET /parts/oe/normalize with oeNumber and, where known, manufacturer. On matched you take over the normalised spelling and the documented replacement numbers. unresolved, ambiguous and invalid stay as entered and receive a task — no case is closed by guessing.
3. Classify the article. For every confirmed number, GET /parts/oe/{oeNumber} returns exactly one tapiGenArt and, where a confirmed mapping exists, the VDI 4081 position; if the VDI 4081 mapping is empty, the product group stays open. Replacement chain, reference family and fitment come with it — see GenArt number. On 404 there was no confirmed base match: the article stays created, the classification stays open.
4. Hold your own references against the market. GET /parts/oe/{oeNumber}/aftermarket-references shows which aftermarket references are documented for an OE number — so a data provider sees where its own list deviates from the market. A reference is no guarantee of fit; an empty list is a finding, not an error — see OE, OEM, OES and IAM.
5. Designations and marketplace texts. The part designation goes individually through GET /translation/translations — exactly one per call, no titles or lists. GET /parts/oe/{oeNumber}/seo supplies product, content and item-specific fields per language and marketplace; the text is checked before publication.
6. Position the price. GET /parts/oe/{oeNumber}/price returns an indicative price evaluation from comparison and market references. It belongs in the record as a dated market reference, not as a list price — and it is no price guarantee.
7. Recalls in the nightly run. A job sends the reference list in batches of up to 100 positions to POST /recalls/parts, with vehicle.make, vehicle.model and build period where known. Per position, status, measures and confidence come back; affected articles receive a notice for trading partners.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/normalize?oeNumber=5Q0919275C&manufacturer=VOLKSWAGEN'

The integration

1. Store the key server-side. The key in the X-Api-Key header belongs in the configuration of your backend or batch system — never in the browser, never in an import script that is passed on with the data package. The path from contract to go-live is in the documentation.
2. Start with one endpoint. For master data that is GET /parts/oe/normalize on import of the reference list: one call per number, and afterwards every row has a status you can count.
3. Define the field mapping. The normalised number and the replacement numbers into the reference field, tapiGenArt onto your article type, the VDI 4081 mapping onto your product group, part.manufacturer and part.name into the master fields — and every field that returns null stays empty.
4. Separate failure from empty result. unresolved, ambiguous and invalid in normalisation, 404 in the OE cross-check and an empty reference list are empty results: keep the record, leave the field empty, raise a task. Only a technical error is retried.
5. Collect 202 responses. Long-running operations answer with 202, Location, Retry-After and a job ID; the status comes from the matching .../jobs/{jobId} endpoint at the interval of Retry-After — for instance GET /vin/cart-check/jobs/{jobId} when POST /vin/cart-check checks up to 30 OE positions against a vehicle, or GET /vision/part/generation-jobs/{jobId} for product-image jobs on new parts from POST /vision/part/generate.
6. Roll out and observe. First one product group, then the stock. GET /client/usage shows which calls run how often; the X-Tapinoma-Usage-Warning header speaks up before the credit runs out.

What to watch out for

• Set an Idempotency-Key. A nightly run that restarts after a crash sends the same batches to POST /recalls/parts. With the Idempotency-Key header the repeat is recognised and flagged in the X-Tapinoma-Idempotent-Replay response header. Exception: calls that issue a key once — after a timeout, reconcile what exists instead of creating again.
• Do not fill empty fields. unresolved does not mean „probably this number“, and a null in part.listPrice is a statement. A record that plausibly closes gaps carries the false statement into every catalogue that takes your data.
• Store the tapiId. If a process has matched a vehicle through a VIN flow, keep the tapiId; GET /vehicles/{tapiId} returns the technical data as part of that paid workflow, without VIN and equipment.
• Store results, do not re-query per export. What GET /parts/oe/{oeNumber} returns belongs to that number in your database; every request is billed from the credit.
• Never the key in the browser. A checking tool for the catalogue team also runs through your backend; rate limits per sub-user contain an import that accidentally re-checks the whole stock.
• Do not deliver SEO content as fit. SEO enrichment creates publication copy and item specifics. A fit claim must come from the dedicated part or VIN comparison.
• Check the result before delivery. Translation, SEO enrichment and price evaluation are meant for review, not for unseen forwarding. The use of the results lies with the customer.

What the API does not do

The API delivers cross-checks and analyses, not a data set: with the result you acquire no rights to the underlying data sets and no catalogue you could sublicense. What is owed is the query; checking and using the results lies with you. GET /vdi returns the classification catalogue without OE assignments, the price evaluation is indicative and no price guarantee, an aftermarket reference is no promise of fit. Vehicle data from provider 1 is not retrieved directly by third-party systems — for that there is the browser redirect via POST /vin/redirect-sessions, whose session expires after ten minutes and contains neither vehicle nor access data. The image endpoints deliver visual inspections, no expert report; a number plate on a photo leads to no keeper lookup. And where the data yields nothing, the field stays empty.