Marketplaces and shop systems for parts: enriching listings from the OE number

Where data is missing in the process

A marketplace is only as good as its sellers' records, and those rarely arrive complete. What the seller does not supply, the platform has to add or leave empty — and empty fields cost visibility, see stock data for marketplaces. The typical places:

• On listing. The seller enters an OE number but no article type and no predecessor numbers. The category comes from a dropdown, and buyers search with the number on their removed part — which is often older than the one listed.
• In multilingual listings. The part designation is translated by hand per language or stays in the source language.
• In the images. Photos from the yard have busy backgrounds, and the condition sits next to them as free text that nobody assigns consistently.
• After listing. Whether an offered part is affected by a recall is checked by nobody, because the registers are not connected to the stock.
• On the buyer's side. Whether the part fits the buyer's vehicle is settled by a query or not at all — and the return arises after shipping.

What the API delivers

One process from start to finish

1. The seller lists a part. Your software calls GET /parts/oe/{oeNumber}. On 200 you take over the normalised number, the tapiGenArt as the basis of the category and the replacement chain into the number field — see GenArt number. On 404 there was no confirmed base match: the listing is still created, the fields stay empty.
2. Search fields and language versions. GET /parts/oe/{oeNumber}/seo supplies product, content and item-specific fields for the language and marketplace. The part designation goes individually through GET /translation/translations.
3. Prepare the images. Each seller photo runs through POST /vision/part/remove/bg; the model only determines the outline, composition happens in code. One to three photos of the same part go to POST /vision/part/quality and return a grade you label as a visual inspection — see part photography.
4. New parts without a photo. For new parts without their own photo, POST /vision/part/generate starts a product-image job. The default is references_required; whoever chooses knowledge_only gets basis=knowledge and partIdentityVerified=false back and shows the image as a depiction, not as a photo.
5. Nightly recall run. A job sends the active stock in batches of up to 100 positions to POST /recalls/parts, with vehicle.make and vehicle.model where known. Affected listings receive a notice and a task for the seller.
6. The buyer adds to the cart. If the buyer provides a VIN, POST /vin/cart-check checks up to 30 positions against it — mode=type for the vehicle type, mode=vehicle for the specific vehicle. fits=false with complete=true is a conclusive no; complete=false remains an open question — see selling used parts online.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/5Q0919275C'

The integration

1. Store the key server-side. The key in the X-Api-Key header belongs in your backend's configuration — never in the browser, never in a feed, never in a seller account. The path from contract to go-live is in the documentation.
2. Start with one endpoint. For marketplaces that is GET /parts/oe/{oeNumber} on listing: one call, three filled fields, immediately measurable in number search.
3. Define the field mapping. tapiGenArt onto your category, the replacement chain into the number field, part.manufacturer and part.name into the listing fields — and every field that returns null stays empty on your side.
4. Separate failure from empty result. 404 on the OE lookup, found=false on cut-out and gradable=false on grading are empty results: create the listing, leave the field empty, raise a task. Only a technical error is retried.
5. Collect 202 responses. POST /vin/cart-check and POST /vision/part/generate answer longer runs with 202, Location, Retry-After and a job ID. The status comes from GET /vin/cart-check/jobs/{jobId} and GET /vision/part/generation-jobs/{jobId} respectively — at the interval of Retry-After.
6. Roll out and observe. First one seller group, then all. GET /client/usage shows which calls run how often; the X-Tapinoma-Usage-Warning header reports before the credit runs out.

What to watch out for

• Set an Idempotency-Key. If a call runs twice after a restart, the repeat is recognised via the Idempotency-Key header and reported 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. A null in part.listPrice is a statement. Turning it into a placeholder produces the returns that eat the visibility again.
• Do not show SEO content as fit. SEO enrichment creates publication copy and item specifics. A fit claim must come from the dedicated part or VIN comparison.
• Store the tapiId. Once a buyer account has matched a vehicle through a VIN flow, keep the tapiId; GET /vehicles/{tapiId} returns the technical data as part of the previously paid VIN workflow, without VIN and without equipment.
• Store results, do not query on every page view. What GET /parts/oe/{oeNumber} returns belongs to the number in your database; every request is billed from the credit.
• Never the key in the browser. The cart check also runs through your backend; the buyer's VIN never appears in a page URL. Rate limits per workspace contain a feed that relists everything each night.
• Check results before publishing. The SEO enrichment is meant for review, not for unseen publication. 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: what is owed is the request; use and review of the results lie with you and your sellers. The price evaluation from GET /parts/oe/{oeNumber}/price is indicative and no price guarantee. The condition grade is a visual inspection, not an appraisal; a licence plate in an image leads to no keeper lookup. 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 carries neither vehicle nor access data. And where the sources yield nothing, the field stays empty — a reference is not a fit, and a photo without a reliable finding gets no grade.