ERP integration: issue passports at end of line

The shape of the integration

1. 1

   Product released in the ERP

   Create or update the battery model with its model-level data points. Store the returned model id on the material master.

2. 2

   Model passport-ready?

   Check the missing-field analysis and upload the EU Declaration of Conformity. Publishing is blocked until the model is complete.

3. 3

   Batch leaves the line

   Create one battery per serial with POST /items/batch, keyed by an idempotency key derived from the production order. Store each returned identifier against its serial.

4. 4

   Publish

   Publish the batch’s passports with POST /passports/publish; handle per-row failures.

5. 5

   Print

   Fetch each QR code (qr.svg) for the label, or print the qrResolverUrl with your own label software.

1. Mirror the model

Map ERP characteristics to the API field names in the field catalogue; GET /field-catalog gives you the same table as data, including which fields your category requires. Before creating, validate:

curl -X POST "https://dppapi-production.up.railway.app/v1/models/validate" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-d '{"category": "LMT","name": "Cargo 48V 15Ah","capacityKwh": 0.72,"chemistry": "Lithium-ion NMC","fields": {"manufacturerName": "Example Batteries GmbH","modelDesignation": "C48-15","weightKg": 4.2,"ratedCapacity": 15}}'

Then create the model once, and on later material-master changes PATCH only the changed fields — the API merges them.

2. Attach the declaration of conformity

curl -X POST "https://dppapi-production.up.railway.app/v1/models/cm1q8x2k40003l70f9a8s7d6e/documents" \-H "Authorization: Bearer $DPP_API_KEY" \-F "type=EU Declaration of Conformity" \-F "file=@declaration.pdf;type=application/pdf"

3. Issue passports at end of line

When a production order is confirmed, send its serials as rows. The idempotency key ties the request to the order line, so a connector restart cannot issue the batch twice — and identifiers, once printed, can never be withdrawn.

curl -X POST "https://dppapi-production.up.railway.app/v1/items/batch" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: po-4500012345-line-10" \-d '{"modelId": "cm1q8x2k40003l70f9a8s7d6e","placeOfManufacture": "Stuttgart, Germany","dateOfManufacture": "2027-01-15","rows": [{"serialNumber": "SN-000481"},{"serialNumber": "SN-000482"},{"serialNumber": "SN-000483"}]}'

The response lists every battery with its uniqueIdentifier and passport.id. Write both back to the serial-number record in the ERP — they are the keys for everything that follows. Batches over 1,000 serials are split into several requests, each with its own key.

Measured values at placing on the market

Annex XIII 4(a) asks for values measured per battery when it is placed on the market — measured capacity, internal resistance, power. If your end-of-line tester produces them, create batteries one at a time with POST /items and put them in fields (measuredCapacityAtPlacing, measuredResistanceAtPlacing, powerAtPlacing, …).

4. Publish

curl -X POST "https://dppapi-production.up.railway.app/v1/passports/publish" \-H "Authorization: Bearer $DPP_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: publish-po-4500012345-line-10" \-d '{"ids": ["cm1q8y0bq0006l70fx9y8z7w6","cm1q8y0bq0008l70fa1b2c3d4"]}'

A 207 means some rows did not publish. missing_place_of_manufacture and model_incomplete are data problems to fix in the ERP and resend; ceased should never happen on fresh batteries and deserves an alert.

5. Labels

curl "https://dppapi-production.up.railway.app/v1/passports/cm1q8y0bq0006l70fx9y8z7w6/qr.svg" \-H "Authorization: Bearer $DPP_API_KEY"

Go-live checklist

• Live key with only the scopes the connector needs; test key in CI.
• Idempotency keys derived from ERP document numbers on every create and publish.
• Identifiers and passport ids written back to the serial records.
• Per-row 207 failures routed to a work queue, not swallowed.
• request_id logged with every error.
• Webhook for passport.published if downstream systems need to know.