Workshop management systems: check parts against the vehicle before ordering

Where data is missing in the process

A workshop job starts with a vehicle and ends with an invoice. In between are points where the software does not know what it would need to know, and a member of staff fills it in from the catalogue or by phone:

• The parts order leaves before fitment is checked. The service advisor copies OE numbers from the catalogue into the job. Whether they fit this exact vehicle with this exact equipment shows up at fitting — or on the return.
• The OE number from the customer's paperwork is a predecessor. The number on the invoice or old part they bring has been superseded. Which one applies today, someone looks up by hand — see OE number: reading original part numbers correctly.
• The removed part carries a label nobody transcribes. Part and reference numbers of the replaced control unit end up as a photo in the job, not as a record — see Used control units: coding, immobiliser, listing.
• Recalls are not reconciled during the visit. The vehicle is on the lift; an open recall would be a second job, but the software knows nothing about it.
• The part designation exists in one language only. A business with customers or suppliers abroad translates designations on the invoice itself.

What the API delivers

One job from start to finish

1. Create the job, reconcile the vehicle. The workshop captures the VIN. Providers 2 and 3 your system queries directly via GET /vin/{vin}/vehicle. For provider 1 your server creates a session via POST /vin/redirect-sessions from vin, returnUrl and state and sends the service advisor to the redirectUrl; the return brings status=completed with tapiId and state — or status=cancelled. The session expires after ten minutes; vehicle or access data never appear in the redirect.
2. Load the included vehicle data. GET /vehicles/{tapiId} delivers the technical vehicle data for the job screen as part of the previously paid VIN workflow — without VIN and equipment and without ordering a new vehicle match.
3. Check recalls while the vehicle is there. GET /recalls/vehicles/{vin} reconciles the model line against the Kraftfahrt-Bundesamt, EU Safety Gate and NHTSA. An open measure appears in the job with file reference, remedy and stop-drive flag.
4. Classify the parts in the job. Every OE number passes through GET /parts/oe/{oeNumber}. Back come the supersession chain, the tapiGenArt as GenArt for the product group and, under part, the fields manufacturer, name and listPrice, which may be null and then stay empty. Without a confirmed base match the call answers 404.
5. Check fitment before ordering. All lines go together to POST /vin/cart-check with mode=vehicle, up to 30 per call. Each line returns fits; complete sits once at response level and says whether the vehicle's parts list was complete. With complete=true, lines with fits=false are flagged before the order; with complete=false, every no in this check remains an open question. If the service answers 202, your system collects the result via GET /vin/cart-check/jobs/{jobId}.
6. Offer alternatives and used parts. For a line without fitment or availability, GET /parts/oe/{oeNumber}/aftermarket-references delivers search candidates from the independent aftermarket, not a fitment guarantee. A used part from a dismantler is a further option; which details the workshop needs for that is covered in Workshops as customers: what a trade buyer needs differently.
7. Capture the removed part. The mechanic photographs the label; POST /scanner/label/extract-partnumbers reads part and reference numbers and files them on the job. What is not legible in the image stays a gap.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"vin":"<VIN>","mode":"vehicle","oeNumbers":["5Q0919275C"]}' \
  'https://api.tapinomahub.com/vin/cart-check'

The build

1. Keep the key server-side. The X-Api-Key belongs in your server's configuration, never in the workshop front end or a mobile app. In an on-premise installation a service on the workshop server makes the calls.
2. Start with one endpoint. For this software category that is POST /vin/cart-check: it acts where errors are most expensive and needs only data the job already holds.
3. Define the field mapping. fits into the job line, the response's complete onto every line of this check, tapiGenArt into the product group, the current number of the supersession chain into its own field next to the captured one. That mapping is the actual work.
4. Separate empty result from failure. 404 vehicle_not_found or an empty reference list are business results: the job stays, the field stays empty, a hint appears. A technical error triggers a retry or a follow-up task — never a default value.
5. Build in collection after `202`. Long-running checks answer with 202, Location, Retry-After and a job ID. Your system polls GET /vin/cart-check/jobs/{jobId} without blocking the job screen.
6. Roll out and observe. One pilot workshop first, then broadly. GET /client/usage shows which calls run how often; the header X-Tapinoma-Usage-Warning reports low credit.

What to watch out for

• Set an `Idempotency-Key` on every POST. A second click on „Check“ must not trigger a second check; X-Tapinoma-Idempotent-Replay marks a replayed answer. Exception: POST /client/partner-workspaces issues the key once — after a timeout, reconcile via externalReference instead of creating again.
• Do not fill empty fields. If name or listPrice is null, the field in the job stays empty. A plausible list price from another source is more dangerous than a visible gap.
• Store the `tapiId` on the vehicle. It is stable and keeps GET /vehicles/{tapiId} linked to the previously paid VIN workflow on the next visit.
• Never hand the key to the browser. Not even for the redirect: your server calls POST /vin/redirect-sessions, the browser only receives the redirectUrl.
• Set rate limits per workshop. PUT /client/users/{clientId}/rate-limits limits per user, key or endpoint, so one business cannot use up the others' quota.
• Have the result checked, not passed through. fits=true is a reconciliation, not a fitting promise; an aftermarket reference is a search candidate. The software shows provenance and confidence, the workshop decides.

What the API does not do

It does not replace the manufacturer's parts catalogue and gives no fitting instructions. POST /vin/cart-check reconciles whether an OE number fits the vehicle; availability and price the call does not say — GET /parts/oe/{oeNumber}/price delivers an indicative evaluation, not a price guarantee. The recall reconciliation is a working aid at model-line level, not an official statement. No keeper is identified anywhere, no expert report is produced anywhere. For provider 1 the vehicle reconciliation runs exclusively through the redirect into the tapinoma interface; a third-party system cannot call it directly. What no source substantiates stays empty: an empty result is not an error but the result. What is sold is the reconciliation, not a data set; checking and using the results lies with the workshop.