AutoID print loop

Norruva creates the identity; the print layer (e.g. TSC) prints and encodes it; the outcome comes back per serial. Four legs, webhooks both ways — print execution stays the printer partner's job, Norruva stays the system of record for what was (and wasn't) printed.

The loop

POST /api/v2/carriers/batch          { "productId": "…", "count": 1000 }
     → 201 { allocated, serials[] }  → webhook carrier.generated
                                       ("codes ready" — eventData carries exportPath; no polling)
GET  /api/v2/carriers/export?productId=…
     → the print CSV: gtin, serial, digital_link, sgtin96_epc
       (digital_link IS the QR payload; sgtin96_epc feeds the RFID encoder)

…the print layer prints…

POST /api/v2/carriers/print-status
{ "results": [ { "serial": "…", "status": "printed", "deviceId": "PEX-2000-01" },
               { "serial": "…", "status": "failed",  "reason": "ribbon jam" } ] }
     → 200 { updated[], unknown[], printed[], failed[], reportedAt, events[] }
     → webhooks print.confirmed / print.failed

The endpoints

Semantics that matter

• Idempotent by construction. Outcomes land on the serialization record (metadata.print: status, reason, deviceId, reportedAt) and are replaced wholesale — a later re-print legitimately overwrites an earlier failure (last write wins, also within one request).
• A retry replays; it does not re-report. Because print controllers rarely send an Idempotency-Key, the endpoint derives one from the batch itself. Re-posting an identical batch returns the first response and fires no further webhooks, so a timed-out report is safe to retry without duplicating print.confirmed / print.failed for subscribers. The events[] counts in a replayed response describe the original call. Change any outcome in the batch and it hashes differently, so genuinely new results always execute.
• Unknown serials are reported, never dropped. Anything not found for your tenant comes back in unknown[] with a 200 — the known outcomes still commit.
• Aggregate events, not per-serial spam. One print.confirmed and/or one print.failed delivery per request, each carrying the serial list (+ per-serial failures[] reasons on the failed event) — a 10k-label run is 2 deliveries, not 10k.
• Webhook dispatch failures never fail the call. The outcome is already durably recorded; events[] in the response tells you what was actually notified.

Report outcomes — example

curl -X POST "$BASE/api/v2/carriers/print-status" \
  -H "Authorization: Bearer $TSC_KEY" -H "Content-Type: application/json" \
  -d '{ "results": [
        { "serial": "100001", "status": "printed", "deviceId": "PEX-2000-01" },
        { "serial": "100002", "status": "failed",  "reason": "ribbon jam" } ] }'

{ "updated": ["100001", "100002"], "unknown": [],
  "printed": ["100001"], "failed": ["100002"],
  "reportedAt": "2026-07-22T17:20:00.000Z",
  "events": [ { "type": "print.confirmed", "webhooksNotified": 1 },
              { "type": "print.failed",    "webhooksNotified": 1 } ] }

The re-print file

After outcomes are in, GET /carriers/export?productId=…&printState=failed returns exactly the serials that need another pass — same CSV columns, so the same file feeds the same print pipeline. printState=pending answers "what has the print layer not reported yet?" for reconciliation.

Tier 2 — orchestrated print jobs (AIDC)

The CSV loop above trusts the print layer to manage its own work. The print-job tier (/api/v2/aidc/*, F15) makes each label an orchestrated, evidence-carrying unit instead: Norruva issues a signed job for one allocated serial, an enrolled device claims it under a lease, reports each state transition with its evidence artifact, and the terminal outcome lands on the same metadata.print spine the CSV loop uses — so the export, the re-print file and the webhooks stay one truth whichever tier printed the label.

POST /api/v2/aidc/jobs                { "gtin": "…", "serial": "…" }   ← serial must be allocated
     → 201 signed envelope            (fails 422 unless the passport is readyToPrint)
POST /api/v2/aidc/jobs/claim          ← THE device pulls (no inbound port into the plant)
     → signed envelope + attempt_id + lease
POST /api/v2/aidc/jobs/{ref}/heartbeat   ← long run? extend the lease
POST /api/v2/aidc/jobs/{ref}/result   { "status": "RENDERED", "evidence": {…}, "attempt_id": "…" }
     …repeat per state…               SPOOL_SUBMITTED → PRINTED_ATTESTED → SCAN_VERIFIED → SEALED
     → SEALED: metadata.print=printed + EPCIS commissioning + print.confirmed
     → DEAD_LETTER (retries exhausted): metadata.print=failed → the re-print file

The job lifecycle — states are evidence-gated

The four client guarantees

• Lease. A crashed device's job is reclaimable the moment its lease expires — no human, no reaper on the happy path. Heartbeat to keep a long run.
• Attempt id. Every claim mints and PERSISTS a fresh attempt_id; a result from a superseded attempt is a 409 STALE_ATTEMPT, an expired envelope a 410.
• Idempotency. Send Idempotency-Key on results — the key is claimed inside the transition transaction, so a retry after a timeout replays instead of double-applying.
• Atomic outcomes. A terminal transition and the spine write (metadata.print) commit in ONE transaction — there is no window where the job says printed and the export says pending.

Two creation gates, both typed 422s: SERIAL_NOT_ALLOCATED (allocate via carriers/batch first — a job can never mint a serial) and PASSPORT_NOT_READY (the F6 readyToPrint gate: ≥ 1 anchored validation ∧ published; anchor via POST /passports/{id}/validations). Full endpoint reference: Print jobs & devices; operator walkthrough: Run a print device.