Label encoding guidance

What a label supplier needs from the platform before a symbol is put on a physical carrier: the exact bytes to encode, what the platform itself produces, what the resolver will accept back, and which facts the platform records rather than measures. The platform mints identity; printing, encoding and print-quality verification stay with the print layer.

What the symbol must encode

The symbol carries the digital_link value from GET /api/v2/carriers/export, verbatim.

• Encode the string exactly as exported: UTF-8, no GS1 Digital Link compression, no trailing slash added.
• Case is preserved. The serial (AI 21) is carried as exported, character for character.
• The product-scope CSV carries gtin, serial, digital_link, sgtin96_epc, allocation_id; the tenant-scope CSV carries gtin, serial, digital_link, sgtin96_epc, passport_id, epc_note, allocation_id. Parse by column name, never by position: the two scopes differ.
• digital_link is the QR payload; sgtin96_epc is the RFID payload. A row can carry a usable Digital Link and an empty EPC with an epc_note; treat the two carriers separately.

What the preview package produces

The Carrier Studio preview package renders the Digital Link as a QR symbol for handoff:

• Symbology QR, error correction level H, 768 px raster, 4 module quiet zone.
• PNG, JPEG and PDF derivatives of the same symbol, plus the SGTIN-96 EPC for the same serial.
• An identity that does not resolve publicly (every Test-workspace identity, because Test mode never publishes) is rendered with a visible band and a file suffix saying so; the clean artifact is only produced for a link that resolves.

The package mints no serial, writes no state and contacts no printer. It is a preview for handoff, not a production print stream.

What the resolver accepts

The public resolver accepts these GS1 Digital Link path forms:

• /01/{gtin14}/21/{serial}
• /01/{gtin14}/10/{lot}/21/{serial} (AI 10 is optional and comes before AI 21)
• /01/{gtin14} (trade item only)

The GTIN is check-digit validated and normalised to 14 digits, so a GTIN-8, GTIN-12 or GTIN-13 is left-zero-padded and both encodings resolve to the same trade item. The serial is case-sensitive: nothing on the resolver path upper-cases or lower-cases it. A browser or scanner client (Accept: text/html) is redirected to the passport page; a JSON client receives the resolved passport identifier and a Location header. An unpublished passport answers 404, which is why a Test-workspace identity does not resolve on a phone.

SGTIN-96 constraints

• The serial must be numeric, without leading zeros, and below 2³⁸. An alphanumeric serial has no SGTIN-96 encoding.
• The company prefix length must be an integer between 6 and 12 (the TDS partition table).
• That length comes from the GS1 licence, supplied as the GS1 Company Prefix on the company profile or as an explicit per-export companyPrefixLength. It is never guessed: a plausible 7 encodes a well-formed EPC that names a different company.

Human readable text

Printing the GTIN and the serial as text beneath the symbol is recommended. The platform does not compose the label, so the placement, typeface and size of that text are the print layer's choice.

Symbol quality is measured off platform

The platform performs no print-quality measurement. The ISO/IEC 15415 overall grade, the measuring aperture and the wavelength are measured by the partner's own verification device (ODV) and reported through POST /api/v2/carriers/quality, which records what is reported. aperture_pct and wavelength_nm are required alongside the grade, so a reported grade can be read back with its measurement setup. A reported grade below the held minimum for the declared target environments is refused with a 422 and nothing is persisted for that request. Two meanings of verified stay separate: the platform asserts only that a decoded payload equals the queued Digital Link; the symbol grade is the verifier's assertion.

RFID

The RFID payload is the sgtin96_epc column of the same export row. The air interface, the encoder command language and the tag commissioning sequence are not implemented by the platform; they belong to the print and encode partner. The export can be run as an EN 18219 section 5.5.2.1 commissioning run, which adds the identifier payload and the commissioning intent to every row; it writes no tag.

Device enrolment

Enrol printers and verifiers through POST /api/v2/devices (label, kind of label_printer, rfid_printer or verifier, connectMode, model, protocolLanguage, dpi). Binding an apiKeyId makes that credential device-bound, so claim, heartbeat and result calls on the print-job loop are attributed to the device; POST /api/v2/devices/{id}/status sets registered, active, disabled or retired, and disabled is the operational kill switch. The deviceId reported to carriers/print-status is a separate field: it is recorded as reported, and when it matches an enrolled device of your tenant the outcome is bound to that device and echoed in boundDevices; anything else is echoed in unknownDevices so a typo is visible.

Reporting outcomes

• POST /api/v2/carriers/print-status takes up to 1000 results per call; status is printed or failed, nothing else.
• Each serial appears once per request body; a repeated serial in one body is refused. A reprint is a separate request with its own attemptRef, recorded verbatim.
• printedAt is optional and is the moment the label left the printer as your device clocked it; when present it becomes the commissioning event time. reportedAt in the response is always the platform's receipt instant.
• reason, deviceId and evidenceRef are recorded as reported; evidenceRef is never dereferenced by the platform.
• Unknown serials come back in unknown[] with a 200. Retries of an identical batch are replayed, not re-executed. Outcomes are last-write-wins on the visible export; the append-only commissioning history is the record of every report.