Integration reference

Connect your systems. Keep the context.

This is the target integration architecture: console and API would apply the same rules. The endpoints described are not available on this website; their implementation and validation are agreed for each deployment.

  • ERP / Management Catalogs and lots
  • Quality / Compliance Signals and reports
  • Production / Labelling Printing and activation
  • Analytics Exports and reports
Conceptual integration diagram

Connection scope

Define. Connect. Validate.

  1. Agree the scope

    Data, responsibilities and permissions for each system.

  2. Connect operations

    Issuance and printing; activation when production is complete.

  3. Validate with evidence

    Readability, data and change-traceability checks.

Issue and activate

There are two steps because a factory works that way: codes are printed while production runs, and the lot’s definitive data only exists once the run ends.

Combined issuance and activation is contemplated only for a product whose production has finished, with printing confirmed and a complete lot and expiry record. Knowing those fields in advance does not permit activating units before production ends.

Issuing requires an idempotency header. A retry after a dropped connection does not produce a second run or spend the balance twice: it returns exactly the same issuance.

Proposed endpoints of the issuance cycle
POST /v1/issuances
     Generates identifiers for a product. Combined activation only
     with production finished, printing confirmed and a complete record.

POST /v1/issuances/{id}/activate
     Completes the record, which is what activates the codes. Four modes:
     declared range · scanned bounds · scan session · whole issuance

POST /v1/issuances/{id}/reassign
     Corrects the record of a range. It stays in the audit trail.

GET  /v1/issuances/{id}/labels
     Paginated download, or streaming for large runs.

Four ways to activate, ordered by certainty

Matching codes to a lot assumes the plant consumed the labels in order, and the physical world mixes rolls up. Hence more than one method.

  • Declared range

    You declare from where to where, with its lot and expiry. It works in plants with orderly consumption, under declared responsibility.

  • Scanned bounds · recommended

    Opening the run, the label of the first unit is read; closing it, the last one. The system derives the range actually observed and absorbs offsets and waste.

  • Scan session

    A session is opened for a lot and every code read during it is assigned to it. Assignment stops being an assumption and becomes an observation.

  • Sampling audit

    As a production-closure check, random units from each lot are scanned and the assigned record is compared with what is printed. Differences are left for the responsible person to review.

Correcting the record is free while the range has no public lookups: the mistake stays in the factory. Once it has been looked up in the market, the correction needs approval and opens a case, because the passport already showed data and the change has to be defensible.

Look up and bind

In serial mode, a serial repeated within the same product, or a second attempt to bind the same code, is rejected and raises a signal. The reverse index from serial to code is what later enables a per-unit warranty or a surgical recall.

The full specification is published as OpenAPI, and the version lives in the path: what works today keeps working when the next one appears.

Lookup and serial-mode endpoints
GET  /v1/verify/{code}
     Public lookup: status and passport. Anonymous, rate-limited.
     Planned for integrators: pharmacies and oversight teams.

GET  /v1/labels/{code}
     Looks up one of your own labels, in more detail than the public one.

POST /v1/labels/bind
     Serial mode: binds a code to the manufacturer’s serial, 1 to 1.

POST /v1/labels/void
     Voids ranges, with a reason. It stays in the audit trail.

Webhooks: issuance.issued · label.alert

How the result arrives

Issuance receipt
Issuance, range, record state, your own reference and a digest of the content
The digest lets you check the integrity of what the print shop received.
Your own reference
Whatever order or run number you use
It travels with the issuance and is filterable: reconciling with your management system is direct.
Download
CSV · XLSX · images · imposition PDF
Every download stays in the audit trail: labels are unit identities.
Production line
Native thermal-printer language
To label at machine speed, without going through a PDF.
Visible sequence
One running number per product
Internally the code carries issuance and position; on screen everything speaks in a sequence that never repeats.

Identities and permissions

An issuer’s account authorises the creation of unit identities. The asymmetry with the public is deliberate.

  • The public has no account

    Looking up and preparing a local report require no account. This website lets you download the code, type and description, without email or location. It does not send the report or change the registry; hand it to the responsible organization.

  • The console requires a second factor

    Corporate email and password with a mandatory second factor, and an optional passkey for anyone who wants phishing resistance. Nobody gets in with a password alone.

  • No social sign-in

    An issuer’s identity is corporate. A personal email address should not control an account that issues.

  • Machine identity

    Integrations use an API key with request signing, specific scopes and rotation. Revocable per key and per device.

What keeps working when something fails

An identification system cannot stop production or trade. That stops being an aspiration and becomes a design requirement.

  • Printing does not depend on the connection

    The range is downloaded once and the local process feeds the printer, with its own queue and consumption reporting when it reconnects.

  • Public lookup and issuance are separate planes

    The lookup has to keep answering even while issuance is under maintenance. They do not share a path.

  • Fail open on reads, fail closed on writes

    If the rate limiter degrades, the lookup is served. Writes and authentication, by contrast, fail closed.

Before you integrate

The identifier format and the print specifications are in the label reference. If you want to understand why the design makes these calls, the precedents page walks through the systems that tried it first.

See the label and the code Why this design