Skip to content

Product passports

QRalto Product Passports maintain product/model information and optionally issue a distinct digital identity for each physical unit. All management routes are tenant-isolated and use the existing experience:* and analytics:read authorization policies.

Management API

Base route: /api/v1/product-passports

Method Route Policy Purpose
GET /api/v1/product-passports experience:read List or search passports.
GET /api/v1/product-passports/{id} experience:read Read the passport workspace and batch summaries.
POST /api/v1/product-passports experience:write Create a draft passport and paused managed Dynamic QR.
PUT /api/v1/product-passports/{id} experience:write Update product facts and branding.
PUT /api/v1/product-passports/{id}/status experience:write Publish or pause the passport and managed QR together.
DELETE /api/v1/product-passports/{id} experience:delete Soft-delete the passport and disable public identities.
POST /api/v1/product-passports/{id}/batches experience:write Queue 1–100,000 serialized identities.
GET /api/v1/product-passports/{id}/units experience:read Page and search serialized units.
PUT /api/v1/product-passports/{id}/units/{unitId} experience:write Set identity/lifecycle state and warranty dates.
POST /api/v1/product-passports/{id}/units/{unitId}/lifecycle experience:write Append a public or internal lifecycle event.
GET /api/v1/product-passports/{id}/units.csv?batchId={batchId} experience:read Download one completed batch for a packaging system.
GET /api/v1/product-passports/{id}/units/{unitId}/qr.svg experience:read Render the unit carrier as SVG; use .png for PNG.
GET /api/v1/product-passports/{id}/analytics analytics:read Read Hour/Day first, repeat, and attention-signal buckets.

The anonymous model and unit read APIs are /api/v1/public/products/model/{slug} and /api/v1/public/products/{token}. Physical carriers use /p/{token} on the configured scanner domain so QRalto can validate the host, enforce plan state, record the scan, and redirect to the mobile public passport.

Product detail and public responses include revisionNumber, currentRevisionHash, and a bounded revisions collection. Public revision items contain the version, summary, changed field names, timestamps and hashes; full historical snapshots remain an authorized storage concern and are not returned anonymously.

Model responses use ETag: "{currentRevisionHash}" and require revalidation. Clients should send If-None-Match and accept 304 Not Modified. Unit reads are no-store; never persist a recognized/attention result as durable authenticity evidence.

Batch and identity rules

  • A batch has an immutable code, serial prefix, starting number, and quantity.
  • Prefix/number ranges cannot overlap within a passport.
  • A leased worker issues at most 1,000 units per transaction and resumes after interruption.
  • Public tokens contain 144 random bits and do not reveal sequence numbers.
  • Packaging exports are deliberately batch-scoped, keeping a download bounded even when a workspace owns millions of identities.
  • Active, Suspended, Recalled, and Revoked are digital-record states—not proof that a physical label was not copied or moved.
  • Concurrent model updates use SQL row-version protection. A stale editor receives a conflict and must reload before it can create the next revision.
  • Product revisions are append-only through AppDbContext and hash-link to the prior revision. The database operator remains part of the trust boundary.

Events and consistency

Mutations write qralto.product-passport.changed.v1. Unit scans write qralto.product-identity.scanned.v1. Both use the SQL outbox and optional RabbitMQ transport. Product analytics are eventually consistent and isolated from ordinary campaign buckets. Consumers must de-duplicate by eventId.

Regulatory boundary

This API is lifecycle-oriented product identity infrastructure. It does not by itself establish EU Digital Product Passport compliance, certify manufacturer claims, provide an independent digital signature, or provide an unclonable physical authenticator. Define category-specific schemas, evidence, standards, access roles, retention, interoperability and conformity controls before regulated deployment.