{ "openapi": "3.1.0", "info": { "title": "OpenDPP Integration API", "version": "1.0.0", "summary": "Create, validate, seal and publish EU Digital Product Passports; serialize battery units; manage facilities, access grants and webhooks; resolve and verify passports publicly.", "description": "OpenDPP is a B2B platform for EU Digital Product Passports (DPPs), aligned with the ESPR (Regulation (EU) 2024/1781) data requirements and the EU Battery Regulation (Regulation (EU) 2023/1542). This specification documents the **public integration surface**: everything an external system needs to create, validate, seal, publish, resolve and verify passports.\n\n## Authentication\nAuthenticate with a tenant **API key** sent as a Bearer token: `Authorization: Bearer op_dpp_token_…`. Keys are created in the Client Console (Developers → API keys), are shown **once** at creation, carry a role plus optional narrowed permissions and optional expiry, and can be revoked at any time. API-key clients are exempt from CSRF requirements. Public endpoints (tagged **Public Resolution**, plus the public validators and the audit verifier) need no credentials.\n\n## Tenancy\nTenant identity is **token-bound** — it is derived from your API key, never from the request host. The same paths work on the apex host and on tenant workspace hosts (`https://.opendpp-node.eu`); when a workspace host is used, it must match the key's tenant (requests across workspaces are rejected with `403`).\n\n## Errors\nAuthenticated endpoints return `{ success: false, error, message }` (some omit `success`). ESPR metadata validation failures return the richer shape documented as **ValidationFailed** with per-field `errors[]`/`warnings[]` (localizable via `?lang=` or `Accept-Language`; 28 languages). Bulk endpoints report row-level problems as `errors: string[]`. Malformed JSON and query-string violations return Fastify's default `{ statusCode, code, error, message }` body.\n\n## Rate limits\nGlobal limit: **100 requests/min per IP** (higher for verified crawlers), with `x-ratelimit-*` response headers. Public passport resolution is additionally limited to **30 requests/min per IP** (no headers). The public validator is limited to **10 requests/min per IP**. Stay under these limits with client-side queueing; on `429`, back off and retry after the indicated window.\n\n## Sealing & verification\nPassport seals are **eIDAS advanced electronic seals** (ECDSA P-256 over a Merkle root of the passport content, optional RFC 3161 timestamp). Anyone can verify a seal — no account required. `POST /api/v1/audit/verify` recomputes every Merkle leaf from the submitted values, so it requires the unredacted document (caller-supplied redacted-leaf hashes are deliberately not trusted). Redacted documents remain verifiable **offline**: masked fields keep their true leaf hashes in `proof.redactedLeaves`, letting any verifier rebuild the sealed root without the privileged values.\n\n## Public access tiers\nPublic resolution endpoints serve **tiered** views of the same URL: the public tier for anonymous callers; a restricted tier for holders of legitimate-interest (`dpp_li_…`) or authority (`dpp_auth_…`) capability tokens (presented as a Bearer token or `?grant=` query parameter); and the owner tier for the issuing tenant's own credentials.\n\n## Webhooks\nSubscribe to passport lifecycle events (`passport.ingested`, `passport.sealed`, `passport.recalled`, or `*`). Deliveries are HMAC-SHA256-signed; see the **webhooks** section of this document for the exact signature scheme, retry schedule, and payloads.\n\nThis document is also served machine-readably at [`/openapi.json`](https://opendpp-node.eu/openapi.json) and [`/openapi.yaml`](https://opendpp-node.eu/openapi.yaml).", "contact": { "name": "OpenDPP", "url": "https://opendpp-node.eu/contact", "email": "support@opendpp-node.eu" }, "license": { "name": "Proprietary — © OpenDPP UAB. The specification may be used to build integrations and generate clients against the OpenDPP service.", "url": "https://opendpp-node.eu/security" } }, "servers": [ { "url": "https://opendpp-node.eu", "description": "Production (apex host)" }, { "url": "https://{workspace}.opendpp-node.eu", "description": "Tenant workspace host — same API; the host's workspace must match the API key's tenant.", "variables": { "workspace": { "default": "demo", "description": "Your workspace subdomain (the demo workspace hosts fictional sample data)." } } } ], "tags": [ { "name": "Passports", "description": "Create, validate, read, update, seal and manage the lifecycle of Digital Product Passports. Passport metadata is category-specific: machine-readable JSON Schemas are served live at `GET /api/v1/schemas/{category}` for textiles, batteries, electronics, chemicals and construction; the remaining categories (cosmetics, toys, iron-steel, aluminium) are validated by built-in rules — use the dry-run validators to check payloads for any category." }, { "name": "Economic Operators", "description": "Register and manage the economic operators (manufacturers/brands, identified by EORI or national registry id) that passports are issued on behalf of. Operators with passports are archived — never hard-deleted — to preserve passport resolvability (ESPR Art. 9(2))." }, { "name": "Battery Units", "description": "Per-unit battery serialization (real serials, GS1 AI 21) under a SKU-level passport, plus append-only telemetry events (state of health, charge cycles, status changes) per the EU Battery Regulation." }, { "name": "Facilities", "description": "Manufacturing facility master data, identified by GS1 GLN-13 (the Unique Facility Identifier). GLN, name, activity and country are public in passport documents; street addresses are never published." }, { "name": "Access Grants", "description": "Capability tokens implementing tiered access (Battery Regulation Art. 77(9) legitimate-interest access): issue, approve, deny and revoke `dpp_li_…` / `dpp_auth_…` tokens. Third parties request access via the hosted request page; granted tokens unlock restricted fields on the public resolution endpoints (Bearer or `?grant=`)." }, { "name": "Webhooks", "description": "Subscribe HTTPS endpoints to passport lifecycle events. Deliveries are HMAC-SHA256-signed POSTs with retry/backoff — see the webhooks section of this document for the signature scheme and payloads." }, { "name": "Traceability & Audit", "description": "UNTP/EPCIS supply-chain traceability events, lineage queries, and the public seal verifier. The verifier checks the cryptographic seal AND that the signing workspace is bound to the economic operator declared in the payload." }, { "name": "Public Resolution", "description": "Unauthenticated, content-negotiated passport resolution: GS1 Digital Link paths, passport and unit pages. One URL serves JSON-LD (default), an AAS environment (`Accept: application/aas+json`), or HTML (`Accept: text/html`). Tiered by optional credentials or grant tokens. Rate limit: 30 requests/min per IP." }, { "name": "Schemas & Vocabulary", "description": "Machine-readable contracts: per-category ESPR JSON Schemas, the W3C JSON-LD context, and the curated materials vocabulary." }, { "name": "QR Codes", "description": "Export GS1-Digital-Link QR codes (PNG/SVG, 128–2048 px, GS1 quiet zone) for passports and battery units." }, { "name": "eIDAS Keys", "description": "Tenant signing-key management. Keys are generated and held server-side in an encrypted vault; private key material is never returned by any endpoint." }, { "name": "Service", "description": "Service metadata and liveness." } ], "paths": { "/api/v1/passports/{passportId}/units": { "parameters": [ { "name": "passportId", "in": "path", "required": true, "description": "The SKU/type-level passport, addressed either by its UUID **or** by its caller-supplied `productId` (GTIN-14 / GRAI / SKU). The UUID lookup is tried first, then `productId` — both scoped to your tenant.", "schema": { "type": "string" }, "example": "09501101530003" } ], "post": { "operationId": "serializeBatteryUnits", "tags": [ "Battery Units" ], "summary": "Serialise individual battery units under a passport (bulk, up to 200)", "description": "Creates one or many **individual physical battery units** (Battery Reg. (EU) 2023/1542 Art. 77(2)) under a SKU/type-level passport. Send either a single unit object or `{\"units\": [...]}` with **at most 200 items** (if `units` is present and an array it is used; otherwise the whole body is treated as one unit).\n\n**Permission:** `battery:write`. Bearer API key (`op_dpp_token_…`) or session JWT; cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only serialise under passports of their own Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403).\n\n**Per-item validation (collected as plain-string errors, not a rejection of the whole batch):** `serialNumber` is trimmed then must match `^[A-Za-z0-9._-]{1,64}$` (GS1 AI-21 recommends ≤ 20 chars); `status` must be a valid unit status; `manufacturedAt` must be Date-parseable; duplicate `(passport, serialNumber)` pairs are skipped with *\"A unit with this serial already exists for this passport\"*. Each created unit gets a per-unit GS1 Digital Link URI `/{01|8003}/{productId}/21/{serialNumber}` carrying the **real physical serial** in AI-21.\n\n**Predecessor linkage (Art. 77(7) repurpose/remanufacture):** `predecessorUnitId` must reference an existing unit **in your tenant** (any passport). A recycled predecessor (`ceasedAt` set) is refused — its passport has ceased to exist (Art. 77(8)). (The check keys on `ceasedAt`, which only the events-route `RECYCLED` transition stamps — a unit merely *created* with status `RECYCLED` has no `ceasedAt` and is still accepted as a predecessor.) In one transaction the new unit is created, an append-only `STATUS_CHANGE` event (`{status, successorUnitId, successorSerial}` payload) is written to the predecessor, and the predecessor's status is set to `predecessorStatus` (default `REPURPOSED`; only `REPURPOSED|REMANUFACTURED|REUSED` allowed).\n\n**Partial success:** the response is **201 when at least one unit was created**; skipped items are listed in `errors`. If *every* item failed you get **400 `Serialisation Failed`** with the same string array. A `batteryunit.created` audit event and a tenant notification are emitted on success.\n\n**Rate limits:** global limiter only — 100 req/min per IP (`x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerializeBatteryUnitsRequest" }, "example": { "units": [ { "serialNumber": "BATT-2026-000451", "manufacturedAt": "2026-05-02T08:00:00.000Z" }, { "serialNumber": "BATT-2026-000452", "status": "IN_SERVICE", "predecessorUnitId": "5a1c9e7d-3b2f-4c8a-9e6d-7f0b1a2c3d4e", "predecessorStatus": "REMANUFACTURED" } ] } } } }, "responses": { "201": { "description": "At least one unit was serialised. `count` is the number actually created; when some items were skipped, `errors` lists one plain-English string per skipped item and `message` notes the skip count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerializeBatteryUnitsResponse" }, "example": { "success": true, "message": "Serialised 2 individual unit(s)", "count": 2, "units": [ { "id": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "serialNumber": "BATT-2026-000451", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "passportId": "4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "tenantId": "tenant-demo-opendpp", "manufacturedAt": "2026-05-02T08:00:00.000Z", "status": "IN_SERVICE", "ceasedAt": null, "predecessorUnitId": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" }, { "id": "2f6b0c1d-8e4a-4b7c-a93d-5e2f1a0b9c8d", "serialNumber": "BATT-2026-000452", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000452", "passportId": "4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "tenantId": "tenant-demo-opendpp", "manufacturedAt": null, "status": "IN_SERVICE", "ceasedAt": null, "predecessorUnitId": "5a1c9e7d-3b2f-4c8a-9e6d-7f0b1a2c3d4e", "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } ] } } } }, "400": { "description": "Three shapes: (1) standard `Bad Request` triple when the body is not a JSON object, the `units` array is empty, or more than 200 units are sent; (2) `Serialisation Failed` (`{success:false, error:\"Serialisation Failed\", errors: string[]}` — **no `message` field**) when *every* item in the batch failed per-item validation/creation; (3) a syntactically malformed JSON body is rejected by the framework before the handler runs, with Fastify's default `{statusCode:400, error:\"Bad Request\", message}` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/BatteryUnitSerialisationFailedError" }, { "$ref": "#/components/schemas/FastifyDefaultBadRequest" } ] }, "examples": { "badRequest": { "summary": "Batch-level rejection", "value": { "success": false, "error": "Bad Request", "message": "A single request may serialise at most 200 units" } }, "serialisationFailed": { "summary": "Every item failed", "value": { "success": false, "error": "Serialisation Failed", "errors": [ "Invalid serialNumber \"bad serial!\": must be 1-64 URL-safe characters ([A-Za-z0-9._-])", "[BATT-2026-000451] A unit with this serial already exists for this passport" ] } }, "malformedJson": { "summary": "Syntactically invalid JSON body (Fastify default body)", "value": { "statusCode": 400, "code": "FST_ERR_CTP_INVALID_JSON_BODY", "error": "Bad Request", "message": "Body is not valid JSON but content-type is set to 'application/json'" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "listBatteryUnits", "tags": [ "Battery Units" ], "summary": "List serialised battery units under a passport", "description": "Lists **all** serialised units of the passport, newest first (`createdAt` DESC). **Unpaginated** — the full set is returned in one response (no `page`/`limit`).\n\n**Permission:** `battery:read`. Operator-scoped credentials may only read passports of their own Economic Operator (403). Units are raw persisted rows (no Fastify response schema, nothing stripped).\n\n**Rate limits:** global limiter only — 100 req/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The passport's units. `productId` echoes the passport's caller-supplied identifier; `count` equals `units.length`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatteryUnitListResponse" }, "example": { "success": true, "count": 1, "productId": "09501101530003", "units": [ { "id": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "serialNumber": "BATT-2026-000451", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "passportId": "4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "tenantId": "tenant-demo-opendpp", "manufacturedAt": "2026-05-02T08:00:00.000Z", "status": "IN_SERVICE", "ceasedAt": null, "predecessorUnitId": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/units/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Battery unit UUID (tenant-scoped).", "schema": { "type": "string" }, "example": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a" } ], "get": { "operationId": "getBatteryUnit", "tags": [ "Battery Units" ], "summary": "Get one battery unit as JSON-LD with its dynamic-data history", "description": "Returns the unit as a **JSON-LD document** (`Content-Type: application/ld+json`) in the **privileged tenant view**: `currentState` (the latest telemetry snapshot) and `dynamicData` (the **500 most recent** events, newest first by `recordedAt`) are included; the public `restrictedData` marker is absent. The embedded `ofModel` is the SKU/type passport document rendered in the **owner (unredacted) variant** — legitimate-interest-tier metadata and owner-only keys are NOT masked, unlike the anonymous public document.\n\n**Caveat:** this authenticated endpoint does **not** load lineage relations, so `repurposedFrom` is always `null` and `successorUnits` is always `[]` here even when Art. 77(7) lineage exists; the public resolver view (`GET /unit/{id}`) does resolve them.\n\n**Permission:** `battery:read`. Operator-scoped credentials may only read units whose passport belongs to their Economic Operator (403).\n\n**Rate limits:** global limiter only — 100 req/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The unit's JSON-LD document (privileged view, telemetry included).", "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/BatteryUnitJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "BatteryUnit": "https://w3id.org/dpp#BatteryUnit", "serialNumber": "https://w3id.org/dpp#serialNumber", "ofModel": "https://w3id.org/dpp#ofModel", "currentState": "https://w3id.org/dpp#currentState", "dynamicData": "https://w3id.org/dpp#dynamicData", "stateOfHealth": "https://w3id.org/dpp#stateOfHealth", "cycleCount": "https://w3id.org/dpp#cycleCount", "restrictedData": "https://w3id.org/dpp#restrictedData", "repurposedFrom": "https://w3id.org/dpp#repurposedFrom", "successorUnits": "https://w3id.org/dpp#successorUnits" } ], "@type": "BatteryUnit", "@id": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "id": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "serialNumber": "BATT-2026-000451", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "status": "IN_SERVICE", "manufacturedAt": "2026-05-02T08:00:00.000Z", "repurposedFrom": null, "successorUnits": [], "ofModel": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "id": "4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/4c8e1d2a-6b3f-4a9e-8d57-0f1e2a3b4c5d", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-05-01T10:00:00.000Z", "updatedAt": "2026-06-01T10:00:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "operator-demo-opendpp", "name": "OpenDPP Demo Eco Industries (SAMPLE)", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": null, "metadata": { "category": "batteries", "originCountry": "PT" }, "category": "batteries", "originCountry": "PT" }, "currentState": { "stateOfHealth": 97.4, "cycleCount": 132, "remainingCapacityAh": 48.7, "temperatureC": 23.1, "recordedAt": "2026-06-11T16:20:00.000Z" }, "dynamicData": [ { "@type": "BatteryUnitEvent", "eventType": "SOH_MEASUREMENT", "stateOfHealth": 97.4, "cycleCount": 132, "remainingCapacityAh": 48.7, "temperatureC": 23.1, "payload": null, "recordedAt": "2026-06-11T16:20:00.000Z" } ], "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteBatteryUnit", "tags": [ "Battery Units" ], "summary": "Permanently delete a battery unit and its telemetry", "description": "**HARD delete** — permanently removes the unit row and **cascades all of its `BatteryUnitEvent` telemetry**. This is *not* a lifecycle/status transition: to record end-of-life semantics (decommissioned, waste, recycled — incl. the Art. 77(8) public 410 tombstone) append a telemetry event with a `status` instead (`POST /api/v1/units/{id}/events`). Deletion is intended for erroneous serialisations. A `batteryunit.deleted` audit event is written.\n\n**Permission:** `battery:write`. Cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only delete units whose passport belongs to their Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403).\n\n**Rate limits:** global limiter only — 100 req/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The unit and its events were permanently deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatteryUnitDeleteResponse" }, "example": { "success": true, "message": "Battery unit deleted." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/units/{id}/events": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Battery unit UUID (tenant-scoped).", "schema": { "type": "string" }, "example": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a" } ], "post": { "operationId": "recordBatteryUnitEvent", "tags": [ "Battery Units" ], "summary": "Append an immutable telemetry event to a battery unit", "description": "Appends one **append-only** per-unit dynamic-data record (Annex XIII / Art. 77: SoH, cycle count, remaining capacity, temperature, negative events). History is immutable — there is **no update or delete path** for events.\n\n**Permission:** `battery:write`. Cookie-session clients must send `X-CSRF-Token`. Operator-scoped credentials may only write to units whose passport belongs to their Economic Operator (403). Write operations pass subscription gating (402) and optional tenant MFA enforcement (403).\n\n**Validation (400 with the standard error triple):** `eventType` is required and must be one of `SOH_MEASUREMENT|CHARGE_CYCLE|STATUS_CHANGE|NEGATIVE_EVENT|OTHER`; `stateOfHealth` 0–100; `cycleCount` and `remainingCapacityAh` 0–9007199254740991; `temperatureC` −273.15–10000 (each may also be `null`/omitted); `status`, if present, must be a valid unit status; `recordedAt` must be Date-parseable (defaults to server time when omitted). `cycleCount` is truncated to an integer before persisting; a `payload` that is not an object or array is silently dropped (stored as `null`) — JSON **arrays** pass the server's `typeof` check and are persisted verbatim.\n\n**Status transition:** when `status` is present and differs from the unit's current status, the unit is updated **in the same transaction** as the event — this works with *any* `eventType`, though `STATUS_CHANGE` is the conventional carrier. Transitioning to **`RECYCLED`** (Art. 77(8)) additionally stamps `ceasedAt` (if not already set; never cleared), after which the public unit view becomes a 410 tombstone and the unit can no longer gain successor units. `status` itself is not locked afterwards — a later event may still set a different value — but `ceasedAt` persists, so the public 410 and the predecessor refusal are permanent.\n\n**Rate limits:** global limiter only — 100 req/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBatteryUnitEventRequest" }, "example": { "eventType": "SOH_MEASUREMENT", "stateOfHealth": 96.8, "cycleCount": 140, "remainingCapacityAh": 48.2, "temperatureC": 24.5, "payload": { "measuredBy": "BMS firmware 4.2.1" }, "recordedAt": "2026-06-12T09:41:00.000Z" } } } }, "responses": { "201": { "description": "Event appended (and, when `status` was supplied and differed, the unit's status transitioned in the same transaction).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBatteryUnitEventResponse" }, "example": { "success": true, "message": "Dynamic data recorded", "event": { "id": "7e5d3c1b-9a8f-4e6d-b2c4-1a0e9f8d7c6b", "batteryUnitId": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "tenantId": "tenant-demo-opendpp", "eventType": "SOH_MEASUREMENT", "stateOfHealth": 96.8, "cycleCount": 140, "remainingCapacityAh": 48.2, "temperatureC": 24.5, "payload": { "measuredBy": "BMS firmware 4.2.1" }, "recordedAt": "2026-06-12T09:41:00.000Z", "createdAt": "2026-06-12T09:41:05.000Z" } } } } }, "400": { "description": "Two shapes: (1) the standard error triple from handler validation — messages: `Request body must be a valid JSON object`; `eventType must be one of: SOH_MEASUREMENT, CHARGE_CYCLE, STATUS_CHANGE, NEGATIVE_EVENT, OTHER`; ` must be a number between and ` (stateOfHealth/cycleCount/remainingCapacityAh/temperatureC); `status must be one of: IN_SERVICE, DECOMMISSIONED, RECALLED, REPURPOSED, REMANUFACTURED, REUSED, WASTE, RECYCLED`; `recordedAt is not a valid date`. (2) A syntactically malformed JSON body is rejected by the framework before the handler runs, with Fastify's default `{statusCode:400, error:\"Bad Request\", message}` body.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FastifyDefaultBadRequest" } ] }, "examples": { "validation": { "summary": "Handler validation error (standard triple)", "value": { "success": false, "error": "Bad Request", "message": "stateOfHealth must be a number between 0 and 100" } }, "malformedJson": { "summary": "Syntactically invalid JSON body (Fastify default body)", "value": { "statusCode": 400, "code": "FST_ERR_CTP_INVALID_JSON_BODY", "error": "Bad Request", "message": "Body is not valid JSON but content-type is set to 'application/json'" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "The transaction failed. Handler-built body: `{success:false, error:\"Internal Server Error\", message:\"Failed to record dynamic data\"}` (error logged server-side, never echoed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Internal Server Error", "message": "Failed to record dynamic data" } } } } } }, "get": { "operationId": "listBatteryUnitEvents", "tags": [ "Battery Units" ], "summary": "List a battery unit's telemetry history (newest first, max 500)", "description": "Returns the unit's append-only dynamic-data history ordered by `recordedAt` DESC, **capped at the 500 most recent events**. There is no pagination — older events beyond the cap are not retrievable via this endpoint.\n\n**Permission:** `battery:read`. Operator-scoped credentials may only read units whose passport belongs to their Economic Operator (403). Events are raw persisted rows (no Fastify response schema, nothing stripped).\n\n**Rate limits:** global limiter only — 100 req/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The unit's telemetry history. `count` equals `events.length` (≤ 500); `serialNumber` echoes the unit's physical serial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatteryUnitEventListResponse" }, "example": { "success": true, "count": 2, "serialNumber": "BATT-2026-000451", "events": [ { "id": "7e5d3c1b-9a8f-4e6d-b2c4-1a0e9f8d7c6b", "batteryUnitId": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "tenantId": "tenant-demo-opendpp", "eventType": "SOH_MEASUREMENT", "stateOfHealth": 96.8, "cycleCount": 140, "remainingCapacityAh": 48.2, "temperatureC": 24.5, "payload": { "measuredBy": "BMS firmware 4.2.1" }, "recordedAt": "2026-06-12T09:41:00.000Z", "createdAt": "2026-06-12T09:41:05.000Z" }, { "id": "3a9c7e5d-1b2f-4c6a-8e0d-9f7b5a3c1d2e", "batteryUnitId": "9b2fa884-1f0c-4d6e-9a3b-2c7d85e41f6a", "tenantId": "tenant-demo-opendpp", "eventType": "CHARGE_CYCLE", "stateOfHealth": null, "cycleCount": 139, "remainingCapacityAh": null, "temperatureC": null, "payload": null, "recordedAt": "2026-06-11T16:20:00.000Z", "createdAt": "2026-06-11T16:20:02.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/facilities": { "post": { "operationId": "createFacility", "tags": [ "Facilities" ], "summary": "Register a facility (GS1 GLN)", "description": "Registers a manufacturing/processing facility as tenant-scoped master data, backing the Unique Facility Identifier (UFI, EN 18219). Passports reference facilities via `facilityId`.\n\n**Permission:** `facility:write`. Authenticate with a Bearer API key (`op_dpp_token_…`) or a session JWT; cookie-authenticated sessions must also send the `X-CSRF-Token` header (double-submit against the `opendpp_csrf` cookie) — Bearer clients are exempt. Write permissions are subscription-gated: a lapsed workspace subscription returns **402**.\n\n**GLN validation:** `gln` is trimmed, then must be exactly 13 digits with a valid GS1 modulo-10 check digit (same weighting algorithm as GTIN). The GLN is unique **platform-wide** (database unique constraint), so a duplicate returns **409** even if the existing facility belongs to another tenant.\n\n**Country:** `country` must match `^[A-Za-z]{2}$` after trimming and is stored uppercased.\n\n**Operator binding:** if `operatorId` is supplied (non-empty), that Economic Operator must be bound to your tenant workspace, otherwise **403**. An empty/whitespace `operatorId` is stored as `null`. Requests authenticated with an **operator-scoped API key** may only attach facilities to their own operator: a mismatched `operatorId` returns **403**, and when omitted the key's operator id is applied automatically.\n\n`activity`, `streetAddress`, `city` and `postalCode` are trimmed; empty/whitespace values are stored as `null`.\n\n**Public/privileged field split:** the public **JSON-LD** passport document exposes `id`, `gln`, `name`, `activity` and `country` of a linked facility; the public **AAS** export emits only the GLN, name and country (`manufacturingFacilityGln` / `manufacturingFacilityName` / `manufacturingFacilityCountry`, plus the GLN as a `urn:gs1:gln:` global asset reference) — the facility `id` and `activity` are never emitted in AAS. `streetAddress`, `city` and `postalCode` are owner-only in both formats. This endpoint returns the full row to you as the owner.\n\nEmits a `facility.created` audit event and an in-app notification.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityCreateRequest" }, "example": { "gln": "0950110153014", "name": "Munich Cell Assembly Plant", "activity": "Cell assembly", "streetAddress": "Werkstrasse 12", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } } } }, "responses": { "201": { "description": "Facility registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityCreatedEnvelope" }, "example": { "success": true, "message": "Facility registered successfully", "facility": { "id": "9b2fa884-5b6e-4c0a-9f3d-2e7c1a8d4b61", "gln": "0950110153014", "name": "Munich Cell Assembly Plant", "activity": "Cell assembly", "streetAddress": "Werkstrasse 12", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b", "tenantId": "7c3e9a12-4b5d-4f6e-8a9b-1c2d3e4f5a6b", "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } } } } }, "400": { "description": "Invalid request body. Checked in order: body must be a JSON object; `gln` must be a 13-digit GS1 GLN with a valid mod-10 check digit; `name` must be a non-empty string; `country` must be a 2-letter ISO code. Note: a syntactically malformed JSON body is rejected earlier by the JSON parser with the default error shape (`{\"statusCode\": 400, \"error\": \"Bad Request\", \"message\": }` — no `code` key), not this envelope; an empty body parses to `{}` and fails the `gln` check with this envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "nonObjectBody": { "value": { "success": false, "error": "Bad Request", "message": "Request body must be a valid JSON object" } }, "invalidGln": { "value": { "success": false, "error": "Bad Request", "message": "gln must be a valid GS1 Global Location Number (13 digits with a valid modulo-10 check digit)" } }, "invalidName": { "value": { "success": false, "error": "Bad Request", "message": "name must be a non-empty string" } }, "invalidCountry": { "value": { "success": false, "error": "Bad Request", "message": "country must be a 2-letter ISO country code" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Forbidden. Route-specific causes: an operator-scoped API key supplied an `operatorId` other than its own (`Your access is restricted to Economic Operator: `); or the supplied `operatorId` is not bound to your tenant workspace. Auth-layer causes also land here: insufficient permission (`facility:write`), missing/invalid CSRF token on a cookie session, cross-tenant subdomain mismatch, or MFA required when enforced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "operatorScopeRestricted": { "value": { "success": false, "error": "Forbidden", "message": "Your access is restricted to Economic Operator: 4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } }, "operatorNotBound": { "value": { "success": false, "error": "Forbidden", "message": "The Economic Operator with ID 4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b is not bound to your Tenant workspace." } }, "insufficientPermission": { "value": { "success": false, "error": "Forbidden", "message": "Insufficient permissions. Required: \"facility:write\"." } } } } } }, "409": { "description": "A facility with this GLN is already registered. The GLN unique constraint is platform-wide, so the conflict can be caused by a facility owned by another tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Conflict", "message": "A facility with GLN 0950110153014 is already registered." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Internal error (standard envelope). This route's catch block returns message `Failed to register facility` for unexpected database errors; a failure inside the auth layer returns message `Authentication verification failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "createFailed": { "summary": "Unexpected database error in the create handler", "value": { "success": false, "error": "Internal Server Error", "message": "Failed to register facility" } }, "authLayer": { "summary": "Failure inside the auth middleware", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } }, "get": { "operationId": "listFacilities", "tags": [ "Facilities" ], "summary": "List facilities in the tenant workspace", "description": "Lists all facilities registered under your tenant workspace, sorted by `createdAt` descending. **Unpaginated** — the full set is returned with a `count`.\n\n**Permission:** `facility:read` (Bearer API key or session JWT/cookie).\n\n**Operator-scoped keys:** when authenticated with an API key scoped to an Economic Operator, the list contains only facilities whose `operatorId` equals the key's operator — facilities with no operator (`operatorId: null`) are **excluded** from the list (they remain readable individually via `GET /api/v1/facilities/{id}`).\n\nThe full row is returned to the owner, including the privileged address fields (`streetAddress`, `city`, `postalCode`) that public passport documents never expose (owner-only in JSON-LD; never emitted in AAS).\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Facility list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityListEnvelope" }, "example": { "success": true, "count": 2, "facilities": [ { "id": "9b2fa884-5b6e-4c0a-9f3d-2e7c1a8d4b61", "gln": "0950110153014", "name": "Munich Cell Assembly Plant", "activity": "Cell assembly", "streetAddress": "Werkstrasse 12", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b", "tenantId": "7c3e9a12-4b5d-4f6e-8a9b-1c2d3e4f5a6b", "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" }, { "id": "3d8c1f27-6a4b-4e9d-a2c8-5b7e9f0a1c3d", "gln": "0950110153021", "name": "Rotterdam Recycling Hub", "activity": "Recycling", "streetAddress": null, "city": null, "postalCode": null, "country": "NL", "operatorId": null, "tenantId": "7c3e9a12-4b5d-4f6e-8a9b-1c2d3e4f5a6b", "createdAt": "2026-06-10T14:05:12.000Z", "updatedAt": "2026-06-10T14:05:12.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/facilities/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Facility id (UUID, as returned at registration). Non-existent or other-tenant ids return 404.", "schema": { "type": "string" } } ], "get": { "operationId": "getFacility", "tags": [ "Facilities" ], "summary": "Get a single facility", "description": "Fetches one facility by id, scoped to your tenant workspace.\n\n**Permission:** `facility:read`.\n\n**Operator-scoped keys:** if the facility belongs to a *different* Economic Operator than the key's scope, the response is **403**. Facilities with no operator (`operatorId: null`) **are** readable by operator-scoped keys here, even though they are excluded from the list endpoint.\n\nReturns the full row including the privileged address fields (`streetAddress`, `city`, `postalCode`) that public passport documents never expose. (Public exposure of a linked facility: the JSON-LD document shows `id`/`gln`/`name`/`activity`/`country`; the AAS export only the GLN, name and country.)\n\n**404 body:** standard envelope with message `Facility not found under your Tenant workspace`.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Facility found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityEnvelope" }, "example": { "success": true, "facility": { "id": "9b2fa884-5b6e-4c0a-9f3d-2e7c1a8d4b61", "gln": "0950110153014", "name": "Munich Cell Assembly Plant", "activity": "Cell assembly", "streetAddress": "Werkstrasse 12", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b", "tenantId": "7c3e9a12-4b5d-4f6e-8a9b-1c2d3e4f5a6b", "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden. Route-specific cause: the request used an operator-scoped API key and the facility belongs to a different Economic Operator. Auth-layer causes (insufficient `facility:read` permission, cross-tenant subdomain mismatch) also land here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Forbidden", "message": "Your access is restricted to Economic Operator: 4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateFacility", "tags": [ "Facilities" ], "summary": "Update facility master data (GLN is immutable)", "description": "Partially updates a facility's master data. **The GLN itself is immutable** — it is the resolvable UFI identifier; a `gln` key in the body is silently ignored (as is `operatorId` — the operator binding cannot be changed here).\n\n**Permission:** `facility:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed).\n\n**Field semantics (all optional):**\n- `name` — applied only when a non-empty string; an empty/whitespace or non-string value is silently ignored (`name` can never be cleared).\n- `activity`, `streetAddress`, `city`, `postalCode` — applied whenever the key is *present* in the body: the value is stringified and trimmed; anything that trims to empty (`null`, `\"\"`, or a whitespace-only string) **clears the field to null** — the same normalization as POST.\n- `country` — when present as a string it must match `^[A-Za-z]{2}$` (else **400**) and is stored uppercased; a non-string value is silently ignored.\n\nAn empty body (or one with no recognized fields) is accepted: the response is **200** with the otherwise-unchanged row, though `updatedAt` is still bumped.\n\n**Operator-scoped keys:** updating a facility that belongs to a different Economic Operator returns **403**; facilities with `operatorId: null` are updatable.\n\nEmits a `facility.updated` audit event recording the changed fields.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityUpdateRequest" }, "example": { "name": "Munich Cell Assembly Plant — Hall B", "activity": "Final manufacturing", "streetAddress": "Werkstrasse 14", "country": "DE" } } } }, "responses": { "200": { "description": "Updated facility (full row).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityEnvelope" }, "example": { "success": true, "facility": { "id": "9b2fa884-5b6e-4c0a-9f3d-2e7c1a8d4b61", "gln": "0950110153014", "name": "Munich Cell Assembly Plant — Hall B", "activity": "Final manufacturing", "streetAddress": "Werkstrasse 14", "city": "Munich", "postalCode": "80331", "country": "DE", "operatorId": "4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b", "tenantId": "7c3e9a12-4b5d-4f6e-8a9b-1c2d3e4f5a6b", "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T10:15:30.000Z" } } } } }, "400": { "description": "`country` was present as a string but is not a 2-letter ISO code. (This is the only body validation that errors; other invalid fields are silently ignored.) Note: a syntactically malformed JSON body is rejected earlier by Fastify's content-type parser with its **default** error shape (`{\"statusCode\": 400, \"code\": \"FST_ERR_CTP_…\", \"error\": \"Bad Request\", \"message\": …}`), not this envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "country must be a 2-letter ISO country code" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Forbidden. Route-specific cause: the request used an operator-scoped API key and the facility belongs to a different Economic Operator. Auth-layer causes (insufficient `facility:write` permission, missing/invalid CSRF token on a cookie session, cross-tenant mismatch, MFA when enforced) also land here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "operatorScopeRestricted": { "value": { "success": false, "error": "Forbidden", "message": "Your access is restricted to Economic Operator: 4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } }, "insufficientPermission": { "value": { "success": false, "error": "Forbidden", "message": "Insufficient permissions. Required: \"facility:write\"." } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteFacility", "tags": [ "Facilities" ], "summary": "Delete a facility (passports are unlinked, never deleted)", "description": "Removes the facility master-data row. **Passports are never deleted by this operation**: `Passport.facilityId` is a `SET NULL` foreign key, so any passports referencing the facility simply lose their UFI link (`facilityId` becomes `null`) and remain fully intact and publicly resolvable.\n\n**Permission:** `facility:write`. Cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated (**402** when lapsed).\n\n**Operator-scoped keys:** deleting a facility that belongs to a different Economic Operator returns **403**; facilities with `operatorId: null` are deletable.\n\nEmits a `facility.deleted` audit event and an in-app notification. **404 body:** standard envelope with message `Facility not found under your Tenant workspace`.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Facility deleted. Minimal envelope — no `message`, no `facility`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacilityDeletedEnvelope" }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Forbidden. Route-specific cause: the request used an operator-scoped API key and the facility belongs to a different Economic Operator. Auth-layer causes (insufficient `facility:write` permission, missing/invalid CSRF token on a cookie session, cross-tenant mismatch, MFA when enforced) also land here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Forbidden", "message": "Your access is restricted to Economic Operator: 4f6d2c1e-8a9b-4d3e-b7c5-0a1f2e3d4c5b" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/grants": { "get": { "operationId": "listGrants", "tags": [ "Access Grants" ], "summary": "List access grants and pending access requests", "description": "Lists the workspace's access grants — capability-token grants for the Battery Regulation's restricted data tiers (Reg. (EU) 2023/1542 Art. 77(9), Annex XIII(2)–(4)) — including undecided third-party access **requests** (`status: PENDING`, `issuerType: REQUEST`) submitted via the hosted request-access page.\n\n**Permission:** `grant:read`. **Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).\n\nReturns at most the **500** most relevant rows (no pagination parameters), grouped by `status` ascending (alphabetical: `ACTIVE`, `DENIED`, `PENDING`, `REVOKED`) and newest-first within each group. `AUTHORITY` grants (platform-issued market-surveillance access) are listed for transparency but are not tenant-revocable (`revocable: false`). Raw capability tokens are never included — only issuance/approval responses contain them, once.\n\nNote: the response envelope has **no** `success` field — it is a bare `{ grants: [...] }` object.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The workspace's grants and requests (most recent 500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantListResponse" }, "example": { "grants": [ { "id": "9b2fa884-3c1d-4e8a-9f27-5b06c8d41a72", "status": "ACTIVE", "kind": "LEGITIMATE_INTEREST", "granteeName": "Dr. Elena Varga", "granteeEmail": "e.varga@inspection-example.eu", "organization": "EU Battery Inspection Services", "purpose": "State-of-health verification for second-life suitability assessment under Art. 77(9).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "TENANT", "issuerEmail": "admin@example.opendpp-node.eu", "decidedAt": null, "decidedBy": null, "expiresAt": "2026-09-12T09:41:00.000Z", "revokedAt": null, "lastUsedAt": "2026-06-12T10:02:14.000Z", "useCount": 3, "createdAt": "2026-06-12T09:41:00.000Z", "revocable": true }, { "id": "c5d8e1f4-7a2b-4c9d-8e3f-6a1b2c3d4e5f", "status": "PENDING", "kind": "LEGITIMATE_INTEREST", "granteeName": "Marta Keller", "granteeEmail": "m.keller@recycler-example.eu", "organization": "Circular Battery Recycling GmbH", "purpose": "Assessing remaining capacity before acquisition for repurposing (Art. 77(9)).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "REQUEST", "issuerEmail": null, "decidedAt": null, "decidedBy": null, "expiresAt": "2026-09-10T08:15:30.000Z", "revokedAt": null, "lastUsedAt": null, "useCount": 0, "createdAt": "2026-06-12T08:15:30.000Z", "revocable": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createGrant", "tags": [ "Access Grants" ], "summary": "Issue a legitimate-interest access grant directly", "description": "Directly issues an `ACTIVE` legitimate-interest access grant (no pending request involved) and mints its capability token. The raw token (`dpp_li_` + 32 hex characters) is returned **once** in this response; only its SHA-256 hash is stored. The grantee presents it to the public resolution endpoints as `Authorization: Bearer dpp_li_…` or `?grant=dpp_li_…` to unlock the restricted (tier-2 / per-unit) data of the granted scope.\n\n**Permission:** `grant:write` (write operations are subject to subscription gating, so 402 is possible). Cookie-session clients must send the `X-CSRF-Token` header; Bearer clients are exempt. On workspaces that enforce multi-factor authentication, user sessions that did not authenticate with a second factor receive 403 on writes (API-key clients are exempt). **Rate limit:** global limiter, 100 requests/min per IP.\n\nScope semantics:\n- `UNIT` — `batteryUnitId` is required; the unit must belong to this workspace. The unit's parent `passportId` is recorded on the grant.\n- `PASSPORT` — `passportId` is required; the passport must belong to this workspace and must not be a `DRAFT` (drafts return 404).\n- `TENANT` — workspace-wide; no target id needed.\n\n`expiresAt` is required, must be in the future, and at most **366 days** out. This endpoint always mints `kind: LEGITIMATE_INTEREST` — `AUTHORITY` (`dpp_auth_…`) grants are platform-issued only and cannot be created here. The issuance is audited as `grant.issued`.\n\nString fields longer than their documented maximum are **silently truncated**, not rejected; unknown fields are ignored.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrantRequest" }, "example": { "granteeName": "Dr. Elena Varga", "granteeEmail": "e.varga@inspection-example.eu", "organization": "EU Battery Inspection Services", "purpose": "State-of-health verification for second-life suitability assessment under Art. 77(9).", "scopeType": "UNIT", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "expiresAt": "2026-09-12T09:41:00.000Z" } } } }, "responses": { "201": { "description": "Grant issued. `token` is the raw capability token — shown only here, store it now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantIssuedResponse" }, "example": { "success": true, "grant": { "id": "9b2fa884-3c1d-4e8a-9f27-5b06c8d41a72", "status": "ACTIVE", "kind": "LEGITIMATE_INTEREST", "granteeName": "Dr. Elena Varga", "granteeEmail": "e.varga@inspection-example.eu", "organization": "EU Battery Inspection Services", "purpose": "State-of-health verification for second-life suitability assessment under Art. 77(9).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "TENANT", "issuerEmail": "admin@example.opendpp-node.eu", "decidedAt": null, "decidedBy": null, "expiresAt": "2026-09-12T09:41:00.000Z", "revokedAt": null, "lastUsedAt": null, "useCount": 0, "createdAt": "2026-06-12T09:41:00.000Z", "revocable": true }, "token": "dpp_li_00000000000000000000000000000001" } } } }, "400": { "description": "Validation failure. Body omits the `success` field. `message` is one of: `granteeName is required`, `granteeEmail is invalid`, `scopeType must be UNIT, PASSPORT or TENANT`, `expiresAt is required`, `expiresAt must be an ISO-8601 date`, `expiresAt must be in the future`, `expiresAt must be within 366 days`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Bad Request", "message": "expiresAt must be within 366 days" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "For `scopeType` `UNIT`/`PASSPORT`: the target id does not exist in this workspace (cross-tenant targets and `DRAFT` passports are indistinguishable from missing ones). Omitting the target id required by the `scopeType` also returns this 404 — there is no separate 400 for a missing target id. Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Not Found", "message": "Scope target not found in this workspace" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/grants/{id}/approve": { "post": { "operationId": "approveGrantRequest", "tags": [ "Access Grants" ], "summary": "Approve a pending access request and mint its token", "description": "Approves a `PENDING` third-party access request (submitted via the hosted request-access page). Approval mints the legitimate-interest capability token **at this moment** — pending requests carry no token — sets `status: ACTIVE`, records `decidedAt`/`decidedBy`, and replaces the request's provisional 90-day expiry with the `expiresAt` you supply (required; future; max **366 days** out).\n\nThe raw token is returned **once** in this response. If the request has a `granteeEmail`, the grantee is additionally e-mailed an inspection link containing the token (`…/unit/{batteryUnitId}?grant=dpp_li_…` or `…/passport/{passportId}?grant=dpp_li_…`) — the only other place the raw token ever exists. The decision is audited as `grant.approved`.\n\n**Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** global limiter, 100 requests/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The access-request (AccessGrant) id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGrantRequest" }, "example": { "expiresAt": "2026-09-12T09:41:00.000Z" } } } }, "responses": { "200": { "description": "Request approved; the capability token is shown only here (and in the grantee e-mail).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantIssuedResponse" }, "example": { "success": true, "grant": { "id": "c5d8e1f4-7a2b-4c9d-8e3f-6a1b2c3d4e5f", "status": "ACTIVE", "kind": "LEGITIMATE_INTEREST", "granteeName": "Marta Keller", "granteeEmail": "m.keller@recycler-example.eu", "organization": "Circular Battery Recycling GmbH", "purpose": "Assessing remaining capacity before acquisition for repurposing (Art. 77(9)).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "REQUEST", "issuerEmail": null, "decidedAt": "2026-06-12T09:41:00.000Z", "decidedBy": "admin@example.opendpp-node.eu", "expiresAt": "2026-09-12T09:41:00.000Z", "revokedAt": null, "lastUsedAt": null, "useCount": 0, "createdAt": "2026-06-12T08:15:30.000Z", "revocable": true }, "token": "dpp_li_00000000000000000000000000000002" } } } }, "400": { "description": "Invalid `expiresAt`. Body omits the `success` field. `message` is one of: `expiresAt is required`, `expiresAt must be an ISO-8601 date`, `expiresAt must be in the future`, `expiresAt must be within 366 days`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Bad Request", "message": "expiresAt is required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No grant with this id exists in this workspace. Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Not Found", "message": "Grant not found" } } } }, "409": { "description": "The grant is not `PENDING` (already decided, active, or revoked). Body omits the `success` field; the current status is interpolated into the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Conflict", "message": "Only PENDING requests can be approved (status: ACTIVE)" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/grants/{id}/deny": { "post": { "operationId": "denyGrantRequest", "tags": [ "Access Grants" ], "summary": "Deny a pending access request", "description": "Denies a `PENDING` third-party access request: sets `status: DENIED` and records `decidedAt`/`decidedBy`. No token is ever minted for a denied request, and no e-mail is sent to the requester. The decision is audited as `grant.denied`. The request body, if any, is ignored.\n\n**Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** global limiter, 100 requests/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The access-request (AccessGrant) id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantDecisionResponse" }, "example": { "success": true, "grant": { "id": "c5d8e1f4-7a2b-4c9d-8e3f-6a1b2c3d4e5f", "status": "DENIED", "kind": "LEGITIMATE_INTEREST", "granteeName": "Marta Keller", "granteeEmail": "m.keller@recycler-example.eu", "organization": "Circular Battery Recycling GmbH", "purpose": "Assessing remaining capacity before acquisition for repurposing (Art. 77(9)).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "REQUEST", "issuerEmail": null, "decidedAt": "2026-06-12T09:41:00.000Z", "decidedBy": "admin@example.opendpp-node.eu", "expiresAt": "2026-09-10T08:15:30.000Z", "revokedAt": null, "lastUsedAt": null, "useCount": 0, "createdAt": "2026-06-12T08:15:30.000Z", "revocable": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No grant with this id exists in this workspace. Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Not Found", "message": "Grant not found" } } } }, "409": { "description": "The grant is not `PENDING` (already decided, active, or revoked). Body omits the `success` field; the current status is interpolated into the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Conflict", "message": "Only PENDING requests can be denied (status: DENIED)" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/grants/{id}": { "delete": { "operationId": "revokeGrant", "tags": [ "Access Grants" ], "summary": "Revoke an access grant (soft revocation)", "description": "Soft-revokes a grant: sets `status: REVOKED` and `revokedAt` (the row is retained for audit; the public resolvers reject the token from then on). Audited as `grant.revoked`.\n\nBehavioral caveats (no status precondition — only the kind is checked):\n- Works on a grant in **any** status: revoking a `PENDING` request withdraws it; revoking a `DENIED` grant flips it to `REVOKED`.\n- Re-revoking an already-`REVOKED` grant returns 200 again and preserves the original `revokedAt`.\n- `AUTHORITY` grants (`kind: AUTHORITY`, platform-issued market-surveillance access) are **not tenant-revocable** — 403. Battery Reg. Art. 77 market-surveillance access must not depend on manufacturer consent; platform admins manage those.\n\n**Permission:** `grant:write` (subscription gating ⇒ 402 possible; cookie sessions need `X-CSRF-Token`; on workspaces enforcing multi-factor authentication, user sessions without a second factor get 403 — API-key clients exempt). **Rate limit:** global limiter, 100 requests/min per IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The grant (AccessGrant) id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grant revoked (idempotent: re-revoking keeps the original `revokedAt`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantDecisionResponse" }, "example": { "success": true, "grant": { "id": "9b2fa884-3c1d-4e8a-9f27-5b06c8d41a72", "status": "REVOKED", "kind": "LEGITIMATE_INTEREST", "granteeName": "Dr. Elena Varga", "granteeEmail": "e.varga@inspection-example.eu", "organization": "EU Battery Inspection Services", "purpose": "State-of-health verification for second-life suitability assessment under Art. 77(9).", "scopeType": "UNIT", "passportId": "4f1f7d2e-9a3b-4c5d-8e6f-7a8b9c0d1e2f", "batteryUnitId": "7c3a91d5-2e4f-4b6a-8c0d-1e2f3a4b5c6d", "issuerType": "TENANT", "issuerEmail": "admin@example.opendpp-node.eu", "decidedAt": null, "decidedBy": null, "expiresAt": "2026-09-12T09:41:00.000Z", "revokedAt": "2026-06-12T11:30:00.000Z", "lastUsedAt": "2026-06-12T10:02:14.000Z", "useCount": 3, "createdAt": "2026-06-12T09:41:00.000Z", "revocable": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Two distinct bodies share this status: (1) **route-level** — the grant is an `AUTHORITY` grant and cannot be revoked by the workspace; body is `{error, message}` **without** a `success` field (see example); (2) **middleware** — insufficient permission, missing/invalid CSRF token, cross-tenant access, or MFA required; standard envelope `{success: false, error, message}`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/GrantRouteError" }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "error": "Forbidden", "message": "Authority grants are platform-managed: market-surveillance access cannot be revoked by the workspace." } } } }, "404": { "description": "No grant with this id exists in this workspace. Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantRouteError" }, "example": { "error": "Not Found", "message": "Grant not found" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/operators": { "post": { "operationId": "registerOperator", "tags": [ "Economic Operators" ], "summary": "Register an economic operator and bind it to your workspace", "description": "Registers an economic operator (manufacturer, importer, supplier, …) and binds it to your workspace.\n\n**Permission:** `operator:create`. Cookie-session clients must send the `X-CSRF-Token` header (double-submit); Bearer clients (API key / JWT) are exempt.\n\n**Deduplication (platform-wide):** operators are unique on `regId` across the whole platform. If an operator with the submitted `regId` already exists (registered by your workspace or any other tenant), the **existing record is bound** to your workspace and the submitted `name`, `role` and `regIdScheme` are **ignored** — the response returns the pre-existing record. The call is idempotent: re-registering an already-bound operator succeeds with `201` again. The platform-wide match includes **archived** operators: if the existing operator is archived, the archived record is bound and returned as-is (`archivedAt` non-null) with `201` — registration does not un-archive it; use `POST /api/v1/operators/{id}/restore` to reactivate it.\n\n**Registration-id integrity:** fabricated `EORI-MOCK…` ids are rejected on every path. When `regIdScheme` is `EORI`, `regId` must match `^[A-Z]{2}[A-Za-z0-9]{1,15}$` (2-letter ISO 3166 country prefix followed by up to 15 alphanumerics, e.g. `DE1234567890`). Validation is syntax-only — existence is not checked against the EU EORI online validation service.\n\nSide effects: an `operator.created` audit event and an in-app notification are recorded.\n\n**Rate limit:** global limiter, 100 requests/min/IP (429 carries `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterOperatorRequest" }, "example": { "name": "Default EU Manufacturing Operator", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" } } } }, "responses": { "201": { "description": "Operator registered (or an existing operator with the same `regId` was bound to your workspace). Returned in both cases — inspect the returned `operator` to see whether your submitted `name`/`role` were applied or a pre-existing record was reused. A pre-existing record may even be archived (`archivedAt` non-null); binding does not un-archive it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterOperatorResponse" }, "example": { "success": true, "message": "Economic Operator supplier registered successfully", "operator": { "id": "9b2fa884-7c1d-4e7a-9a64-2f8d3b5c6e01", "name": "Default EU Manufacturing Operator", "regId": "EU-DEFAULT-001", "regIdScheme": null, "role": "MANUFACTURER", "archivedAt": null, "createdAt": "2026-06-12T09:41:00.000Z" } } } } }, "400": { "description": "Two distinct bodies. Missing `name`/`regId` returns the minimal envelope **without** an `error` key. A `regId`/`regIdScheme` validation failure (whitespace-only `regId`, fabricated `EORI-MOCK…` id, unknown scheme, or invalid EORI syntax) returns the standard envelope with `error: \"Bad Request\"`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperatorMinimalError" }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "missingParameters": { "summary": "name or regId missing (no error key)", "value": { "success": false, "message": "Missing supplier parameters: name and regId are required" } }, "whitespaceRegId": { "summary": "regId is whitespace-only (standard envelope)", "value": { "success": false, "error": "Bad Request", "message": "regId is required" } }, "invalidRegId": { "summary": "regId validation failure (standard envelope)", "value": { "success": false, "error": "Bad Request", "message": "Fabricated registration ids (EORI-MOCK…) are not accepted — register the operator's real registration id." } }, "invalidEoriSyntax": { "summary": "regIdScheme=EORI with bad syntax", "value": { "success": false, "error": "Bad Request", "message": "regId is not a syntactically valid EORI (expected a 2-letter country code followed by up to 15 alphanumeric characters, e.g. DE1234567890)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Database/handler failure. The route handler emits the minimal envelope (`{success: false, message}`, **no** `error` key, message taken from the underlying error); a failure inside the authentication layer instead emits the standard three-field envelope.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperatorMinimalError" }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "success": false, "message": "Database connection lost" } } } } } } }, "/api/v1/operators/{id}": { "patch": { "operationId": "updateOperator", "tags": [ "Economic Operators" ], "summary": "Update an operator's name or role (regId is immutable)", "description": "Edits an operator bound to your workspace. Only `name` and `role` are editable; `regId` is the legal registry identifier and is **intentionally immutable** here (register the operator again under the correct id instead). Non-string or whitespace-only values are silently ignored; submitted values are trimmed. If no usable field is supplied (every field missing, non-string, or whitespace-only — including an empty object `{}` or an omitted body), the current operator row is returned unchanged with `200` and no audit event is written. The handler does not diff against current values: supplying a value identical to the current one still performs an update and writes an audit event.\n\n**Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt.\n\n**Caveat — shared records:** operators are deduplicated platform-wide on `regId`. Updating `name`/`role` modifies the shared `EconomicOperator` record, so the change is visible to every other workspace bound to the same operator.\n\nWhen a change is applied, an `operator.updated` audit event is recorded. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side).\n\n**Rate limit:** global limiter, 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Operator UUID (`EconomicOperator.id`). Must be bound to your workspace.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOperatorRequest" }, "example": { "name": "Default EU Manufacturing Operator B.V.", "role": "IMPORTER" } } } }, "responses": { "200": { "description": "The (possibly unchanged) operator row. If the body contained no usable field, the current row is echoed back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOperatorResponse" }, "example": { "success": true, "operator": { "id": "9b2fa884-7c1d-4e7a-9a64-2f8d3b5c6e01", "name": "Default EU Manufacturing Operator B.V.", "regId": "EU-DEFAULT-001", "regIdScheme": null, "role": "IMPORTER", "archivedAt": null, "createdAt": "2026-06-12T09:41:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The operator does not exist or is not bound to your workspace. Note: minimal envelope without an `error` key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMinimalError" }, "example": { "success": false, "message": "Operator not found in your workspace." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Server-side failure. Unexpected server error. Unhandled errors are normalized by the global error handler to the standard envelope with the generic message \"An unexpected error occurred\"; details are logged server-side, never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "authLayerError": { "summary": "Authentication-layer failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } }, "delete": { "operationId": "deleteOperator", "tags": [ "Economic Operators" ], "summary": "Remove an operator (archives if it has passports, else hard-deletes)", "description": "Removes an operator, choosing automatically between two outcomes (ESPR Art. 9(2)/77 passport-persistence compliance — an operator that still has passports must never be hard-deleted):\n\n- **Archive (soft delete)** — if the operator has one or more passports, it is archived instead of deleted: `archivedAt` is set on the operator and every active passport of the operator is archived with a `retentionUntil` deadline set to a platform-configured retention period from now (default 15 years). Archived passports remain **publicly resolvable** (the persistence duty) but are excluded from active management lists. Response: `{success: true, archived: true, archivedPassports: }`. Fully reversible via `POST /api/v1/operators/{id}/restore`.\n- **Hard delete** — if the operator has no passports it is permanently deleted (tenant bindings cascade-delete; user/facility/API-key references are set to null). Response: `{success: true, archived: false}` — no `archivedPassports` field.\n- **Fallback** — if the hard delete fails on a residual foreign-key reference, the operator is archived instead and the response is `{success: true, archived: true}` **without** `archivedPassports`. If even the fallback archive fails, `409` is returned.\n\n**Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. The operator must be bound to your workspace (`404` otherwise).\n\n**Caveat — shared records:** archiving/deleting affects the platform-wide operator record, which may be shared with other workspaces bound to the same `regId`.\n\nSide effects: an `operator.archived` or `operator.deleted` audit event plus an in-app notification — on the primary archive and hard-delete paths only; the foreign-key fallback archive writes **no** audit event or notification. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side).\n\n**Rate limit:** global limiter, 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Operator UUID (`EconomicOperator.id`). Must be bound to your workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operator removed. `archived: true` = soft-deleted (passports retained and still publicly resolvable; restorable); `archived: false` = hard-deleted. `archivedPassports` is present only on the primary archive path — it is absent on hard deletes and on the foreign-key fallback archive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOperatorResponse" }, "examples": { "archivedWithPassports": { "summary": "Operator had passports: archived", "value": { "success": true, "archived": true, "archivedPassports": 12 } }, "hardDeleted": { "summary": "Operator had no passports: hard-deleted", "value": { "success": true, "archived": false } }, "fallbackArchived": { "summary": "Hard delete blocked by a residual reference: archived (no count)", "value": { "success": true, "archived": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The operator does not exist or is not bound to your workspace. Note: minimal envelope without an `error` key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMinimalError" }, "example": { "success": false, "message": "Operator not found in your workspace." } } } }, "409": { "description": "The operator could neither be hard-deleted nor archived (both attempts failed). Note: minimal envelope without an `error` key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMinimalError" }, "example": { "success": false, "message": "Operator could not be removed; it is still referenced." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Server-side failure. Unexpected server error. Unhandled errors are normalized by the global error handler to the standard envelope with the generic message \"An unexpected error occurred\"; details are logged server-side, never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "authLayerError": { "summary": "Authentication-layer failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } } }, "/api/v1/operators/{id}/restore": { "post": { "operationId": "restoreOperator", "tags": [ "Economic Operators" ], "summary": "Restore an archived operator and its archived passports", "description": "Un-archives an operator that was soft-deleted by `DELETE /api/v1/operators/{id}` and brings its archived passports back into the active catalogue: clears the operator's `archivedAt`, then clears `archivedAt` and `retentionUntil` on every archived passport of the operator **except** passports that were independently `DECOMMISSIONED` (those keep their own retention clock and stay archived).\n\nSafe to call on a non-archived operator — it simply restores any archived passports the operator may have (`restoredPassports` may be `0`). No request body.\n\n**Permission:** `operator:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt. `404` if the operator is not bound to your workspace.\n\nSide effects: an `operator.restored` audit event and an in-app notification. Unhandled database errors are normalized by the global error handler to the standard `{success: false, error, message}` envelope with a generic message (details are logged server-side).\n\n**Rate limit:** global limiter, 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Operator UUID (`EconomicOperator.id`). Must be bound to your workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operator un-archived. `restoredPassports` is the number of passports returned to the active catalogue (excludes independently DECOMMISSIONED passports).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreOperatorResponse" }, "example": { "success": true, "restoredPassports": 12 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The operator does not exist or is not bound to your workspace. Note: minimal envelope without an `error` key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorMinimalError" }, "example": { "success": false, "message": "Operator not found in your workspace." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Server-side failure. Unexpected server error. Unhandled errors are normalized by the global error handler to the standard envelope with the generic message \"An unexpected error occurred\"; details are logged server-side, never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "authLayerError": { "summary": "Authentication-layer failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } } }, "/api/v1/tenants/rotate-keys": { "post": { "operationId": "rotateTenantKeys", "tags": [ "eIDAS Keys" ], "summary": "Rotate the tenant's eIDAS ECDSA signing key pair", "description": "Generates a brand-new ECDSA **prime256v1 (P-256)** key pair for your workspace's eIDAS advanced-seal signing and rotates it into the encrypted database vault, replacing the previous key. No request body is required; a valid JSON body, if sent, is ignored.\n\nWhat happens:\n- The new private key (PKCS#8) is encrypted with AES-256-GCM (per-entry HKDF-derived key; the tenant id is bound as GCM additional authenticated data) and upserted into the vault — the **previous private key is overwritten and unrecoverable**.\n- The tenant's published `eidasPublicKey` is updated to the new public key (SPKI PEM), which is also returned in the response.\n- A best-effort X.509 identity certificate is minted from the platform seal CA, binding the new key to the tenant's legal name (eIDAS Art. 36(1)(b) creator identification); a certificate-minting failure does **not** fail the rotation (the certificate fields simply stay null until backfilled).\n\n**Operational impact:** rotation does not invalidate existing seals. Each sealed passport embeds the signing public key and certificate chain at sealing time, so previously sealed passports keep verifying with their embedded key material. Passports sealed after rotation use the new key.\n\n**Permission:** `key:write`. Cookie-session clients must send `X-CSRF-Token`; Bearer clients are exempt.\n\n**Rate limit:** global limiter, 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Key pair rotated. `publicKey` is the new public key as an SPKI PEM string (the private key never leaves the encrypted vault).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateTenantKeysResponse" }, "example": { "success": true, "message": "eIDAS Asymmetric Key Pair generated and rotated in secure DB custody successfully", "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEb2zJ9bQ4mB1S0aD3kXq8YV5nW7Hc\nPdLmA2tFx0RkNqUjEe6ZsK1vGyTwoCh3M4i5O8rJlD9fXaB0nSgQp7Y2uw==\n-----END PUBLIC KEY-----\n" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Key generation, vault encryption, or database failure. The route handler emits the minimal envelope (`{success: false, message}`, **no** `error` key, message taken from the underlying error); a failure inside the authentication layer instead emits the standard three-field envelope.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/OperatorMinimalError" }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "success": false, "message": "tenantId is required for key provisioning" } } } } } } }, "/api/v1/passports": { "post": { "operationId": "createPassport", "tags": [ "Passports" ], "summary": "Create (ingest) a Digital Product Passport", "description": "Creates a SKU/type-level Digital Product Passport.\n\n**Permission:** `passport:create` (Bearer `op_dpp_token_…` API key or session JWT; cookie sessions must also send the `X-CSRF-Token` double-submit header). Write operations are subject to subscription gating (**402**) and, where the workspace enforces it, MFA (**403**).\n\n**Rate limit:** global 100 requests/min per IP (`x-ratelimit-*` headers). **Body limit: 1 MiB (1,048,576 bytes)** → **413** beyond that.\n\n**Validation.** Unless `draft: true`, `metadata` is validated against the ESPR category rules for `metadata.category` plus cross-field rules (e.g. `materialComposition` percentages must sum to 100 ±0.1, `originCountry` must be a real ISO 3166-1 alpha-2 code), and the product's EPCIS traceability lineage is audited. For five categories (textiles, batteries, electronics, chemicals, construction) the authoritative per-category JSON Schema is served live at `GET /api/v1/schemas/{category}`; the other four (cosmetics, toys, iron-steel, aluminium) are validated by built-in server-side rules and `GET /api/v1/schemas/{category}` returns **404** for them. Failure returns the **400 Validation Failed** body with per-field `errors[]` (plus `warnings[]` when any exist — the key is omitted entirely when there are none). A passing payload may still produce non-blocking `warnings[]`, echoed in the 201. `friendlyMessage` texts are localized via `?lang=` or `Accept-Language` (default `en`); category-validity errors (`metadata.category` missing or unknown) carry no `friendlyMessage`.\n\n**Drafts.** `draft: true` skips ALL validation, stores the passport with `status: \"DRAFT\"` (not publicly resolvable), returns `message: \"Draft passport saved\"` with `warnings: []`, and does **not** emit a webhook.\n\n**Identifier handling.** `productId` may be a GTIN-14 (14 digits, GS1 mod-10 check digit), a GRAI (14-digit numeric asset id + up to 16 alphanumeric serial chars), or a free-form SKU. A valid GTIN-14 is auto-copied into `metadata.gtin` (a GRAI into `metadata.grai`) before storage. The server mints a UUID passport id and a GS1 Digital Link URI `https://opendpp-node.eu/{01|8003}/{productId}/21/{passportId}`.\n\n**Operator binding.** With `operatorId` omitted, the passport is attributed to the first economic operator bound to your workspace; if no operator is bound at all the request fails **400** (the API never fabricates an operator identity — register one via `POST /api/v1/operators`). An `operatorId` not bound to your workspace → **403**. Operator-scoped API keys force their own operator and **403** on mismatch. The `(productId, operatorId)` pair is unique → **409** on duplicates. An optional `facilityId` must reference a Facility in your workspace (**400** otherwise).\n\n**Webhook:** non-draft creation transactionally enqueues a `passport.ingested` event whose payload is the public redacted JSON-LD passport document (same masking as the 201 `passport` field). Drafts emit nothing.\n\n**Response caveats:** the 201 `passport` field is the **public, redacted** JSON-LD representation — even for the creator. The owner-only metadata key `facilityDetails` is replaced with the literal placeholder `\"[REDACTED - Privileged Access Required]\"` (it appears as the placeholder even when you did not supply it), and for `category: \"batteries\"` the restricted legitimate-interest keys `detailedPerformance`, `lifecycleAndInUse` and `circularityAndDisassembly` (Battery Reg. Annex XIII parts 2-4) are masked the same way when present. `enrichment` is stored outside the validated metadata and Merkle seal and never appears in the JSON-LD document. Only `success`, `message`, `passport`, and `warnings` are emitted at the top level of the 201 body.\n\n**Other 400 bodies:** non-validation failures (whitespace-only `productId`, no bound operator, unknown `facilityId`) reuse status 400 with the plain `{\"success\": false, \"error\": \"Bad Request\", \"message\": …}` triple and **no** `errors`/`warnings` arrays. Requests rejected before the handler runs — request-body schema violations (e.g. missing `productId`) and malformed JSON — come back as just `{\"error\": \"Bad Request\", \"message\": …}`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Locale for localized `friendlyMessage` validation texts. One of: en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is, uk, tr. Unknown values are ignored; falls back to `Accept-Language`, then `en`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportCreateRequest" }, "example": { "productId": "09501101530003", "operatorId": "5c1e0f3a-7b2d-4c8e-a91f-2d3e4f5a6b7c", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 }, "enrichment": { "tagline": "Low-carbon structural steel", "images": [ { "url": "https://cdn.example.com/steel-beam.jpg", "caption": "S355 beam" } ] } } } } }, "responses": { "201": { "description": "Passport created (or draft saved). `passport` is the public redacted JSON-LD document; `warnings` is always present (empty array when none, and always empty for drafts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportIngestCreated" }, "example": { "success": true, "message": "Digital Product Passport successfully validated and ingested", "passport": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "materialComposition": "https://w3id.org/dpp/context/v1#materialComposition", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails", "regulatoryCompliance": "https://w3id.org/dpp/context/v1#regulatoryCompliance", "scrapMetalContentRatio": "https://w3id.org/dpp/context/v1#scrapMetalContentRatio", "tensileStrengthClass": "https://w3id.org/dpp/context/v1#tensileStrengthClass", "carbonEmissionIntensityPerTon": "https://w3id.org/dpp/context/v1#carbonEmissionIntensityPerTon", "gtin": "https://w3id.org/dpp/context/v1#gtin" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012", "id": "9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "5c1e0f3a-7b2d-4c8e-a91f-2d3e4f5a6b7c", "name": "Demo Manufacturing GmbH", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" }, "manufacturingFacility": null, "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": "[REDACTED - Privileged Access Required]", "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42, "gtin": "09501101530003" }, "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": "[REDACTED - Privileged Access Required]", "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42, "gtin": "09501101530003" }, "warnings": [] } } } }, "400": { "description": "Three variants share this status: (1) **Validation Failed** — the metadata failed ESPR category / cross-field / traceability validation; carries per-field `errors[]` (and `warnings[]` only when at least one warning exists). (2) **Bad Request** triple — whitespace-only `productId`, no economic operator bound to the workspace, or unknown `facilityId`; `{success, error, message}` with no `errors`/`warnings`. (3) Pre-handler rejections — request-body schema violations (e.g. missing `productId`) and malformed JSON return only `{error, message}`.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "title": "ESPR validation failure", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Blocking findings. Items produced by the category-validity check (`metadata.category` missing/unknown) carry no `friendlyMessage`." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted entirely when there are no warnings." } } }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "validationFailed": { "summary": "ESPR category validation failure (no warnings → key omitted)", "value": { "success": false, "error": "Validation Failed", "message": "Dynamic metadata payload failed ESPR category compliance validation", "errors": [ { "path": "tensileStrengthClass", "message": "tensileStrengthClass must be a non-empty string", "friendlyMessage": "Tensile Strength Class: a non-empty string" } ] } }, "badRequest": { "summary": "No economic operator bound to the workspace", "value": { "success": false, "error": "Bad Request", "message": "No economic operator is bound to this workspace. Register your operator first via POST /api/v1/operators (or pass operatorId) — every passport must be attributed to a real economic operator." } }, "schemaRejected": { "summary": "Request-body schema rejection (only error + message returned)", "value": { "error": "Bad Request", "message": "body must have required property 'productId'" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "A passport already exists for this `(productId, operatorId)` pair.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Conflict", "message": "A Product Passport already exists for productId: 09501101530003" } } } }, "413": { "description": "Body exceeds the 1 MiB (1,048,576-byte) body limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 413 }, "code": { "type": "string", "const": "FST_ERR_CTP_BODY_TOO_LARGE" }, "error": { "type": "string", "const": "Payload Too Large" }, "message": { "type": "string" } } }, "example": { "statusCode": 413, "code": "FST_ERR_CTP_BODY_TOO_LARGE", "error": "Payload Too Large", "message": "Request body is too large" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "listPassports", "tags": [ "Passports" ], "summary": "List passports in your workspace (paginated JSON-LD)", "description": "Returns the **non-archived** passports of every economic operator bound to your workspace, newest first (`createdAt DESC`). Operator-scoped API keys only see passports of their bound operator.\n\n**Permission:** `passport:read` (read-only — no subscription/402 gate).\n\n**Filtering:** `category` and `originCountry` are exact-match filters on the top-level `metadata` keys of the same name. Known `metadata.category` values: `textiles`, `batteries`, `electronics`, `cosmetics`, `toys`, `iron-steel`, `aluminium`, `chemicals`, `construction`; `originCountry` is ISO 3166-1 alpha-2.\n\n**Pagination:** `page` (default 1) and `limit` (default 10) are numeric strings matching `^[0-9]+$` — any other value is rejected with the framework's default 400 validation body (see 400). Parsed values are clamped server-side to `page >= 1` and `1 <= limit <= 100`. There is **no `total` count**; page until you receive fewer than `limit` items.\n\n**Serialization caveats:**\n- The redaction tier of each item depends on the credential's **role**: only `BRAND_OPERATOR` credentials receive the unredacted owner-tier document. Every other role — including `TENANT_ADMIN` — receives the public tier: `facilityDetails` (and, for `batteries`, `detailedPerformance` / `lifecycleAndInUse` / `circularityAndDisassembly`) are masked to the literal string `\"[REDACTED - Privileged Access Required]\"`.\n- `economicOperator.role` is **absent** from list items and `manufacturingFacility` is always `null` here — fetch a single passport (`GET /api/v1/passports/{id}`) for the facility node and operator role.\n- The response passes through a declared response schema: top-level keys other than `success`, `page`, `limit`, `passports` are stripped. Passport items allow additional properties, so undeclared item keys (`status`, `archivedAt`, `retentionUntil`, `manufacturingFacility`, the flattened metadata keys) pass through intact — but two **declared** item keys are mangled by their subschemas: the `@context` term-map object (second array element) is always emptied to `{}`, and `proof` is emptied to `{}` on sealed items (`null` on unsealed) — `signatureValue`, `merkleRoot`, `redactedLeaves`, `x5c` and `rfc3161` are all stripped from list output. Fetch a single passport (`GET /api/v1/passports/{id}`) or the public resolver for the verifiable proof block.\n\n**Rate limits:** global limiter, 100 requests/min per IP (600/min for known crawler user agents); 429 carries `x-ratelimit-*` headers.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "category", "in": "query", "required": false, "description": "Exact-match filter on `metadata.category`. Known values: textiles, batteries, electronics, cosmetics, toys, iron-steel, aluminium, chemicals, construction.", "schema": { "type": "string" } }, { "name": "originCountry", "in": "query", "required": false, "description": "Exact-match filter on `metadata.originCountry` (ISO 3166-1 alpha-2, e.g. `PT`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of JSON-LD passport documents. No total count is returned. Note the list-specific mangling: the `@context` term map is emptied to `{}` and `proof` contents are stripped (see operation description).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportListResponse" }, "example": { "success": true, "page": 1, "limit": 10, "passports": [ { "@context": [ "https://w3id.org/dpp/context/v1", {} ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "id": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f", "name": "Aurora Textiles GmbH", "regId": "EU-DEFAULT-001" }, "manufacturingFacility": null, "metadata": { "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" } ] } } } }, "400": { "description": "Route validation failure (framework default body — note `statusCode`/`code` keys, no `success` field): `page` or `limit` did not match `^[0-9]+$`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "querystring/page must match pattern \"^[0-9]+$\"" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:read` required) or cross-tenant access: the credential does not belong to the tenant-subdomain workspace being addressed." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError", "description": "Query failure. Body is the standard `{success:false, error:\"Internal Server Error\", message}` envelope; `message` may echo the internal error text or fall back to \"Failed to search passports\"." } } } }, "/api/v1/passports/validate-only": { "post": { "operationId": "validatePassport", "tags": [ "Passports" ], "summary": "Dry-run ESPR validation of passport metadata (nothing is stored)", "description": "Runs the full ESPR category compliance validation on a metadata payload **without persisting anything** — intended for pre-flight checks in integration pipelines.\n\n**Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions). Despite being read-only in effect, it is gated as a write permission, so subscription gating (**402**) applies.\n\n**Rate limit:** global 100 requests/min per IP. **Body limit: 262,144 bytes (256 KiB)** → **413** beyond that.\n\n**Behavioral caveats:**\n- The EPCIS **traceability lineage audit is NOT run** here (it only runs at real ingestion), so a payload can pass this dry-run and still fail `POST /api/v1/passports` on traceability errors.\n- `operatorId` is accepted by the body schema but **ignored** by the handler.\n- The 200 body always carries `errors: []`; `warnings` is **omitted entirely** when there are none (it is not an empty array). The same omission applies to `warnings` on the 400 Validation Failed body.\n- `friendlyMessage` localization via `?lang=` / `Accept-Language` (28 languages, default `en`); category-validity errors (`metadata.category` missing or unknown) carry no `friendlyMessage`.\n- Structural rejections of the request body (e.g. missing `productId`, non-object `metadata`) and malformed JSON return just `{\"error\": \"Bad Request\", \"message\": …}`; the only structurally bad input that reaches the handler is a whitespace-only `productId`, answered with the fuller `Bad Request` body shown below.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Locale for localized `friendlyMessage` validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is, uk, tr). Unknown values are ignored; falls back to `Accept-Language`, then `en`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyRequest" }, "example": { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } } } } }, "responses": { "200": { "description": "Metadata is valid for its ESPR category. `errors` is always an empty array; `warnings` (non-blocking findings) is present only when there is at least one warning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyResult" }, "example": { "success": true, "message": "Passport metadata payload is 100% valid and ESPR category compliant", "category": "iron-steel", "errors": [] } } } }, "400": { "description": "Validation failed, or the request body was structurally invalid. Three variants share this status: (1) ESPR validation failure (`error: \"Validation Failed\"`, with `errors[]` and — only when at least one exists — `warnings[]`); (2) whitespace-only `productId` (`error: \"Bad Request\"`, `category: \"unknown\"`, `errors: []`); (3) request-body schema rejections and malformed JSON, returned as just `{error, message}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyError" }, "examples": { "validationFailed": { "summary": "ESPR category validation failure", "value": { "success": false, "error": "Validation Failed", "message": "Dynamic metadata payload failed ESPR category compliance validation", "category": "iron-steel", "errors": [ { "path": "tensileStrengthClass", "message": "tensileStrengthClass must be a non-empty string", "friendlyMessage": "Tensile Strength Class: a non-empty string" } ] } }, "badRequest": { "summary": "Whitespace-only productId", "value": { "success": false, "error": "Bad Request", "message": "productId must be a non-empty string", "category": "unknown", "errors": [] } }, "schemaRejected": { "summary": "Request-body schema rejection (only error + message returned)", "value": { "error": "Bad Request", "message": "body must have required property 'productId'" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "Body exceeds the 262,144-byte (256 KiB) route body limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 413 }, "code": { "type": "string", "const": "FST_ERR_CTP_BODY_TOO_LARGE" }, "error": { "type": "string", "const": "Payload Too Large" }, "message": { "type": "string" } } }, "example": { "statusCode": 413, "code": "FST_ERR_CTP_BODY_TOO_LARGE", "error": "Payload Too Large", "message": "Request body is too large" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/passports/validate-only-public": { "post": { "operationId": "validatePassportPublic", "tags": [ "Passports" ], "summary": "Public dry-run ESPR metadata validation (strictly rate-limited)", "description": "Identical validation semantics to `POST /api/v1/passports/validate-only`, but **fully public — no authentication of any kind**, intended for try-before-you-buy schema checks. Nothing is persisted.\n\n**Rate limit: 10 requests/min per IP** — a strict per-route limit that **replaces** the global 100/min for this endpoint (emits `x-ratelimit-limit` / `x-ratelimit-remaining` / `x-ratelimit-reset` headers and `retry-after` on 429). **Body limit: 65,536 bytes (64 KiB)** → **413** beyond that. These caps exist because the endpoint runs the full validation engine unauthenticated (DoS mitigation).\n\n**Behavioral caveats:**\n- No tenant context: the EPCIS traceability lineage audit is **not** run, and `operatorId` is accepted but ignored.\n- The 200 body always carries `errors: []`; `warnings` is omitted entirely when there are none (same omission on the 400 Validation Failed body).\n- Error/warning `friendlyMessage` localization via `?lang=` / `Accept-Language` (28 languages, default `en`); category-validity errors carry no `friendlyMessage`.\n- Structural rejections of the request body (e.g. missing `productId`) and malformed JSON return just `{\"error\": \"Bad Request\", \"message\": …}`; a whitespace-only `productId` gets the fuller `Bad Request` body shown below.", "security": [], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Locale for localized `friendlyMessage` validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is, uk, tr). Unknown values are ignored; falls back to `Accept-Language`, then `en`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyRequest" }, "example": { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } } } } }, "responses": { "200": { "description": "Metadata is valid for its ESPR category. `errors` is always an empty array; `warnings` is present only when there is at least one non-blocking warning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyResult" }, "example": { "success": true, "message": "Passport metadata payload is 100% valid and ESPR category compliant", "category": "iron-steel", "errors": [] } } } }, "400": { "description": "Validation failed or the body was structurally invalid — same three variants as the authenticated `validate-only` endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportValidateOnlyError" }, "examples": { "validationFailed": { "summary": "ESPR category validation failure", "value": { "success": false, "error": "Validation Failed", "message": "Dynamic metadata payload failed ESPR category compliance validation", "category": "textiles", "errors": [ { "path": "fiberComposition", "message": "fiberComposition must be an array for textiles", "friendlyMessage": "Fiber Composition: an array for textiles" } ] } }, "badRequest": { "summary": "Whitespace-only productId", "value": { "success": false, "error": "Bad Request", "message": "productId must be a non-empty string", "category": "unknown", "errors": [] } } } } } }, "413": { "description": "Body exceeds the 65,536-byte (64 KiB) route body limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 413 }, "code": { "type": "string", "const": "FST_ERR_CTP_BODY_TOO_LARGE" }, "error": { "type": "string", "const": "Payload Too Large" }, "message": { "type": "string" } } }, "example": { "statusCode": 413, "code": "FST_ERR_CTP_BODY_TOO_LARGE", "error": "Payload Too Large", "message": "Request body is too large" } } } }, "429": { "description": "Rate limit exceeded. This endpoint is capped at **10 requests/min per IP** (a per-route limit that replaces the global 100/min). Inspect the `x-ratelimit-*` headers and retry after the indicated window.", "headers": { "x-ratelimit-limit": { "description": "Request ceiling for the current window.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "retry-after": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Default rate-limit error body.", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "statusCode": 429, "code": "FST_ERR_RATE_LIMIT", "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 1 minute" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/passports/bulk": { "post": { "operationId": "bulkIngestPassports", "tags": [ "Passports" ], "summary": "Bulk-ingest up to 200 passports with per-row error reporting", "description": "Ingests up to **200** passports in one request with **partial-success semantics**: each row is validated and inserted independently; failed rows are skipped and reported as human-readable strings in `errors[]`. Returns **201** as long as at least one row was inserted (even with row errors); returns **400 Bulk Ingestion Failed** only when **every** row failed.\n\n**Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions; subscription gating → **402**).\n\n**Rate limit:** global 100 requests/min per IP. **Body limit: 1 MiB (1,048,576 bytes)** → **413** beyond that; in practice the `maxItems: 200` envelope cap is the effective bound for typical rows. Envelope violations — empty array, more than 200 items, missing `passports` — are rejected before any row is processed, with the full default validation error body (`{statusCode, code, error, message}`).\n\n**Per-row behavior (differences from `POST /api/v1/passports`):**\n- Rows are validated with the ESPR category engine only — the **EPCIS traceability audit is NOT run** for bulk rows.\n- No `draft` support: every inserted row is created with `status: \"ACTIVE\"`. No `enrichment` support.\n- A valid GTIN-14/GRAI `productId` is **not** auto-copied into `metadata.gtin`/`metadata.grai` (unlike single ingestion).\n- Operator resolution per row: explicit `operatorId` must be bound to your workspace; otherwise the workspace's first bound operator is used; operator-scoped API keys force their operator. Lookups are cached within the request.\n- Duplicate `(productId, operatorId)` rows, unknown facilities, and per-row DB failures become `errors[]` strings (prefixed `[SKU: ]`), never a request-level failure.\n- Each successfully inserted row **transactionally enqueues a `passport.ingested` webhook event** (public redacted JSON-LD payload).\n- Row validation messages use the localized `friendlyMessage` where the engine provides one (`?lang=` / `Accept-Language`); category-validity errors fall back to the technical `path: message` form.\n\nNote the 400 `Bulk Ingestion Failed` body has **no `message` field**, and `errors` is an array of **strings** (not objects).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Locale for the localized validation text inside per-row `errors[]` strings (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is, uk, tr). Unknown values are ignored; falls back to `Accept-Language`, then `en`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportBulkRequest" }, "example": { "passports": [ { "productId": "09501101530003", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 62.5 }, { "material": "Virgin steel", "percentage": 37.5 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Hot rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00417", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 62.5, "tensileStrengthClass": "S355", "carbonEmissionIntensityPerTon": 1.42 } }, { "productId": "09501101530010", "metadata": { "category": "iron-steel", "originCountry": "DE", "materialComposition": [ { "material": "Recycled steel", "percentage": 100 } ], "facilityDetails": [ { "facilityName": "Musterstahl Works Duisburg", "location": "Duisburg, DE", "activity": "Cold rolling" } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "EN 10025-2 Mill Certificate", "referenceNumber": "MC-2026-00418", "issuer": "TUV Rheinland" } ] }, "scrapMetalContentRatio": 100, "tensileStrengthClass": "S275", "carbonEmissionIntensityPerTon": 0.61 } } ] } } } }, "responses": { "201": { "description": "Bulk run finished with at least one inserted row. `errors` is present only when at least one row failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportBulkResult" }, "example": { "success": true, "message": "Bulk CSV ingestion finished. Registered 1 passports, skipped 1 rows with errors.", "insertedCount": 1, "results": [ { "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012" } ], "errors": [ "[SKU: 09501101530010] Duplicate productId already exists in database for this operator" ] } } } }, "400": { "description": "Either every row failed (`Bulk Ingestion Failed`, with string `errors[]` and no `message` field), or the request never reached row processing: envelope violations of the `passports` array bounds and malformed JSON both return the full default error body (`{statusCode, code?, error, message}` — nothing is stripped on this operation).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PassportBulkFailure" }, { "type": "object", "title": "Default request-rejection error body", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 400 }, "code": { "type": "string", "description": "Machine-readable error code; present for envelope (schema) violations (`FST_ERR_VALIDATION`), may be absent for malformed JSON.", "examples": [ "FST_ERR_VALIDATION" ] }, "error": { "type": "string", "const": "Bad Request" }, "message": { "type": "string" } } } ] }, "examples": { "allRowsFailed": { "summary": "Every row was rejected", "value": { "success": false, "error": "Bulk Ingestion Failed", "errors": [ "[SKU: 09501101530003] Validation failed: category: Category must be one of: textiles, batteries, electronics, cosmetics, toys, iron-steel, aluminium, chemicals, construction", "Missing or invalid productId in spreadsheet row" ] } }, "envelopeRejected": { "summary": "Envelope violates the request schema (e.g. more than 200 rows)", "value": { "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "body/passports must NOT have more than 200 items" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "Body exceeds the 1 MiB (1,048,576-byte) body limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 413 }, "code": { "type": "string", "const": "FST_ERR_CTP_BODY_TOO_LARGE" }, "error": { "type": "string", "const": "Payload Too Large" }, "message": { "type": "string" } } }, "example": { "statusCode": 413, "code": "FST_ERR_CTP_BODY_TOO_LARGE", "error": "Payload Too Large", "message": "Request body is too large" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/passports/aas/ingest": { "post": { "operationId": "ingestPassportFromAas", "tags": [ "Passports" ], "summary": "Ingest a passport from an AAS JSON Environment (seal-verified)", "description": "Ingests (creates **or updates**) a Digital Product Passport from an Industry-4.0 **Asset Administration Shell (AAS) JSON Environment** — the same format produced by OpenDPP's own AAS export.\n\n**Permission:** `passport:create` (Bearer API key or session JWT + CSRF for cookie sessions; subscription gating → **402**).\n\n**Rate limit:** global 100 requests/min per IP. **Body limit: 262,144 bytes (256 KiB)** → **413**.\n\n**Parsing.** The environment must contain a `submodels` array including a submodel with `idShort: \"ComplianceMetadata\"`, whose `submodelElements` are parsed back into the metadata object; missing it fails 400 (`Ingestion Failed`). `productId` is resolved from `metadata.gtin` || `metadata.grai` || `metadata.productId` || the first shell's `assetInformation.specificAssetIds` entry named `productId` — unresolvable → 400 `Bad Request`. The parsed metadata then passes the full ESPR category validation **plus the EPCIS traceability audit** (400 `Validation Failed` with `errors[]`).\n\n**eIDAS seal verification.** If the environment embeds an `eidasVerificationSeal` submodel (`digitalSealHash` / `cryptographicSignature` / `pemPublicKey` elements), the seal is verified against **your tenant's server-held eIDAS public key** — never the key embedded in the request (self-signing is rejected by design). An embedded seal that fails verification → **400 `Signature Verification Failed`**; this includes the case where your workspace holds no matching key. `isSealed`/`signatureVerified` in the 201 echo the outcome (both `false` for unsealed documents).\n\n**Upsert semantics.** If a passport already exists for the resolved `(productId, operator)` pair: a **sealed** existing passport refuses re-ingestion (**403** — re-seal explicitly after changes); an unsealed one has its metadata, Merkle tree and seal fields **replaced**, still answering **201**. Operator resolution: operator-scoped API keys use their own operator and **403** when that operator is not bound to your workspace; otherwise the workspace's first bound operator is used; none bound → 400.\n\n**Caveats:**\n- **NO webhook is emitted** — unlike `POST /api/v1/passports` and `/bulk`, AAS ingestion never enqueues `passport.ingested` (or any other event).\n- The catch-all error path returns **400 `Ingestion Failed`** with the underlying parse/processing message — even for internal failures (this handler does not emit its own 500).\n- Validation `friendlyMessage` localization via `?lang=` / `Accept-Language`; category-validity errors carry no `friendlyMessage`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Locale for localized `friendlyMessage` validation texts (en, bg, hr, cs, da, nl, et, fi, fr, de, el, hu, ga, it, lv, lt, mt, pl, pt, ro, sk, sl, es, sv, no, is, uk, tr). Unknown values are ignored; falls back to `Accept-Language`, then `en`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AasEnvironmentInput" }, "examples": { "abbreviated": { "summary": "Structurally illustrative (abbreviated) environment", "description": "Shows the envelope structure only. A real `ComplianceMetadata` submodel must carry the FULL field set its ESPR category requires (for `iron-steel`: `materialComposition`, `facilityDetails`, `regulatoryCompliance`, `scrapMetalContentRatio`, `tensileStrengthClass`, `carbonEmissionIntensityPerTon` in addition to `category`/`originCountry`) — this abbreviated example would fail ingestion with 400 `Validation Failed`. The reliable source of a valid environment is OpenDPP's own AAS export of an existing passport.", "value": { "assetAdministrationShells": [ { "id": "urn:opendpp:aas:9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012", "idShort": "AAS_09501101530003", "assetInformation": { "assetKind": "Instance", "specificAssetIds": [ { "name": "productId", "value": "09501101530003" } ] }, "submodels": [] } ], "submodels": [ { "id": "urn:opendpp:submodel:compliance:09501101530003", "idShort": "ComplianceMetadata", "submodelElements": [ { "idShort": "category", "modelType": "Property", "valueType": "xs:string", "value": "iron-steel" }, { "idShort": "originCountry", "modelType": "Property", "valueType": "xs:string", "value": "DE" }, { "idShort": "gtin", "modelType": "Property", "valueType": "xs:string", "value": "09501101530003" } ] } ] } } } } } }, "responses": { "201": { "description": "Passport created or (if it existed unsealed) updated from the AAS environment. Returned for both create and update. No webhook event is emitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AasIngestCreated" }, "example": { "success": true, "message": "Digital Product Passport successfully ingested from AAS", "passportId": "9b2fa884-1c7d-4a0e-9d3b-5f6a7c8e9012", "productId": "09501101530003", "isSealed": false, "signatureVerified": false } } } }, "400": { "description": "Four variants share this status: `Bad Request` (non-object body, unresolvable productId, no bound operator), `Signature Verification Failed` (embedded seal invalid/altered or no matching tenant key), `Validation Failed` (ESPR/traceability — carries `errors[]`, and `warnings[]` when present), and `Ingestion Failed` (catch-all parse/processing error with the underlying message).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "title": "AAS ESPR validation failure", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted entirely when there are no warnings." } } } ] }, "examples": { "badRequest": { "summary": "productId unresolvable from the AAS metadata", "value": { "success": false, "error": "Bad Request", "message": "Could not resolve productId (GTIN/GRAI) from AAS metadata." } }, "signatureVerificationFailed": { "summary": "Embedded eIDAS seal failed verification", "value": { "success": false, "error": "Signature Verification Failed", "message": "eIDAS Electronic Seal signature is invalid or altered." } }, "validationFailed": { "summary": "Parsed metadata failed ESPR/traceability validation", "value": { "success": false, "error": "Validation Failed", "message": "Dynamic metadata parsed from AAS failed compliance validation", "errors": [ { "path": "materialComposition", "message": "materialComposition must be an array", "friendlyMessage": "materialComposition must be a valid array of material percentage shares" } ] } }, "ingestionFailed": { "summary": "Catch-all parse/processing failure", "value": { "success": false, "error": "Ingestion Failed", "message": "Missing 'ComplianceMetadata' submodel in AAS Environment." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "description": "Body exceeds the 262,144-byte (256 KiB) route body limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer", "const": 413 }, "code": { "type": "string", "const": "FST_ERR_CTP_BODY_TOO_LARGE" }, "error": { "type": "string", "const": "Payload Too Large" }, "message": { "type": "string" } } }, "example": { "statusCode": 413, "code": "FST_ERR_CTP_BODY_TOO_LARGE", "error": "Payload Too Large", "message": "Request body is too large" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/passports/{id}": { "get": { "operationId": "getPassport", "tags": [ "Passports" ], "summary": "Fetch a single passport (content-negotiated JSON-LD / AAS / HTML)", "description": "Owner-side alias of the public resolver. Accepts either the passport **UUID** or its caller-supplied **`productId`** (GTIN-14 / GRAI / SKU), scoped to operators bound to your workspace. After the scoped lookup the request is **re-dispatched internally to `GET /passport/{uuid}`**, forwarding all request headers, and the inner response (status, content type, body) is returned as-is.\n\n**Permission:** `passport:read` (read-only — no subscription/402 gate).\n\n**Content negotiation** (substring match on `Accept`): `application/aas+json` → role-filtered AAS environment; `text/html` → SSR passport page; anything else (including `application/json`, `*/*`, or no header) → JSON-LD with `Content-Type: application/ld+json` (the default).\n\n**Access-tier caveat (privilege is resolved from the *forwarded* headers, not the already-authenticated context):** only **database API keys** (`Authorization: Bearer op_dpp_token_…`) of the owning or operator-bound tenant are recognized as owner by the inner resolver. Those callers get the **owner-tier** document: `facilityDetails` and battery restricted keys unmasked, `manufacturingFacility` includes `streetAddress`/`city`/`postalCode`, and DRAFT passports are visible. Callers authenticated with a **JWT session** (login cookie or bearer JWT) receive the **public-redacted** tier instead, and DRAFT passports answer 404 with the forwarded public body (no `success` field).\n\nEvery successful resolution records an anonymized-IP access audit entry.\n\n**Rate limits:** global limiter 100 req/min/IP with `x-ratelimit-*` headers, **plus** the forwarded public resolver's own limiter (30 req/min/IP, no headers) — both 429 shapes are possible (see 429).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID **or** caller-supplied `productId` (GTIN-14 / GRAI / SKU). UUID is tried first, then `productId`.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The resolved passport. Representation depends on the `Accept` header; redaction tier depends on the forwarded credential (see description). The `@id`/`digitalLinkUri` is the stored GS1 Digital Link URI `{base}/01/{productId}/21/{passportUuid}` (AI `8003` instead of `01` for GRAI ids; AI-21 carries the passport UUID at SKU level).", "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "size": "https://w3id.org/dpp/context/v1#size", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "id": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f", "name": "Aurora Textiles GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "5b21cf12-7d24-4a8e-9a3c-2f1f4f4f9d10", "gln": "0950110153000", "name": "Aurora Spinning Mill", "activity": "Spinning", "country": "PT", "streetAddress": "Rua das Flores 12", "city": "Porto", "postalCode": "4050-262" }, "metadata": { "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": [ { "facilityName": "Aurora Spinning Mill", "location": "Porto, PT", "activity": "Spinning" } ] }, "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": [ { "facilityName": "Aurora Spinning Mill", "location": "Porto, PT", "activity": "Spinning" } ] } }, "application/aas+json": { "schema": { "$ref": "#/components/schemas/PassportAasEnvironment" }, "example": { "assetAdministrationShells": [ { "id": "urn:opendpp:aas:9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "idShort": "AAS_09501101530003", "assetInformation": { "assetKind": "Instance", "globalAssetId": "urn:opendpp:asset:f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f:09501101530003", "specificAssetIds": [ { "name": "productId", "value": "09501101530003", "externalSubjectId": { "type": "ExternalReference", "keys": [ { "type": "GlobalReference", "value": "urn:gs1:gln:0950110153000" } ] } }, { "name": "manufacturingFacilityGln", "value": "0950110153000" } ] }, "submodels": [ { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "urn:opendpp:submodel:general:9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d" } ] }, { "type": "ModelReference", "keys": [ { "type": "Submodel", "value": "urn:opendpp:submodel:compliance" } ] } ] } ], "submodels": [ { "id": "urn:opendpp:submodel:general:9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "idShort": "GeneralProductInformation", "semanticId": { "keys": [ { "type": "Submodel", "value": "urn:opendpp:submodel-spec:general:1.0.0" } ] }, "submodelElements": [ { "idShort": "passportId", "modelType": "Property", "valueType": "xs:string", "value": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d" }, { "idShort": "createdAt", "modelType": "Property", "valueType": "xs:dateTime", "value": "2026-06-12T09:41:00.000Z" }, { "idShort": "manufacturingFacilityGln", "modelType": "Property", "valueType": "xs:string", "value": "0950110153000" }, { "idShort": "manufacturingFacilityName", "modelType": "Property", "valueType": "xs:string", "value": "Aurora Spinning Mill" }, { "idShort": "manufacturingFacilityCountry", "modelType": "Property", "valueType": "xs:string", "value": "PT" } ] }, { "id": "urn:opendpp:submodel:compliance", "idShort": "ComplianceMetadata", "submodelElements": [ { "idShort": "category", "modelType": "Property", "valueType": "xs:string", "value": "textiles" }, { "idShort": "originCountry", "modelType": "Property", "valueType": "xs:string", "value": "PT" }, { "idShort": "size", "modelType": "Property", "valueType": "xs:string", "value": "M" } ] } ], "conceptDescriptions": [] } }, "text/html": { "schema": { "type": "string", "description": "Server-rendered passport page (returned when `Accept` contains `text/html`)." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:read`), cross-tenant subdomain mismatch, or an operator-scoped API key addressing another operator's passport (message: `Your access is restricted to Economic Operator: `)." }, "404": { "description": "Two distinct bodies. (1) Standard: the id/productId matched nothing under your workspace — `{success:false, error:\"Not Found\", message:\"Passport with ID or Product ID not found under your Tenant workspace\"}`. (2) Forwarded from the public resolver (note: **no `success` field**): the passport is a DRAFT and the forwarded credential was not recognized as owner (e.g. JWT session); with `Accept: text/html` this case returns an HTML not-found page instead.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "description": "Forwarded public-resolver body (no `success` field).", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } ] }, "examples": { "notInWorkspace": { "summary": "Not found under your workspace (standard envelope)", "value": { "success": false, "error": "Not Found", "message": "Passport with ID or Product ID 09501101530003 not found under your Tenant workspace" } }, "draftNotOwnerForwarded": { "summary": "DRAFT passport, credential not recognized by the inner resolver (forwarded body)", "value": { "error": "Not Found", "message": "No Digital Product Passport found matching identifier: 9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d" } } } }, "text/html": { "schema": { "type": "string", "description": "Forwarded SSR not-found page (DRAFT + unrecognized credential + `Accept: text/html`)." } } } }, "429": { "description": "Two possible sources. (1) Global limiter (100/min/IP): default rate-limit body (`statusCode`/`error`/`message` — no `code` field) with `x-ratelimit-limit`/`x-ratelimit-remaining`/`x-ratelimit-reset` + `retry-after` headers. (2) Forwarded from the inner public resolver's limiter (30/min/IP): two-field body, **no rate-limit headers**.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "description": "Global rate-limit plugin default body (with x-ratelimit-* headers).", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" } } }, { "type": "object", "description": "Forwarded public-resolver limiter body (no `success` field, no headers).", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } ] }, "examples": { "globalLimiter": { "summary": "Global plugin limiter", "value": { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 1 minute" } }, "forwardedPublicLimiter": { "summary": "Forwarded public-resolver limiter", "value": { "error": "Too Many Requests", "message": "Rate limit exceeded. Public passport resolutions are limited to 30 requests per minute." } } } } } }, "500": { "description": "Unexpected failure. A failure inside the scoped lookup is not wrapped by the route and returns the framework's **default** error body (`statusCode`/`error`/`message`, no `success` field); an authentication-layer failure returns the standard envelope with `message: \"Authentication verification failed\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "authVerificationFailed": { "summary": "Authentication-layer failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } }, "put": { "operationId": "updatePassport", "tags": [ "Passports" ], "summary": "Update passport metadata (versioned to history)", "description": "Replaces the passport's `metadata` (the Merkle root and leaf hashes are recomputed) and snapshots the **previous** metadata into the passport's version history (version = count + 1, `changedBy` = user email or `api-key:`, `changeReason` defaults to `\"API Update\"`).\n\n**Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token` (double-submit); Bearer/API-key clients are exempt.\n\n**Lookup:** by passport **UUID only** — `productId` aliasing is NOT supported on this endpoint. The passport must belong to an operator bound to your workspace.\n\n**Draft semantics (`draft` flag):**\n- `draft: true` **skips ESPR validation entirely** and forces `status: \"DRAFT\"` — note this also demotes an already-published (ACTIVE/RECALLED/DECOMMISSIONED) passport back to DRAFT.\n- `draft` absent/false: `metadata` is validated against the ESPR category rules (400 on failure — see below). If the passport was a DRAFT it is **published**: status becomes `ACTIVE`, a `passport.ingested` webhook is enqueued transactionally (public-redacted JSON-LD payload) and an in-app notification is created best-effort afterwards. Live statuses are left untouched.\n\n**Validation divergence:** the 400 validation body here contains `errors` but — unlike `POST /api/v1/passports` — **never a `warnings` array**. `friendlyMessage` is localized via the `lang` query parameter or `Accept-Language` (28 languages, default `en`; unsupported values silently fall back).\n\n**Sealed passports are immutable in place:** if `digitalSeal` is set the update is refused with **403** (message: \"This passport is sealed and cannot be edited in place — editing would invalidate the eIDAS advanced electronic seal. Re-seal explicitly after any change.\").\n\n**Facility:** omit `facilityId` to leave it unchanged; pass `null` or `\"\"` to detach; pass a facility UUID owned by your tenant to attach (400 if not found in your workspace).\n\n**Enrichment:** include the `enrichment` key (even as `null`/`{}`) to overwrite the presentational marketing block; omit it to leave it unchanged. Values are sanitized server-side (truncated/sliced, http(s) URLs only), never rejected.\n\n**Response caveat:** the returned `passport` document is serialized at the **public** redaction tier — `facilityDetails` (and battery restricted keys) appear as `\"[REDACTED - Privileged Access Required]\"` even though you are the owner.\n\n**Rate limits:** global limiter, 100 req/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID. `productId` aliasing is NOT supported here.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "Locale for `friendlyMessage` localization in validation errors. Falls back to `Accept-Language`, then `en`. Unsupported values are ignored (no error).", "schema": { "type": "string", "enum": [ "en", "bg", "hr", "cs", "da", "nl", "et", "fi", "fr", "de", "el", "hu", "ga", "it", "lv", "lt", "mt", "pl", "pt", "ro", "sk", "sl", "es", "sv", "no", "is", "uk", "tr" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportUpdateRequest" }, "example": { "metadata": { "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic cotton", "percentage": 80 }, { "material": "Recycled polyester", "percentage": 20 } ], "fiberComposition": [ { "fiber": "cotton", "percentage": 80 }, { "fiber": "polyester", "percentage": 20 } ], "careInstructions": "Machine wash cold, line dry", "size": "M", "facilityDetails": [ { "facilityName": "Aurora Spinning Mill", "location": "Porto, PT", "activity": "Spinning", "eudrPlots": [ { "plotId": "PLOT-001", "polygonType": "point", "coordinates": [ { "lat": 41.1579, "lng": -8.6291 } ] } ], "traceabilityDocs": [ { "documentName": "GOTS scope certificate", "documentHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "documentUrl": "https://docs.aurora-textiles.example/gots.pdf" } ] } ], "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "GOTS", "referenceNumber": "GOTS-2026-0042", "issuer": "Control Union", "validUntil": "2027-05-31" } ] } }, "changeReason": "Updated fiber composition after supplier audit", "facilityId": "5b21cf12-7d24-4a8e-9a3c-2f1f4f4f9d10" } } } }, "responses": { "200": { "description": "Updated (or published) passport. `message` is `\"Draft published\"` on a first publish, otherwise `\"Digital Product Passport successfully updated and history versioned\"`. The `passport` document is public-tier redacted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportUpdateResponse" }, "example": { "success": true, "message": "Digital Product Passport successfully updated and history versioned", "passport": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "materialComposition": "https://w3id.org/dpp/context/v1#materialComposition", "fiberComposition": "https://w3id.org/dpp/context/v1#fiberComposition", "careInstructions": "https://w3id.org/dpp/context/v1#careInstructions", "size": "https://w3id.org/dpp/context/v1#size", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails", "regulatoryCompliance": "https://w3id.org/dpp/context/v1#regulatoryCompliance" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "id": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T10:15:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f", "name": "Aurora Textiles GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "5b21cf12-7d24-4a8e-9a3c-2f1f4f4f9d10", "gln": "0950110153000", "name": "Aurora Spinning Mill", "activity": "Spinning", "country": "PT" }, "metadata": { "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic cotton", "percentage": 80 }, { "material": "Recycled polyester", "percentage": 20 } ], "fiberComposition": [ { "fiber": "cotton", "percentage": 80 }, { "fiber": "polyester", "percentage": 20 } ], "careInstructions": "Machine wash cold, line dry", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]", "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "GOTS", "referenceNumber": "GOTS-2026-0042", "issuer": "Control Union", "validUntil": "2027-05-31" } ] } }, "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic cotton", "percentage": 80 }, { "material": "Recycled polyester", "percentage": 20 } ], "fiberComposition": [ { "fiber": "cotton", "percentage": 80 }, { "fiber": "polyester", "percentage": 20 } ], "careInstructions": "Machine wash cold, line dry", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]", "regulatoryCompliance": { "ceMarking": true, "certificates": [ { "name": "GOTS", "referenceNumber": "GOTS-2026-0042", "issuer": "Control Union", "validUntil": "2027-05-31" } ] } } } } } }, "400": { "description": "Either a plain Bad Request — body is not a JSON object; `metadata` missing/not an object; `facilityId` not found in your workspace (`Facility not found in your Tenant workspace`) — or an ESPR validation failure. **Divergence:** unlike `POST /api/v1/passports`, the validation body has NO `warnings` array.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PassportUpdateValidationError" } ] }, "examples": { "badRequest": { "summary": "metadata missing or not an object", "value": { "success": false, "error": "Bad Request", "message": "metadata payload must be a valid object" } }, "validationFailed": { "summary": "ESPR category validation failed (no warnings key)", "value": { "success": false, "error": "Validation Failed", "message": "Dynamic metadata payload failed ESPR category compliance validation", "errors": [ { "path": "fiberComposition", "message": "fiberComposition percentages sum to 95, expected 100 (±0.1)", "friendlyMessage": "Fiber Composition: the listed fiber percentages must add up to 100%." } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:update`), missing/invalid CSRF token (cookie sessions), cross-tenant subdomain mismatch, operator-scoped key restriction (`Your access is restricted to Economic Operator: `), **or the passport is sealed** — sealed passports cannot be edited in place (message: \"This passport is sealed and cannot be edited in place — editing would invalidate the eIDAS advanced electronic seal. Re-seal explicitly after any change.\")." }, "404": { "$ref": "#/components/responses/NotFound", "description": "No passport with this UUID under an operator bound to your workspace. Message: `Passport with ID not found under your Tenant workspace`." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "History snapshot or transactional update failure returns the standard envelope (`message` may echo the internal error text or fall back to \"Failed to update passport\"). Unexpected server error. Unhandled errors are normalized by the global error handler to the standard envelope with the generic message \"An unexpected error occurred\"; details are logged server-side, never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "standardEnvelope": { "summary": "Update/history failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Failed to update passport" } } } } } } } }, "delete": { "operationId": "deleteDraftPassport", "tags": [ "Passports" ], "summary": "Permanently delete a DRAFT passport", "description": "Hard-deletes a passport **only while it is a DRAFT** (never published, not publicly resolvable, no retention duty). Children (history, access logs, battery units) cascade on delete.\n\nPublished passports (ACTIVE/RECALLED/DECOMMISSIONED) are refused with **409** — they must be decommissioned/archived through the status lifecycle (`PUT /api/v1/passports/{id}/status`) to satisfy the ESPR Art. 9(2) persistence duty.\n\n**Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt.\n\n**Lookup:** by passport **UUID only** (no `productId` aliasing) and only within the passport's **owning tenant** — an operator-binding alone is not sufficient, unlike PUT.\n\n**Rate limits:** global limiter, 100 req/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID. `productId` aliasing is NOT supported here.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Draft deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "const": "Draft passport deleted." } } }, "example": { "success": true, "message": "Draft passport deleted." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:update`), missing/invalid CSRF token (cookie sessions), cross-tenant subdomain mismatch, or operator-scoped key restriction (`Your access is restricted to Economic Operator: `)." }, "404": { "$ref": "#/components/responses/NotFound", "description": "No passport with this UUID owned by your tenant. Message: `Passport not found in your workspace.`" }, "409": { "description": "The passport is not a DRAFT — published passports cannot be hard-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Conflict", "message": "Only draft passports can be deleted. A published passport must be decommissioned/archived to satisfy the persistence duty (ESPR Art. 9(2))." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected failure. A failure in the lookup or delete itself is not wrapped by the route and returns the framework's **default** error body (`statusCode`/`error`/`message`, no `success` field); an authentication-layer failure returns the standard envelope with `message: \"Authentication verification failed\"`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "authVerificationFailed": { "summary": "Authentication-layer failure (standard envelope)", "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } } }, "/api/v1/passports/{id}/seal": { "post": { "operationId": "sealPassport", "tags": [ "Passports" ], "summary": "Apply the tenant's eIDAS advanced electronic seal", "description": "Signs the passport's Merkle root (SHA-256 tree over the key-sorted top-level `metadata` entries) with the tenant's vault-held **ECDSA P-256 (prime256v1)** private key, producing an eIDAS **advanced** electronic seal (this is a local cryptographic seal — NOT a Commission/EU-registry registration, and NOT a qualified seal). The base64 signature is stored as `digitalSeal` together with the signing public key (PEM), the X.509 chain binding the key to the tenant's legal identity (surfaced as `proof.x5c`, leaf first, base64 DER), and — **best-effort, opt-in** — an RFC 3161 trusted timestamp over SHA-256(merkleRoot) (`proof.rfc3161`; a TSA outage or missing configuration never blocks sealing, the field is simply absent).\n\nA `passport.sealed` webhook is enqueued transactionally with the update (payload: the public-redacted JSON-LD document including the full `proof` block).\n\n**Permission:** `passport:seal` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt.\n\n**Lookup:** passport **UUID or `productId`** (UUID tried first), restricted to the passport's **owning tenant**.\n\n**Behavioral caveats:**\n- The route does **not** modify the passport's `status` — despite the success message's \"and published\" wording, a DRAFT stays a DRAFT after sealing. Publish via `PUT /api/v1/passports/{id}` (validated save) instead.\n- Re-sealing an already-sealed passport is allowed and **overwrites** the previous seal/timestamp.\n- Once sealed, in-place metadata edits are refused (403 on `PUT /api/v1/passports/{id}`).\n- Requires the tenant's eIDAS key pair to exist — otherwise 400.\n- The returned `passport` document is serialized at the **public** redaction tier (masked keys keep their true leaf hashes in `proof.redactedLeaves`, so the seal stays offline-verifiable after redaction).\n\n**Rate limits:** global limiter, 100 req/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID **or** caller-supplied `productId` (GTIN-14 / GRAI / SKU). UUID is tried first.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Passport sealed. `digitalSeal` is the base64 ECDSA-P256-SHA256 signature over the Merkle root; the same value appears as `passport.proof.signatureValue`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportSealResponse" }, "example": { "success": true, "message": "Passport sealed with the tenant's eIDAS advanced electronic seal and published.", "digitalSeal": "MEUCIQDOJ9uZ9b1H0u4G7m2X8nF3kqL5wTzVbY1c2d3e4f5g6AIgKxN8mPqRsTuVwXyZ0a1b2c3d4e5f6g7h8i9j0kAbCdE=", "signingPublicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1u2v3w4x5y6z7A8B9C0D1E2F3G4H\n5I6J7K8L9M0N1O2P3Q4R5S6T7U8V9W0X1Y2Z3a4b5c6d7e8f9g0h1i2j3k4l5m6n\n-----END PUBLIC KEY-----\n", "passport": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "size": "https://w3id.org/dpp/context/v1#size", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "id": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "digitalSeal": "MEUCIQDOJ9uZ9b1H0u4G7m2X8nF3kqL5wTzVbY1c2d3e4f5g6AIgKxN8mPqRsTuVwXyZ0a1b2c3d4e5f6g7h8i9j0kAbCdE=", "signingPublicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1u2v3w4x5y6z7A8B9C0D1E2F3G4H\n5I6J7K8L9M0N1O2P3Q4R5S6T7U8V9W0X1Y2Z3a4b5c6d7e8f9g0h1i2j3k4l5m6n\n-----END PUBLIC KEY-----\n", "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": { "@type": [ "MerkleTreeAttestationProof" ], "type": "MerkleTreeAttestationProof", "signatureAlgorithm": "ECDSA-P256-SHA256-over-MerkleRoot", "created": "2026-06-12T09:45:12.000Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://opendpp-node.eu/passport/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d#key-1", "signatureValue": "MEUCIQDOJ9uZ9b1H0u4G7m2X8nF3kqL5wTzVbY1c2d3e4f5g6AIgKxN8mPqRsTuVwXyZ0a1b2c3d4e5f6g7h8i9j0kAbCdE=", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1u2v3w4x5y6z7A8B9C0D1E2F3G4H\n5I6J7K8L9M0N1O2P3Q4R5S6T7U8V9W0X1Y2Z3a4b5c6d7e8f9g0h1i2j3k4l5m6n\n-----END PUBLIC KEY-----\n", "x5c": [ "MIIBszCCAVqgAwIBAgIUEjRWeJq83vEjRWeJq83vEjRWeJo", "MIIBqzCCAVGgAwIBAgIUZYxw9PqrstuvZYxw9Pqrstuvxyz" ], "rfc3161": { "genTime": "2026-06-12T09:45:13.000Z", "token": "MIIKExampleBase64DerEncodedRfc3161TimeStampRespToken" }, "merkleRoot": "7f83b1657ff1fc53b92dc18148a1d65dff20fdcf2e57d8a1f6cbeab6db1ec9f3", "redactedLeaves": { "facilityDetails": "3c9909afec25354d551dae21590bb26e38d53f2173b8d3dc3eee4c047e7ab1c1" } }, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:45:12.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f", "name": "Aurora Textiles GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": null, "metadata": { "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } } }, "400": { "description": "Missing identifier, or the tenant has no eIDAS key pair configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "eIDAS cryptographic keys are not configured for this Tenant. Please generate or rotate keys in your console first." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:seal`), missing/invalid CSRF token (cookie sessions), cross-tenant subdomain mismatch, or operator-scoped key restriction (`Your access is restricted to Economic Operator: `)." }, "404": { "$ref": "#/components/responses/NotFound", "description": "No passport with this UUID/productId owned by your tenant. Message: `No Digital Product Passport found matching identifier: for this tenant`." }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError", "description": "Three variants: key-material lookup failure (\"Database lookup failed while retrieving cryptographic credentials.\"), signing failure (\"Failed to generate the eIDAS digital seal. Please contact support.\" — the raw signing/decryption error is never leaked), or transactional update failure (message may echo the internal error or fall back to \"Failed to synchronize and sign passport payload\")." } } } }, "/api/v1/passports/{id}/status": { "put": { "operationId": "updatePassportStatus", "tags": [ "Passports" ], "summary": "Transition passport lifecycle status (recall / decommission / reactivate)", "description": "Transitions a **published** passport between live lifecycle states. The request body carries only `status` (any other keys are ignored — there is no `reason` field; the history entry's change reason is auto-generated as `Status changed: → `).\n\n**Permission:** `passport:update` (write — subscription gating applies, see 402). Cookie sessions must send `X-CSRF-Token`; Bearer/API-key clients are exempt.\n\n**Lookup:** passport **UUID or `productId`** (UUID tried first), scoped to operators bound to your workspace.\n\n**Effects:**\n- `DECOMMISSIONED` — sets `retentionUntil = now + the configured retention period` (default 15 years), starting the minimum-availability retention clock. The passport stays publicly resolvable.\n- `ACTIVE` (reactivation) — clears `retentionUntil` **and** `archivedAt`.\n- `RECALLED` — marks the product recalled.\n- The status change, the version-history entry (who/when/what) and the webhook enqueue are **transactional**; an in-app notification is created **best-effort after the transaction commits** (a notification failure never affects the response).\n\n**Webhooks:** `RECALLED` enqueues `passport.recalled`; any other transition (`DECOMMISSIONED`, reactivate-to-`ACTIVE`) enqueues `passport.status_updated` — note that `passport.status_updated` is **not** an explicitly subscribable event filter, so only wildcard (`\"*\"`) webhook subscriptions receive it. Payloads are the public-redacted JSON-LD document.\n\n**Caveats:** DRAFT passports are refused with 409 (publish first via a validated `PUT /api/v1/passports/{id}`). Sealed passports CAN change status — `status` is stored alongside the document, not inside the sealed metadata Merkle tree. The returned `passport` document is serialized at the **public** redaction tier.\n\n**Rate limits:** global limiter, 100 req/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID **or** caller-supplied `productId` (GTIN-14 / GRAI / SKU). UUID is tried first.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportStatusUpdateRequest" }, "example": { "status": "DECOMMISSIONED" } } } }, "responses": { "200": { "description": "Status updated. `status` echoes the new lifecycle state; `passport` is the public-tier JSON-LD document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassportStatusUpdateResponse" }, "example": { "success": true, "message": "Passport status successfully updated to DECOMMISSIONED", "status": "DECOMMISSIONED", "passport": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "size": "https://w3id.org/dpp/context/v1#size", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "id": "9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-3f1e-4c2a-9d4b-5e6f7a8b9c0d", "digitalSeal": null, "signingPublicKey": null, "status": "DECOMMISSIONED", "archivedAt": null, "retentionUntil": "2041-06-12T10:02:00.000Z", "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T10:02:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "f2d6a9c1-4b3e-4d2a-8c1f-0a9b8c7d6e5f", "name": "Aurora Textiles GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": null, "metadata": { "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "textiles", "originCountry": "PT", "size": "M", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } } }, "400": { "description": "`status` missing or not one of the allowed values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "status must be one of: ACTIVE, RECALLED, DECOMMISSIONED" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden", "description": "Insufficient permission (`passport:update`), missing/invalid CSRF token (cookie sessions), cross-tenant subdomain mismatch, or operator-scoped key restriction (`Your access is restricted to Economic Operator: `)." }, "404": { "$ref": "#/components/responses/NotFound", "description": "No passport with this UUID/productId under an operator bound to your workspace. Message: `Passport not found`." }, "409": { "description": "The passport is a DRAFT — drafts cannot transition to a live status here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Conflict", "message": "This passport is a draft. Open it and use Save & publish to validate and publish it before changing its status." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error. Unhandled errors are normalized by the global error handler to the standard envelope with the generic message \"An unexpected error occurred\"; details are logged server-side, never returned.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard envelope; `message` is omitted when the internal error carried no text.", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "standardEnvelope": { "summary": "Transactional failure (standard envelope; message optional)", "value": { "success": false, "error": "Internal Server Error", "message": "Transaction failed" } } } } } } } } }, "/passport/{id}": { "get": { "operationId": "resolvePublicPassport", "tags": [ "Public Resolution" ], "summary": "Resolve a passport by UUID (JSON-LD / AAS / HTML)", "description": "Public, content-negotiated resolution of a Digital Product Passport by its server-assigned UUID. Lookup is by primary key only — GTIN/GRAI/serial lookups go through the GS1 Digital Link gateway (`GET /01/{gtin14}`, `GET /8003/{grai}`).\n\n**Content negotiation** (substring match on `Accept`, checked in order): `application/aas+json` (or bare `aas+json`) → role-filtered Asset Administration Shell environment; `text/html` → server-rendered passport page; anything else (including `application/json`, `*/*`, or no header) → JSON-LD (`application/ld+json`, the default). `Vary: Accept` is always set on the 200.\n\n**Access tiers** — no permission string (public endpoint). Credentials are *optional* and never produce 401/402/403 here; an invalid or foreign credential silently degrades to the public tier:\n- **Public** (anonymous): restricted metadata keys (for category `batteries`: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly` — masked only when present) and the owner-only key `facilityDetails` (present-as-placeholder in every non-owner response, even when the underlying metadata never contained it) carry the literal placeholder `[REDACTED - Privileged Access Required]`. Each masked key that exists in the sealed metadata keeps its true Merkle leaf hash in `proof.redactedLeaves`, so the eIDAS seal stays offline-verifiable after redaction; a placeholder-valued key with no `redactedLeaves` entry was never in the sealed metadata and must be excluded when rebuilding the root.\n- **Legitimate interest / authority**: a capability grant token — `dpp_li_…` (tenant-issued) or `dpp_auth_…` (platform-issued, not tenant-revocable) — sent as `Authorization: Bearer ` or `?grant=`, with TENANT or PASSPORT scope covering this passport, unlocks the restricted tier-2 keys. `facilityDetails`, the facility street address and DRAFT passports stay hidden. Grant-unlocked responses add `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer`.\n- **Owner**: a tenant **API key** (`op_dpp_token_…`, shown once at creation) belonging to the owning tenant or to a tenant bound to the passport's economic operator — sent as Bearer or, legacy, as the literal value of the `opendpp_session` cookie. Only API keys are matched on the public resolvers: a Console JWT login session in that cookie does **not** unlock owner tier (it silently resolves as public). Owners see everything, including DRAFT passports, owner-only metadata keys and the facility street address (`manufacturingFacility.streetAddress`/`city`/`postalCode`). In the AAS representation the owner credential's API-key role drives element filtering; a grant maps to the `legitimate_interest` filter tier, anonymous to `public`.\n\nDRAFT passports are hidden from everyone but the owner (404 with a body identical to a true miss). Every resolution is recorded in the passport's access audit log with an anonymized IP.\n\n**Rate limit:** 30 requests/min/IP via a per-process in-memory limiter; its 429 body is the two-field public error shape (no `success` field). This limiter adds no headers of its own — the `x-ratelimit-*` headers still present on responses (including these 429s) belong to the global platform limit (100 req/min/IP, 600/min for known crawler user agents), which applies on top.", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The passport's server-assigned UUID (returned as `id` on creation and embedded as AI-21 in the SKU-level Digital Link URI)." }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^dpp_(li|auth)_[A-Za-z0-9]{20,64}$" }, "description": "Capability grant token (`dpp_li_…` legitimate-interest, `dpp_auth_…` authority) — the inspection-link path for QR-scanning inspectors who cannot set headers. Equivalent to sending the token as `Authorization: Bearer`. Tokens minted by the platform are the prefix followed by 32 hex characters, but the server matches any prefixed token against its stored hashes (the demo workspace's sample tokens use a different suffix), so the pattern here is deliberately loose. Treat as a secret: responses unlocked this way carry `Cache-Control: private, no-store` + `Referrer-Policy: no-referrer`, and the server log redacts the parameter." } ], "responses": { "200": { "description": "The passport in the negotiated representation. `Vary: Accept` always set; `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer` added only when a grant token unlocked the response.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "Always `Accept` — the same URL serves HTML, JSON-LD and AAS." }, "Cache-Control": { "schema": { "type": "string" }, "description": "`private, no-store` — present only when access was unlocked by a grant token." }, "Referrer-Policy": { "schema": { "type": "string" }, "description": "`no-referrer` — present only when access was unlocked by a grant token." } }, "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "gtin": "https://w3id.org/dpp/context/v1#gtin", "batteryCategory": "https://w3id.org/dpp/context/v1#batteryCategory", "chemistry": "https://w3id.org/dpp/context/v1#chemistry", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "detailedPerformance": "https://w3id.org/dpp/context/v1#detailedPerformance", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "id": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "digitalSeal": "MEUCIQDl0n7K0wG7B1k9p2v4S0cQ9X4j8M5n6P7q8R9s0T1uAIgK2L3m4N5o6P7q8R9s0T1u2V3w4X5y6Z7a8B9c0D1e2F4=", "signingPublicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7sB3kFq2nXp9wLm4Rv8tYc1dZh6j\nKe0aGu5iSx3oNl2bPw9rT7vCmD4fHg8qWy1zEjU6kA0sIxLpO5tMnBvR3Q==\n-----END PUBLIC KEY-----\n", "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": { "@type": [ "MerkleTreeAttestationProof" ], "type": "MerkleTreeAttestationProof", "signatureAlgorithm": "ECDSA-P256-SHA256-over-MerkleRoot", "created": "2026-06-12T09:41:00.000Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://opendpp-node.eu/passport/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b#key-1", "signatureValue": "MEUCIQDl0n7K0wG7B1k9p2v4S0cQ9X4j8M5n6P7q8R9s0T1uAIgK2L3m4N5o6P7q8R9s0T1u2V3w4X5y6Z7a8B9c0D1e2F4=", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7sB3kFq2nXp9wLm4Rv8tYc1dZh6j\nKe0aGu5iSx3oNl2bPw9rT7vCmD4fHg8qWy1zEjU6kA0sIxLpO5tMnBvR3Q==\n-----END PUBLIC KEY-----\n", "x5c": [ "MIIB2TCCAX6gAwIBAgIUTGVhZkNlcnRFeGFtcGxlRGF0YTAKBggqhkjOPQQDAjAgMR4wHAYDVQQDDBVPcGVuRFBQIFNlYWwgQ0EgKERlbW8p", "MIIBszCCAVmgAwIBAgIUQ2FDZXJ0RXhhbXBsZURhdGFCYXNlNjQwCgYIKoZIzj0EAwIwIDEeMBwGA1UEAwwVT3BlbkRQUCBTZWFsIENBIChEZW1vKQ" ], "rfc3161": { "genTime": "2026-06-12T09:41:02.000Z", "token": "MIIKExampleBase64DerEncodedRfc3161TimeStampRespToken" }, "merkleRoot": "8c4f9d2e6a1b7c3f5e0d8a4b2c6f1e9d7a3b5c8f0e2d4a6b9c1f3e5d7a0b2c4f", "redactedLeaves": { "detailedPerformance": "f3a19c7e5b2d8f4a6c0e1d9b7a3f5c2e8d4b6a0c9f1e3d5b7a2c4f6e8d0b1a3c", "facilityDetails": "0b7c4f2e9d1a6b3c8f5e0d7a4b1c6f3e9d2a5b8c0f7e4d1a6b3c9f5e2d8a0b4c" } }, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40", "name": "Voltaic Cells Manufacturing GmbH", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" }, "manufacturingFacility": { "@type": "Facility", "id": "7c1e5a2d-9b4f-4c8e-a3d6-2f8b0e4c9a71", "gln": "0950110153007", "name": "Voltaic Gigafactory Brandenburg", "activity": "cell assembly", "country": "DE" }, "metadata": { "category": "batteries", "gtin": "09501101530003", "batteryCategory": "ev", "chemistry": "NMC 811", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "gtin": "09501101530003", "batteryCategory": "ev", "chemistry": "NMC 811", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" } }, "application/aas+json": { "schema": { "$ref": "#/components/schemas/AasEnvironment" }, "example": { "assetAdministrationShells": [ { "id": "urn:opendpp:aas:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "AAS_09501101530003", "assetInformation": { "assetKind": "Instance", "globalAssetId": "urn:opendpp:asset:4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40:09501101530003" } } ], "submodels": [ { "id": "urn:opendpp:submodel:general:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "GeneralProductInformation" }, { "id": "urn:opendpp:submodel:compliance", "idShort": "ComplianceMetadata" }, { "id": "urn:opendpp:submodel:security-seal:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "eidasVerificationSeal" } ], "conceptDescriptions": [] } }, "text/html": { "schema": { "type": "string", "description": "Server-rendered passport page (owner credentials see the full owner view)." } } } }, "400": { "description": "Passport identifier missing. (Defensive guard — not reachable through normal routing, since the path parameter is required.) Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Bad Request", "message": "Passport identifier must be provided" } } } }, "404": { "description": "No passport with that UUID — or the passport is a DRAFT and the caller is not owner-tier (identical body, deliberate). `Accept: text/html` gets an SSR not-found page instead of JSON. Body omits the `success` field. (This route does not set `Vary` on the 404.) Separately, a request on an unknown tenant workspace host receives a platform-level JSON 404 (`No tenant company found for subdomain: …`) before resolution runs — that host check applies to every documented path except `/health`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "message": "No Digital Product Passport found matching identifier: 9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b" } }, "text/html": { "schema": { "type": "string", "description": "SSR not-found page." } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/01/{gtin14}": { "get": { "operationId": "resolveGs1Gtin", "tags": [ "Public Resolution" ], "summary": "GS1 Digital Link resolution by GTIN-14 (AI 01)", "description": "Unified GS1 Digital Link gateway, GTIN branch. The GTIN-14 is matched against `metadata.gtin`, `metadata.grai`, or the passport's `productId`. On tenant workspaces (`https://{tenant}.opendpp-node.eu`) the lookup is scoped to that tenant — an unknown subdomain returns 404. Without a tenant scope, a GTIN matching more than one passport is rejected with 400 (ambiguous); disambiguate via a brand subdomain (the `?subdomain=` query override is honoured in non-production environments only).\n\nContent negotiation (JSON-LD default / `application/aas+json` / `text/html`, `Vary: Accept` always set), access tiers (public / `dpp_li_…`·`dpp_auth_…` grant via Bearer or `?grant=` / owner = a tenant **API key** sent as Bearer or, legacy, as the literal `opendpp_session` cookie value — Console JWT login sessions do **not** unlock owner tier), DRAFT hiding, access-audit logging (anonymized IP), and grant response headers (`Cache-Control: private, no-store`, `Referrer-Policy: no-referrer`) are identical to `GET /passport/{id}` — see that operation for the full tier semantics. No permission string (public endpoint); invalid credentials silently degrade to the public tier, never 401/403.\n\nThe gateway also accepts additional GS1 AI key/value path pairs after the GTIN; the only one acted on is AI 21 (serial) — documented separately as `GET /01/{gtin14}/21/{serial}`. (The underlying route is `GET /{ai}/*`; AI prefixes other than `01` and `8003` get a 400.)\n\n**Rate limit:** 30 requests/min/IP, per-process in-memory limiter; two-field 429 body without `success`. The limiter adds no headers of its own — `x-ratelimit-*` headers on responses come from the global platform limit (100 req/min/IP), which applies on top.", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "gtin14", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{14}$" }, "description": "GTIN-14: exactly 14 digits with a valid GS1 modulo-10 check digit (the check digit is validated server-side — the pattern alone is not sufficient)." }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^dpp_(li|auth)_[A-Za-z0-9]{20,64}$" }, "description": "Capability grant token (`dpp_li_…` / `dpp_auth_…`); equivalent to `Authorization: Bearer`. Minted tokens are the prefix + 32 hex characters, but the server matches any prefixed token against stored hashes, so the pattern is deliberately loose. Treat as a secret — grant-unlocked responses are `private, no-store` and the parameter is redacted from logs." } ], "responses": { "200": { "description": "The matched passport in the negotiated representation (same envelope as `GET /passport/{id}`).", "headers": { "Vary": { "schema": { "type": "string" }, "description": "Always `Accept`." }, "Cache-Control": { "schema": { "type": "string" }, "description": "`private, no-store` — only when a grant token unlocked the response." }, "Referrer-Policy": { "schema": { "type": "string" }, "description": "`no-referrer` — only when a grant token unlocked the response." } }, "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "gtin": "https://w3id.org/dpp/context/v1#gtin", "chemistry": "https://w3id.org/dpp/context/v1#chemistry", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "detailedPerformance": "https://w3id.org/dpp/context/v1#detailedPerformance", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "id": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40", "name": "Voltaic Cells Manufacturing GmbH", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" }, "manufacturingFacility": { "@type": "Facility", "id": "7c1e5a2d-9b4f-4c8e-a3d6-2f8b0e4c9a71", "gln": "0950110153007", "name": "Voltaic Gigafactory Brandenburg", "activity": "cell assembly", "country": "DE" }, "metadata": { "category": "batteries", "gtin": "09501101530003", "chemistry": "NMC 811", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "gtin": "09501101530003", "chemistry": "NMC 811", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" } }, "application/aas+json": { "schema": { "$ref": "#/components/schemas/AasEnvironment" }, "example": { "assetAdministrationShells": [ { "id": "urn:opendpp:aas:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "AAS_09501101530003", "assetInformation": { "assetKind": "Instance", "globalAssetId": "urn:opendpp:asset:4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40:09501101530003" } } ], "submodels": [ { "id": "urn:opendpp:submodel:general:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "GeneralProductInformation" }, { "id": "urn:opendpp:submodel:compliance", "idShort": "ComplianceMetadata" }, { "id": "urn:opendpp:submodel:security-seal:9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "idShort": "eidasVerificationSeal" } ], "conceptDescriptions": [] } }, "text/html": { "schema": { "type": "string", "description": "Server-rendered passport page." } } } }, "400": { "description": "Invalid GTIN-14 (must be 14 digits with a valid modulo-10 check digit) or — when no tenant scope is in play and no AI-21 serial was given — an ambiguous lookup matching multiple passports. Bodies omit the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidGtin": { "summary": "Check-digit / format failure", "value": { "error": "Bad Request", "message": "Invalid GS1 GTIN format. Standard GS1 Digital Link resolution under AI 01 requires a numeric-only GTIN of exactly 14 digits with a valid modulo-10 check digit. Got: \"09501101530009\"" } }, "ambiguous": { "summary": "Multiple passports match (no tenant scope)", "value": { "error": "Bad Request", "message": "GS1 Digital Link lookup on /01/:productId is ambiguous. Multiple passports match this identifier. A brand-specific subdomain (e.g., brand.opendpp.eu) or a ?subdomain=... query parameter is required." } } } } } }, "404": { "description": "No passport matches the identifier (content-negotiated: HTML page for `Accept: text/html`, JSON otherwise; `Vary: Accept` set), a DRAFT match was hidden from a non-owner caller, or the request arrived on an unknown tenant subdomain (JSON only). Bodies omit the `success` field.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "`Accept` — set on the negotiated not-found variant." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "noMatch": { "summary": "Nothing matches the GTIN", "value": { "error": "Not Found", "message": "No Digital Product Passport found matching identifier: 09501101530003" } }, "draftHidden": { "summary": "DRAFT hidden from non-owner", "value": { "error": "Not Found", "message": "No Digital Product Passport found matching that identifier" } }, "unknownSubdomain": { "summary": "Unknown tenant subdomain", "value": { "error": "Not Found", "message": "No tenant company found for subdomain: acme" } } } }, "text/html": { "schema": { "type": "string", "description": "SSR not-found page." } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/01/{gtin14}/21/{serial}": { "get": { "operationId": "resolveGs1GtinSerial", "tags": [ "Public Resolution" ], "summary": "GS1 Digital Link serialised-item redirect (AI 01 + AI 21)", "description": "GS1 Digital Link resolution of an *individual serialised item*. This path never returns a document directly — on success it issues a `302` redirect (the query string, including `?grant=`, is preserved on the `Location` URL):\n\n1. If the GTIN resolves to a SKU/type passport that has a serialised battery unit whose `serialNumber` equals the AI-21 value → `302` to `/unit/{unitId}` (Battery Reg. Art. 77(2) per-unit view).\n2. Otherwise (legacy fallback) the AI-21 value is matched against the passport UUID, `metadata.serialNumber`, or `metadata[\"21\"]`; if a passport matches → `302` to `/passport/{passportId}`.\n3. Otherwise → `404` (content-negotiated).\n\nThe ambiguity check of the bare-GTIN branch is skipped when an AI-21 serial is present. The redirect handler itself never evaluates credentials — access tiers (owner / grant / public) apply at the redirect target; carry the grant in `?grant=` (preserved across the redirect) or re-send the `Authorization` header to the target. On tenant subdomains the lookup is scoped to that tenant (unknown subdomain → 404, JSON only).\n\nNo permission string (public endpoint). **Rate limit:** 30 requests/min/IP (in-memory public limiter; two-field 429 body without `success`). The limiter adds no headers of its own — `x-ratelimit-*` headers come from the global platform limit, which applies on top — and the redirect target counts as a second request against both.", "security": [], "parameters": [ { "name": "gtin14", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{14}$" }, "description": "GTIN-14: exactly 14 digits with a valid GS1 modulo-10 check digit (validated server-side)." }, { "name": "serial", "in": "path", "required": true, "schema": { "type": "string" }, "description": "GS1 AI-21 serial. For serialised battery units this is the unit's physical serial (units are created matching `^[A-Za-z0-9._-]{1,64}$`); the legacy fallback also matches a passport UUID or the passport's `metadata.serialNumber` / `metadata[\"21\"]` value. Percent-encode reserved characters; the segment is URL-decoded before matching." }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^dpp_(li|auth)_[A-Za-z0-9]{20,64}$" }, "description": "Capability grant token. Not evaluated by this redirect handler — it is preserved on the `Location` URL and takes effect at the redirect target." } ], "responses": { "302": { "description": "Redirect to the resolved resource. `Location` is `/unit/{unitId}` (serialised unit found) or `/passport/{passportId}` (legacy serial fallback), with the original query string appended. No body.", "headers": { "Location": { "schema": { "type": "string" }, "description": "Relative redirect target, e.g. `/unit/5d8e2c41-7b9a-4e3f-8c2d-6a1f0b9e4d72?grant=dpp_li_...` or `/passport/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b`." } } }, "400": { "description": "Invalid GTIN-14 (format / modulo-10 check digit). Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Bad Request", "message": "Invalid GS1 GTIN format. Standard GS1 Digital Link resolution under AI 01 requires a numeric-only GTIN of exactly 14 digits with a valid modulo-10 check digit. Got: \"09501101530009\"" } } } }, "404": { "description": "Neither a serialised unit nor a fallback passport matches (content-negotiated HTML/JSON, `Vary: Accept`), or unknown tenant subdomain (JSON only). Bodies omit the `success` field.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "`Accept` — set on the negotiated not-found variant." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "message": "No Digital Product Passport found matching identifier: 09501101530003" } }, "text/html": { "schema": { "type": "string", "description": "SSR not-found page." } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/8003/{grai}": { "get": { "operationId": "resolveGs1Grai", "tags": [ "Public Resolution" ], "summary": "GS1 Digital Link resolution by GRAI (AI 8003)", "description": "Unified GS1 Digital Link gateway, GRAI branch (Global Returnable Asset Identifier). The GRAI is matched against `metadata.gtin`, `metadata.grai`, or the passport's `productId`. Everything else — content negotiation (JSON-LD default / `application/aas+json` / `text/html`, `Vary: Accept`), access tiers (public / grant `dpp_li_…`·`dpp_auth_…` via Bearer or `?grant=` / owner = tenant API key as Bearer or legacy `opendpp_session` cookie value, never a Console JWT session), DRAFT hiding, tenant-subdomain scoping, the no-tenant-scope ambiguity 400, access-audit logging, grant response headers, and the 30 req/min/IP in-memory rate limit (two-field 429 body without `success`; the limiter adds no headers of its own — `x-ratelimit-*` headers come from the global 100 req/min/IP limit, which applies on top) — is identical to `GET /01/{gtin14}`; see that operation and `GET /passport/{id}` for full semantics.\n\nAn additional `/21/{serial}` AI pair after the GRAI behaves exactly like `GET /01/{gtin14}/21/{serial}` (302 redirect to `/unit/{id}` or `/passport/{id}`). No permission string (public endpoint).", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "grai", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{14}[A-Za-z0-9]{0,16}$", "minLength": 14, "maxLength": 30 }, "description": "GRAI: a 14-digit numeric asset identifier with a valid GS1 modulo-10 check digit (validated server-side), followed by an optional alphanumeric serial component of up to 16 characters (total length 14-30)." }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^dpp_(li|auth)_[A-Za-z0-9]{20,64}$" }, "description": "Capability grant token (`dpp_li_…` / `dpp_auth_…`); equivalent to `Authorization: Bearer`. Minted tokens are the prefix + 32 hex characters; the server matches any prefixed token against stored hashes. Treat as a secret." } ], "responses": { "200": { "description": "The matched passport in the negotiated representation (same envelope as `GET /passport/{id}`).", "headers": { "Vary": { "schema": { "type": "string" }, "description": "Always `Accept`." }, "Cache-Control": { "schema": { "type": "string" }, "description": "`private, no-store` — only when a grant token unlocked the response." }, "Referrer-Policy": { "schema": { "type": "string" }, "description": "`no-referrer` — only when a grant token unlocked the response." } }, "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "grai": "https://w3id.org/dpp/context/v1#grai", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/8003/09501101530003CRATE001/21/3c7e1f52-8d4a-4b9e-a6c0-5f2d8e1b7a93", "id": "3c7e1f52-8d4a-4b9e-a6c0-5f2d8e1b7a93", "productId": "09501101530003CRATE001", "digitalLinkUri": "https://opendpp-node.eu/8003/09501101530003CRATE001/21/3c7e1f52-8d4a-4b9e-a6c0-5f2d8e1b7a93", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40", "name": "Voltaic Cells Manufacturing GmbH", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" }, "manufacturingFacility": null, "metadata": { "category": "iron-steel", "grai": "09501101530003CRATE001", "originCountry": "DE", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "iron-steel", "grai": "09501101530003CRATE001", "originCountry": "DE", "facilityDetails": "[REDACTED - Privileged Access Required]" } }, "application/aas+json": { "schema": { "$ref": "#/components/schemas/AasEnvironment" }, "example": { "assetAdministrationShells": [ { "id": "urn:opendpp:aas:3c7e1f52-8d4a-4b9e-a6c0-5f2d8e1b7a93", "idShort": "AAS_09501101530003CRATE001", "assetInformation": { "assetKind": "Instance", "globalAssetId": "urn:opendpp:asset:4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40:09501101530003CRATE001" } } ], "submodels": [ { "id": "urn:opendpp:submodel:general:3c7e1f52-8d4a-4b9e-a6c0-5f2d8e1b7a93", "idShort": "GeneralProductInformation" }, { "id": "urn:opendpp:submodel:compliance", "idShort": "ComplianceMetadata" } ], "conceptDescriptions": [] } }, "text/html": { "schema": { "type": "string", "description": "Server-rendered passport page." } } } }, "400": { "description": "Invalid GRAI (format / check digit) or — without tenant scope and AI-21 serial — an ambiguous lookup. Bodies omit the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidGrai": { "summary": "Format / check-digit failure", "value": { "error": "Bad Request", "message": "Invalid GS1 GRAI format. Standard GS1 Digital Link resolution under AI 8003 requires a 14-digit asset identifier (with a valid modulo-10 check digit) followed by an optional alphanumeric serial component of up to 16 characters. Got: \"0950110153000\"" } }, "ambiguous": { "summary": "Multiple passports match (no tenant scope)", "value": { "error": "Bad Request", "message": "GS1 Digital Link lookup on /8003/:productId is ambiguous. Multiple passports match this identifier. A brand-specific subdomain (e.g., brand.opendpp.eu) or a ?subdomain=... query parameter is required." } } } } } }, "404": { "description": "No passport matches (content-negotiated HTML/JSON, `Vary: Accept`), DRAFT hidden from non-owner, or unknown tenant subdomain (JSON only). Bodies omit the `success` field.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "`Accept` — set on the negotiated not-found variant." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "message": "No Digital Product Passport found matching identifier: 09501101530003CRATE001" } }, "text/html": { "schema": { "type": "string", "description": "SSR not-found page." } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/unit/{id}": { "get": { "operationId": "resolvePublicBatteryUnit", "tags": [ "Public Resolution" ], "summary": "Resolve an individual serialised battery unit", "description": "Public, content-negotiated view of one individual serialised unit (battery; Reg. (EU) 2023/1542 Art. 77(2)) by its unit UUID, including the embedded SKU/type passport (`ofModel`, masked by the same tier rules as `GET /passport/{id}`).\n\n**Content negotiation:** `Accept` containing `text/html` → server-rendered unit page; everything else → JSON-LD (`application/ld+json`). No AAS representation on this route. `Vary: Accept` always set on the 200.\n\n**Per-unit telemetry is never public** (Annex XIII(2)-(4)): anonymous responses omit `currentState`/`dynamicData` and instead carry a `restrictedData` notice with a `/request-access` pointer. An owner credential — a tenant **API key** (`op_dpp_token_…`) of the owning or operator-bound tenant, sent as Bearer or, legacy, as the literal `opendpp_session` cookie value (a Console JWT login session does **not** unlock owner tier) — or a valid grant token (`dpp_li_…`/`dpp_auth_…` as Bearer or `?grant=`; TENANT, PASSPORT or UNIT scope) unlocks `currentState` and `dynamicData` — up to the 500 most recent events, newest first. Invalid credentials silently degrade to the public tier (never 401/402/403). Grant-unlocked responses add `Cache-Control: private, no-store` + `Referrer-Policy: no-referrer`. No permission string (public endpoint).\n\n**Art. 77(8) tombstone:** once the unit's status is `RECYCLED` (or `ceasedAt` is set) this URL answers `410 Gone` with a minimal tombstone for everyone — grants and owner credentials do NOT override it (the owning tenant retains internal access via `GET /api/v1/units/{id}`).\n\nEvery resolution is access-audit-logged with an anonymized IP. **Rate limit:** 30 requests/min/IP (in-memory public limiter; two-field 429 body without `success`). The limiter adds no headers of its own — `x-ratelimit-*` headers come from the global platform limit, which applies on top.", "security": [ {}, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The battery unit's server-assigned UUID (AI-21 serial resolution via `GET /01/{gtin14}/21/{serial}` redirects here)." }, { "name": "grant", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^dpp_(li|auth)_[A-Za-z0-9]{20,64}$" }, "description": "Capability grant token (`dpp_li_…` / `dpp_auth_…`); equivalent to `Authorization: Bearer`. Minted tokens are the prefix + 32 hex characters; the server matches any prefixed token against stored hashes. Treat as a secret." } ], "responses": { "200": { "description": "The unit document in the negotiated representation. Telemetry keys (`currentState`, `dynamicData`) only for owner/grant tiers; `restrictedData` notice for the anonymous public.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "Always `Accept`." }, "Cache-Control": { "schema": { "type": "string" }, "description": "`private, no-store` — only when a grant token unlocked the response." }, "Referrer-Policy": { "schema": { "type": "string" }, "description": "`no-referrer` — only when a grant token unlocked the response." } }, "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/PublicBatteryUnitJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "BatteryUnit": "https://w3id.org/dpp#BatteryUnit", "serialNumber": "https://w3id.org/dpp#serialNumber", "ofModel": "https://w3id.org/dpp#ofModel", "currentState": "https://w3id.org/dpp#currentState", "dynamicData": "https://w3id.org/dpp#dynamicData", "stateOfHealth": "https://w3id.org/dpp#stateOfHealth", "cycleCount": "https://w3id.org/dpp#cycleCount", "restrictedData": "https://w3id.org/dpp#restrictedData", "repurposedFrom": "https://w3id.org/dpp#repurposedFrom", "successorUnits": "https://w3id.org/dpp#successorUnits" } ], "@type": "BatteryUnit", "@id": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "id": "5d8e2c41-7b9a-4e3f-8c2d-6a1f0b9e4d72", "serialNumber": "BATT-2026-000451", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/BATT-2026-000451", "status": "IN_SERVICE", "manufacturedAt": "2026-01-15T08:00:00.000Z", "repurposedFrom": null, "successorUnits": [], "ofModel": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "gtin": "https://w3id.org/dpp/context/v1#gtin", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "detailedPerformance": "https://w3id.org/dpp/context/v1#detailedPerformance", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "id": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003/21/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-01T08:00:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "4f6f0b9c-2d71-4f3a-8e5b-1c9d7a2e6b40", "name": "Voltaic Cells Manufacturing GmbH", "regId": "EU-DEFAULT-001", "role": "MANUFACTURER" }, "manufacturingFacility": { "@type": "Facility", "id": "7c1e5a2d-9b4f-4c8e-a3d6-2f8b0e4c9a71", "gln": "0950110153007", "name": "Voltaic Gigafactory Brandenburg", "activity": "cell assembly", "country": "DE" }, "metadata": { "category": "batteries", "gtin": "09501101530003", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "gtin": "09501101530003", "originCountry": "DE", "detailedPerformance": "[REDACTED - Privileged Access Required]", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "restrictedData": { "reason": "LEGITIMATE_INTEREST_REQUIRED", "reference": "Regulation (EU) 2023/1542, Annex XIII(2)-(4)", "description": "Per-unit dynamic data (state of health, cycle counts, negative events, temperature) is accessible only to persons with a legitimate interest and to authorities.", "howToRequest": "/request-access?unit=5d8e2c41-7b9a-4e3f-8c2d-6a1f0b9e4d72" }, "createdAt": "2026-01-15T09:00:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } }, "text/html": { "schema": { "type": "string", "description": "Server-rendered unit page (telemetry sections only for owner/grant tiers)." } } } }, "404": { "description": "No unit with that id (a malformed UUID also resolves to this 404). Content-negotiated: HTML page for `Accept: text/html`, JSON otherwise; `Vary: Accept` set. Body omits the `success` field. A request on an unknown tenant workspace host receives the platform-level JSON 404 (`No tenant company found for subdomain: …`) before this handler runs.", "headers": { "Vary": { "schema": { "type": "string" }, "description": "`Accept`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not Found", "message": "No serialised unit found matching identifier: 5d8e2c41-7b9a-4e3f-8c2d-6a1f0b9e4d72" } }, "text/html": { "schema": { "type": "string", "description": "SSR not-found page." } } } }, "410": { "description": "Gone — the unit was RECYCLED (or `ceasedAt` is set): the battery passport has ceased to exist (Art. 77(8)). A minimal tombstone is returned to everyone; grants and owner credentials do not override it. Content-negotiated: HTML tombstone for `Accept: text/html`, JSON-LD otherwise.", "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/BatteryUnitTombstoneJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "BatteryUnit": "https://w3id.org/dpp#BatteryUnit", "serialNumber": "https://w3id.org/dpp#serialNumber", "ceasedAt": "https://w3id.org/dpp#ceasedAt" } ], "@type": "BatteryUnit", "@id": "https://opendpp-node.eu/01/09501101530003/21/BATT-2024-000118", "id": "1f4c8a92-6e3d-4b7a-9d5c-8e2a0f6b3c14", "serialNumber": "BATT-2024-000118", "status": "RECYCLED", "ceasedAt": "2026-03-01T10:00:00.000Z", "notice": "This battery has been recycled. Its battery passport has ceased to exist (Regulation (EU) 2023/1542, Art. 77(8)).", "ofModelUrl": "/passport/9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b" } }, "text/html": { "schema": { "type": "string", "description": "SSR tombstone page." } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/.well-known/opendpp-seal-ca.pem": { "get": { "operationId": "getSealCaCertificate", "tags": [ "eIDAS Keys" ], "summary": "Download the platform seal-CA certificate (PEM)", "description": "Downloads the platform seal-CA certificate as PEM. Third parties pin this CA to validate the `x5c` certificate chains embedded in sealed-passport `proof` blocks — the chain's leaf certificate binds a tenant's signing key to its legal identity (eIDAS Art. 36(1)(b) creator identification; the seal is an eIDAS *advanced*, not qualified, electronic seal). The certificate is provisioned server-side on first use.\n\nNo authentication, no permission (public endpoint). Successful responses carry `Cache-Control: public, max-age=3600`. Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 before this handler runs.\n\n**Rate limit:** 30 requests/min/IP via the in-memory public limiter — note that this route's 429 body carries ONLY `{\"error\": \"Too Many Requests\"}` (no `message`, no `success`), unlike the other public resolvers. The global platform limit (100 req/min/IP) applies on top: a global-limit 429 carries the platform's default `{statusCode, error, message}` body instead, and the global limiter's `x-ratelimit-*` headers appear on every response from this route. Returns `503` if the seal CA cannot be provisioned or loaded.", "security": [], "responses": { "200": { "description": "The CA certificate, PEM-encoded.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "`public, max-age=3600`." } }, "content": { "application/x-pem-file": { "schema": { "type": "string", "description": "X.509 CA certificate in PEM encoding." }, "example": "-----BEGIN CERTIFICATE-----\nMIIBszCCAVmgAwIBAgIUQ2FDZXJ0RXhhbXBsZURhdGFCYXNlNjQwCgYIKoZIzj0E\nAwIwIDEeMBwGA1UEAwwVT3BlbkRQUCBTZWFsIENBIChEZW1vKQ==\n-----END CERTIFICATE-----\n" } } }, "429": { "description": "Rate limited (30/min/IP in-memory public limiter). This route's 429 body has ONLY the `error` field — no `message`, no `success`. (Any `x-ratelimit-*` headers on the response belong to the global platform limiter.)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "const": "Too Many Requests" } } }, "example": { "error": "Too Many Requests" } } } }, "503": { "description": "Seal CA not available (provisioning/load failure). Body omits the `success` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Service Unavailable", "message": "Seal CA not available" } } } } } } }, "/api/v1/schemas/{category}": { "get": { "operationId": "getSectorSchema", "tags": [ "Schemas & Vocabulary" ], "summary": "Get the ESPR metadata schema for a product category", "description": "Returns the machine-readable ESPR `metadata` schema for a product category.\n\n**Default representation** (any `Accept` NOT containing `application/ld+json`): the category's JSON Schema **draft-07** document, served as `application/schema+json`, with each known field annotated server-side with a plain-English `description` (the annotations are AJV-ignored — validation behavior is unchanged). **With `Accept: application/ld+json`:** a small JSON-LD `@context` for the category vocabulary instead. Note: the route does not set `Vary: Accept`.\n\nThe category path segment is lower-cased before lookup. Machine-readable schemas exist for **5** of the 9 ESPR categories: `textiles`, `batteries`, `electronics`, `chemicals`, `construction`. The remaining 4 categories accepted by passport metadata validation (`cosmetics`, `toys`, `iron-steel`, `aluminium`) are validated by built-in server rules and currently return `404` from this endpoint.\n\nNo authentication, no permission (public endpoint). No custom rate limiter — only the global platform limit applies (100 req/min/IP, standard `x-ratelimit-*` headers). Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 (`No tenant company found for subdomain: …`, no `success` field) before this handler runs.", "security": [], "parameters": [ { "name": "category", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "textiles", "batteries", "electronics", "chemicals", "construction", "cosmetics", "toys", "iron-steel", "aluminium" ] }, "description": "ESPR product category (case-insensitive). Only `textiles`, `batteries`, `electronics`, `chemicals` and `construction` have published JSON Schemas; `cosmetics`, `toys`, `iron-steel` and `aluminium` return 404 here (their validation rules are built into the server)." } ], "responses": { "200": { "description": "The category schema (default) or its JSON-LD vocabulary context (`Accept: application/ld+json`).", "content": { "application/schema+json": { "schema": { "$ref": "#/components/schemas/SectorJsonSchemaDocument" }, "example": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Chemicals compliance schema", "type": "object", "required": [ "category", "materialComposition", "originCountry", "facilityDetails", "regulatoryCompliance", "hazardClassification", "safetyDatasheetUrl", "presenceOfSVHC" ], "properties": { "category": { "type": "string", "enum": [ "chemicals" ], "description": "Product sector for this passport: one of textiles, batteries, electronics, chemicals or construction. Must match the chosen schema." }, "materialComposition": { "type": "array", "items": { "type": "object", "required": [ "material", "percentage" ], "properties": { "material": { "type": "string", "minLength": 1, "description": "Name of one material in the product, e.g. 'cotton', 'aluminium', 'PET'. Free text, at least one character." }, "percentage": { "type": "number", "minimum": 0.01, "maximum": 100, "description": "Share of this item as a percentage (0.01-100). Material/fibre percentages should add up to 100 for the whole product." } } }, "description": "List the materials in the product, each with its name and weight percentage; required under ESPR for transparency and recycling." }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country where the product was made or assembled. Two-letter ISO 3166 code in capitals, e.g. DE, FR, CN." }, "facilityDetails": { "type": "array", "items": { "type": "object", "required": [ "facilityName", "location", "activity" ], "properties": { "facilityName": { "type": "string", "minLength": 1, "description": "Name of the supply-chain facility or company at this site, e.g. 'Acme Weaving Mill'." }, "location": { "type": "string", "minLength": 1, "description": "Where the facility is, e.g. city and country or full address; used for supply-chain traceability." }, "activity": { "type": "string", "minLength": 1, "description": "What this facility does in the chain, e.g. 'spinning', 'assembly', 'final manufacturing'." }, "eori": { "type": "string", "description": "Optional EU EORI number identifying the operator for customs, e.g. DE123456789012345. Leave blank if none." }, "eudrPlots": { "type": "array", "description": "Land plots where deforestation-risk commodities were produced, with geolocation; required by EUDR to prove deforestation-free sourcing." } } }, "description": "List of sites in the supply chain (factory, processor, etc.), each with name, location and activity; supports traceability duties." }, "regulatoryCompliance": { "type": "object", "required": [ "ceMarking", "certificates" ], "properties": { "ceMarking": { "type": "boolean", "description": "True/false: does the product carry CE marking declaring conformity with applicable EU product law?" }, "certificates": { "type": "array", "items": { "type": "object", "required": [ "name", "referenceNumber", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the certificate or standard, e.g. 'OEKO-TEX Standard 100' or 'ISO 9001'." }, "referenceNumber": { "type": "string", "minLength": 1, "description": "The certificate's official number or ID so it can be looked up with the issuer." }, "issuer": { "type": "string", "minLength": 1, "description": "Organisation that issued the certificate, e.g. the notified body or testing lab." }, "validUntil": { "type": "string", "description": "Expiry date of the certificate (e.g. 2026-12-31). Leave blank if it does not expire." } } }, "description": "List of certificates or approvals held for the product, each with a name, reference number and issuer." } }, "description": "Block confirming the product meets EU rules: CE marking status and any certificates held." }, "hazardClassification": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "List of CLP/GHS hazard classes or H-statements for the chemical, e.g. 'Flammable liquid', 'H315'." }, "safetyDatasheetUrl": { "type": "string", "format": "uri", "description": "Web link (https) to the chemical's Safety Data Sheet (SDS), required under REACH/CLP." }, "presenceOfSVHC": { "type": "boolean", "description": "True/false: does the product contain Substances of Very High Concern above the REACH notification threshold?" } } } }, "application/ld+json": { "schema": { "$ref": "#/components/schemas/SectorVocabularyContext" }, "example": { "@context": { "@vocab": "https://w3id.org/opendpp/schemas/chemicals#", "id": "@id", "type": "@type", "category": "https://w3id.org/opendpp#category", "materialComposition": "https://w3id.org/opendpp#materialComposition", "originCountry": "https://w3id.org/opendpp#originCountry", "facilityDetails": "https://w3id.org/opendpp#facilityDetails", "regulatoryCompliance": "https://opendpp.org/compliance#regulatoryCompliance" } } } } }, "404": { "$ref": "#/components/responses/NotFound", "description": "Unknown category, or one of the 4 schema-less ESPR categories (`cosmetics`, `toys`, `iron-steel`, `aluminium`). Body: `{\"success\": false, \"error\": \"Not Found\", \"message\": \"Schema not found for category: \"}`." }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/context/v1": { "get": { "operationId": "getJsonLdContext", "tags": [ "Schemas & Vocabulary" ], "summary": "W3C JSON-LD context document for passport terms", "description": "Serves the resolvable W3C JSON-LD `@context` document for the core Digital Product Passport terms referenced from every passport JSON-LD representation. Static, fixed content (`application/ld+json`): maps the DPP terms to `https://w3id.org/dpp#…` IRIs and `createdAt`/`updatedAt` to schema.org `dateCreated`/`dateModified`.\n\nNo authentication, no permission (public endpoint). No custom rate limiter — only the global platform limit applies (100 req/min/IP, standard `x-ratelimit-*` headers). Like every documented path except `/health`, a request on an unknown tenant workspace host receives a platform-level JSON 404 before this handler runs.", "security": [], "responses": { "200": { "description": "The JSON-LD context document (fixed content).", "content": { "application/ld+json": { "schema": { "$ref": "#/components/schemas/DppJsonLdContextDocument" }, "example": { "@context": { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "proof": "https://w3id.org/dpp#proof", "createdAt": "http://schema.org/dateCreated", "updatedAt": "http://schema.org/dateModified" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Service" ], "summary": "Service health check", "description": "Liveness probe. Always returns 200 with the service identity and the current server time (ISO 8601 UTC with milliseconds). No authentication, no permission. Subject only to the global platform rate limit (100 req/min/IP, 600/min for known crawler user agents; standard `x-ratelimit-*` headers on responses). This is the one path exempt from tenant-subdomain resolution — it answers 200 on any host.", "security": [], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" }, "example": { "status": "OK", "service": "OpenDPP B2B Enterprise Engine", "timestamp": "2026-06-12T09:41:00.000Z" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/passports/{id}/qr": { "get": { "operationId": "getPassportQrCode", "tags": [ "QR Codes" ], "summary": "Export a print-grade GS1 Digital Link QR code for a passport", "description": "Renders the passport's GS1 Digital Link URI (its `digitalLinkUri`, e.g. `https://opendpp-node.eu/01/09501101530003/21/{passportUuid}`) as a print-grade QR code and returns it as a binary file download. The printed carrier resolves through the public GS1 gateway.\n\n**Permission:** `passport:read` (read-only — subscription status is **not** checked on `:read` permissions, so this endpoint never returns 402). Works with a Bearer API key, a Bearer JWT, or the `opendpp_session` cookie — plain same-origin `` downloads are supported for browser sessions.\n\n**Identifier resolution:** `{id}` is matched first against the passport UUID, then against the caller-supplied `productId` (GTIN-14/GRAI/SKU), always scoped to your tenant. Credentials scoped to an Economic Operator receive **403** (`Your access is restricted to Economic Operator: `) when the passport belongs to a different operator.\n\n**QR rendering:** 4-module quiet zone (GS1 guidance); error-correction level per `ecl` (default `Q`, the GS1 recommendation for product labels); `size` is **clamped** to 128–2048 px — out-of-range values are clamped to the nearest bound, not rejected, and fractional values are truncated. The response carries `Content-Disposition: attachment; filename=\"qr-.png\"` (or `.svg`); the filename base is the passport's `productId` with characters outside `[A-Za-z0-9._-]` replaced by `_`, truncated to 80 characters.\n\n**Errors:** an invalid query option returns **400** with one of these exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`. An unknown passport returns **404** with message `Passport not found under your Tenant workspace`.\n\n**Rate limit:** global limiter only — 100 requests/min/IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Passport UUID, or the caller-supplied `productId` (GTIN-14/GRAI/SKU) as a fallback. Resolution is tenant-scoped.", "schema": { "type": "string" }, "examples": { "byUuid": { "summary": "Passport UUID", "value": "9b2fa884-3c1d-4e0a-9f6b-2d7c5a1e8b40" }, "byProductId": { "summary": "GTIN-14 productId", "value": "09501101530003" } } }, { "name": "format", "in": "query", "required": false, "description": "Output image format. Case-insensitive; any other value returns 400 (`format must be png or svg`).", "schema": { "type": "string", "enum": [ "png", "svg" ], "default": "png" } }, { "name": "size", "in": "query", "required": false, "description": "Rendered width in pixels (PNG) / SVG width attribute. Clamped to 128–2048 — out-of-range values are silently clamped, fractions truncated. A non-numeric value returns 400 (`size must be a number`).", "schema": { "type": "integer", "minimum": 128, "maximum": 2048, "default": 1024 } }, { "name": "ecl", "in": "query", "required": false, "description": "QR error-correction level: `M` (~15% recovery), `Q` (~25%, GS1 product-label guidance, default) or `H` (~30%). Case-insensitive; any other value returns 400 (`ecl must be M, Q or H`). `L` is intentionally not offered.", "schema": { "type": "string", "enum": [ "M", "Q", "H" ], "default": "Q" } } ], "responses": { "200": { "description": "QR code image encoding the passport's `digitalLinkUri`. The returned media type follows the `format` query parameter (no `Accept`-header negotiation): `image/png` is a raw PNG bitmap, `size` px wide; `image/svg+xml` is a vector SVG document. Delivered as an attachment download.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"qr-.png\"` or `...svg` — filename base sanitized to `[A-Za-z0-9._-]` (other characters become `_`), max 80 chars.", "schema": { "type": "string" } } }, "content": { "image/png": {}, "image/svg+xml": { "schema": { "type": "string", "description": "Vector SVG document (returned when `format=svg`)." } } } }, "400": { "description": "Invalid query option. Exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "ecl must be M, Q or H" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/units/{id}/qr": { "get": { "operationId": "getBatteryUnitQrCode", "tags": [ "QR Codes" ], "summary": "Export a print-grade QR code for an individual battery unit", "description": "Renders the battery unit's GS1 Digital Link URI as a print-grade QR code — the AI-21 path segment carries the unit's **real physical serial number** (e.g. `https://opendpp-node.eu/01/09501101530003/21/BAT-2026-000123`). This is the carrier each individual battery must wear (per-unit passports, Battery Regulation Art. 77(2)).\n\n**Permission:** `battery:read` (read-only — subscription status is **not** checked on `:read` permissions, so this endpoint never returns 402). Works with a Bearer API key, a Bearer JWT, or the `opendpp_session` cookie.\n\n**Identifier resolution:** `{id}` is the BatteryUnit **UUID only** — unlike the passport QR route there is **no** serial-number fallback. Lookup is tenant-scoped. Credentials scoped to an Economic Operator receive **403** (`Your access is restricted to Economic Operator: `) when the unit's parent passport belongs to a different operator.\n\n**QR rendering:** identical pipeline to the passport QR export — 4-module quiet zone, `ecl` default `Q`, `size` clamped to 128–2048 px (clamped, not rejected; fractions truncated). The response carries `Content-Disposition: attachment; filename=\"qr-.png\"` (or `.svg`); the filename base is the unit's `serialNumber` with characters outside `[A-Za-z0-9._-]` replaced by `_`, truncated to 80 characters.\n\n**Errors:** an invalid query option returns **400** with one of these exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`. An unknown unit returns **404** with message `Battery unit not found under your Tenant workspace`.\n\n**Rate limit:** global limiter only — 100 requests/min/IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "BatteryUnit UUID (primary key). Serial numbers are NOT accepted here.", "schema": { "type": "string" }, "example": "9b2fa884-5e2b-4d1c-8a7f-3e9d0c4b6a21" }, { "name": "format", "in": "query", "required": false, "description": "Output image format. Case-insensitive; any other value returns 400 (`format must be png or svg`).", "schema": { "type": "string", "enum": [ "png", "svg" ], "default": "png" } }, { "name": "size", "in": "query", "required": false, "description": "Rendered width in pixels (PNG) / SVG width attribute. Clamped to 128–2048 — out-of-range values are silently clamped, fractions truncated. A non-numeric value returns 400 (`size must be a number`).", "schema": { "type": "integer", "minimum": 128, "maximum": 2048, "default": 1024 } }, { "name": "ecl", "in": "query", "required": false, "description": "QR error-correction level: `M` (~15% recovery), `Q` (~25%, GS1 product-label guidance, default) or `H` (~30%). Case-insensitive; any other value returns 400 (`ecl must be M, Q or H`).", "schema": { "type": "string", "enum": [ "M", "Q", "H" ], "default": "Q" } } ], "responses": { "200": { "description": "QR code image encoding the unit's `digitalLinkUri` (AI-21 = real physical serial). The returned media type follows the `format` query parameter (no `Accept`-header negotiation): `image/png` is a raw PNG bitmap, `size` px wide; `image/svg+xml` is a vector SVG document. Delivered as an attachment download.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"qr-.png\"` or `...svg` — filename base sanitized to `[A-Za-z0-9._-]` (other characters become `_`), max 80 chars.", "schema": { "type": "string" } } }, "content": { "image/png": {}, "image/svg+xml": { "schema": { "type": "string", "description": "Vector SVG document (returned when `format=svg`)." } } } }, "400": { "description": "Invalid query option. Exact messages: `format must be png or svg`, `size must be a number`, `ecl must be M, Q or H`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "format must be png or svg" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/materials": { "get": { "operationId": "listMaterials", "tags": [ "Schemas & Vocabulary" ], "summary": "List the platform-curated material vocabulary", "description": "Lists active entries from the platform-global material vocabulary that powers the searchable material/fiber/chemistry pickers in the passport form. This is shared reference data, deliberately **not** tenant-scoped, so DPP data stays comparable across tenants.\n\n**Auth:** any authenticated session — Bearer API key, Bearer JWT, or `opendpp_session` cookie. **No specific permission string is required** and subscription status is not checked, so this endpoint never returns 402. On a tenant-subdomain host, credentials belonging to a different tenant receive **403** with message `Cross-tenant access blocked.`.\n\n**Filtering & ordering:** `kind` filters by vocabulary kind — an unrecognized value is **silently ignored** (the filter simply isn't applied; no 400). `search` is a trimmed, case-insensitive substring match on `name` (blank values ignored). Only active entries are returned, ordered by `kind` ascending then `name` ascending. `limit` is clamped to 1–1000 (default 1000); there is no pagination.\n\n**Envelope caveat:** the 200 body is `{ \"materials\": [...] }` — there is **no `success` field** on this endpoint.\n\n**Curation:** this vocabulary is curated by the platform operator — the API is read-only for tenant credentials. Free-text material values in passport metadata remain allowed but are never auto-added to this vocabulary.\n\n**Rate limit:** global limiter only — 100 requests/min/IP (standard `x-ratelimit-*` headers).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Filter by vocabulary kind. Unrecognized values are silently ignored (no error; the filter is not applied).", "schema": { "type": "string", "enum": [ "material", "fiber", "chemistry", "substance", "hazard", "crm" ] } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive substring match on the entry `name` (value is trimmed; blank values ignored).", "schema": { "type": "string" }, "example": "lithium" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of entries to return. Clamped to 1–1000 (out-of-range numeric values are clamped, not rejected); a non-numeric value falls back to the default 1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } } ], "responses": { "200": { "description": "Active vocabulary entries matching the filters, ordered by `kind` then `name` ascending. Note: no `success` field in this envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaterialVocabularyListResponse" }, "example": { "materials": [ { "id": "9b2fa884-3c1d-4e0a-9f6b-2d7c5a1e8b40", "name": "Lithium Iron Phosphate (LFP)", "kind": "chemistry", "casNumber": "15365-14-7", "description": "Cathode chemistry for stationary storage and EV cells" }, { "id": "9b2fa884-77aa-4b2e-8c3d-0f1e2a3b4c5d", "name": "Organic Cotton", "kind": "fiber", "casNumber": null, "description": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/events": { "post": { "operationId": "registerTraceabilityEvent", "tags": [ "Traceability & Audit" ], "summary": "Register a UNTP/EPCIS 2.0 traceability event (Verifiable Credential)", "description": "Registers a supply-chain traceability event carried as a W3C-style UNTP Verifiable Credential and persists it as an EPCIS 2.0 event row scoped to your tenant.\n\n**Permission:** `passport:update` (write operation — subscription gating applies, see 402). When the node operator enforces MFA, writes from user-backed sessions (cookie or Bearer JWT) whose MFA policy requires a second factor (user policy `REQUIRED`, or `DEFAULT` with the workspace's MFA-by-default setting, which is on by default) receive 403 without one; API-key clients are exempt. Cookie-session clients must send the `X-CSRF-Token` header (double-submit with the `opendpp_csrf` cookie); Bearer JWT / API-key clients are exempt.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).\n\n**Validation pipeline (in order):**\n1. *Structural* — the body must be an object containing `credentialSubject`, otherwise 400 `Bad Request`.\n2. *EPCIS rule* — `action` is strictly forbidden on `TransformationEvent` (any non-null value → 400 `Schema Validation Error`).\n3. *Cryptographic* — the ECDSA (P-256 / SHA-256) signature in `proof.proofValue` (base64) is verified over the deterministically canonicalized credential (key-sorted JSON with `proof.proofValue` blanked — OpenDPP's own canonicalization scheme, NOT RFC 8785 JCS, so this is not a conformant W3C Data Integrity suite). The verification key is resolved in trust order: (a) an embedded `proof.verificationMethod.x5c` chain, accepted ONLY when the node has eIDAS trust anchors configured, the chain validates against them, every certificate is currently valid, and the leaf attests the issuer; (b) the registered eIDAS public key of the tenant whose subdomain or company name EXACTLY equals the trailing `:`-segment of the issuer DID. If no key resolves or the signature does not verify → 400 `Cryptographic Verification Failed`.\n4. *Operator scoping* — if your API key is scoped to an Economic Operator, the credential's declared operator DID — the `issuer` DID, or `credentialSubject.responsibleOperatorDid` only when `issuer` is absent — must contain the bound operator's registration id (e.g. `EU-DEFAULT-001`), otherwise 403 with `message: \"Your access is restricted to Economic Operator: ()\"`.\n\n**Persistence:** the stored event id is ALWAYS server-generated (UUID) — the credential's own `id` is never used as the primary key (prevents cross-tenant id squatting); the issuer DID is retained as `issuerDid`. Defaults applied on write: `bizStep` → `urn:epcglobal:cbv:bizstep:receiving`; `disposition` → `urn:epcglobal:cbv:disp:in_progress`; `readPoint` → `geo:,` derived from `credentialSubject.originLocation` when present; `bizLocation` → `responsibleOperatorDid`; `eventTime` → `issuanceDate`, else the server clock; `epcList` → `[credentialSubject.id]` when not supplied as an array (or `[]`). The row is stored with `isUntpCompliant: true` and the `proof.proofValue` retained.\n\n**Caveats:** `credentialSubject.eventType` must be one of the documented event-type values and `action` (when present) one of `ADD`/`OBSERVE`/`DELETE` — both map to server-side enums, and a missing or unknown value is only rejected at the persistence layer and surfaces as the 500 `Database Persistence Failed` body, not as a 400. Note the 201 envelope is `{status: \"success\", ...}`, NOT the usual `{success: true, ...}` shape. This endpoint does not create lineage edges between events; the lineage DAG read by `GET /api/v1/events/{id}/lineage` is built from lineage relations maintained separately on the node.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UntpEventCredential" }, "example": { "@context": [ "https://www.w3.org/ns/credentials/v2", "https://vocabulary.uncefact.org/untp/dpp/" ], "id": "urn:uuid:0e7a2c1c-6f4e-4a08-9d2e-3b1f5a7c9d10", "type": [ "VerifiableCredential", "DigitalTraceabilityEvent" ], "issuer": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo", "issuanceDate": "2026-06-12T09:41:00.000Z", "credentialSubject": { "id": "urn:epc:id:sgtin:0950110153.0003.SN-2026-000123", "eventType": "ObjectEvent", "action": "OBSERVE", "bizStep": "urn:epcglobal:cbv:bizstep:shipping", "disposition": "urn:epcglobal:cbv:disp:in_transit", "readPoint": "geo:41.1496,-8.6109", "bizLocation": "urn:epc:id:sgln:0950110153000..0", "eventTime": "2026-06-12T08:30:00.000Z", "epcList": [ "urn:epc:id:sgtin:0950110153.0003.SN-2026-000123" ], "responsibleOperatorDid": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo" }, "proof": { "type": "DataIntegrityProof", "created": "2026-06-12T09:41:00.000Z", "proofPurpose": "assertionMethod", "verificationMethod": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo#key-1", "proofValue": "MEUCIQDkx0VqFholm0Oa7lzwL9C5cqcRBYRJWcExampleEcdsaDerAiBJ4dY0YxV5n7pUq2tHj8sExampleSecondIntegerValue9w==" } } } } }, "responses": { "201": { "description": "Event registered. Note the non-standard envelope: `status: \"success\"` (string), not `success: true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceEventRegistered" }, "example": { "status": "success", "eventId": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "untpVerified": true } } } }, "400": { "description": "Route-specific validation failure, always `{success: false, error, message}` with one of three `error` values: `Bad Request` (body missing or no `credentialSubject`), `Schema Validation Error` (`action` present on a `TransformationEvent`), or `Cryptographic Verification Failed` (no trusted key resolved for the issuer, or the proof signature does not verify).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalidStructure": { "value": { "success": false, "error": "Bad Request", "message": "Invalid credential payload structure." } }, "actionOnTransformationEvent": { "value": { "success": false, "error": "Schema Validation Error", "message": "The 'action' field is strictly forbidden on TransformationEvent rows under the GS1 EPCIS 2.0 standard." } }, "signatureInvalid": { "value": { "success": false, "error": "Cryptographic Verification Failed", "message": "W3C Verifiable Credential signature is invalid or altered." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Persistence failure — also returned when `credentialSubject.eventType`/`action` is missing or not a valid enum value (the server-side enum rejects the row). The authentication layer can additionally emit `{success: false, error: \"Internal Server Error\", message: \"Authentication verification failed\"}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "persistenceFailed": { "value": { "success": false, "error": "Database Persistence Failed", "message": "Failed to persist the event." } }, "authVerificationFailed": { "value": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } } }, "/api/v1/events/{id}/lineage": { "get": { "operationId": "getEventLineage", "tags": [ "Traceability & Audit" ], "summary": "Retrieve the upstream pedigree of an event as a recursive lineage DAG", "description": "Returns the full upstream pedigree of a traceability event as a recursive Directed Acyclic Graph: the root event plus, in `parents`, every event linked upstream through lineage relations registered on the node, walked transitively (parents of parents). A shared ancestor reached through multiple downstream paths is repeated under EACH path — the DAG is expanded into a tree in the response, not deduplicated; only a true cycle aborts the walk (400).\n\n**Permission:** `passport:read`. Every node in the walk — the root AND each upstream parent — is scoped to the caller's tenant; an event belonging to another tenant is invisible and the request fails with 404 (no cross-tenant pedigree reads). Sessions with the `SUPER_ADMIN` role are exempt from tenant scoping.\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).\n\n**Caveats:** if the lineage graph contains a circular reference the walk aborts with 400. Any other failure (unknown id, other-tenant id, missing parent) is reported as the same deliberately generic 404 body. `eventTime` is serialized as ISO 8601 UTC; `epcs` is parsed from the stored EPC list (a non-array value degrades to `[]`); `location` mirrors the stored `bizLocation`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "EPCIS event id — the server-generated UUID returned as `eventId` by `POST /api/v1/events`." } ], "responses": { "200": { "description": "The lineage DAG rooted at the requested event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceLineageResponse" }, "example": { "success": true, "lineage": { "eventId": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "eventType": "TransformationEvent", "bizStep": "urn:epcglobal:cbv:bizstep:commissioning", "disposition": "urn:epcglobal:cbv:disp:active", "eventTime": "2026-06-12T08:30:00.000Z", "epcs": [ "urn:epc:id:sgtin:0950110153.0003.SN-2026-000123" ], "location": "urn:epc:id:sgln:0950110153000..0", "readPoint": "geo:41.1496,-8.6109", "isUntpCompliant": true, "issuerDid": "did:web:opendpp-node.eu:EU-DEFAULT-001:demo", "parents": [ { "eventId": "4c81d2e6-9f0a-4b3c-8d5e-1a2b3c4d5e6f", "eventType": "ObjectEvent", "bizStep": "urn:epcglobal:cbv:bizstep:receiving", "disposition": "urn:epcglobal:cbv:disp:in_progress", "eventTime": "2026-06-10T14:05:00.000Z", "epcs": [ "urn:epc:id:sgtin:0950110153.0001.RAW-COTTON-LOT-77" ], "location": "did:web:opendpp-node.eu:supplier-pt", "readPoint": "geo:38.7223,-9.1393", "isUntpCompliant": true, "issuerDid": "did:web:opendpp-node.eu:supplier-pt", "parents": [] } ] } } } } }, "400": { "description": "Circular reference detected while walking the lineage graph.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Lineage Retrieval Failed", "message": "Circular reference detected in lineage graph." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The event does not exist, belongs to another tenant, or an upstream node could not be retrieved. The `error` value is `Lineage Retrieval Failed` (not the standard `Not Found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Lineage Retrieval Failed", "message": "Lineage could not be retrieved." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/events/{id}/audit": { "post": { "operationId": "auditEventLineage", "tags": [ "Traceability & Audit" ], "summary": "Run heuristic UFLPA/EUDR compliance screening over an event's lineage", "description": "Walks the same upstream lineage DAG as `GET /api/v1/events/{id}/lineage` and screens every node's location data against two heuristic rules:\n\n- **UFLPA** — flags any node whose `bizLocation` starts with `CN-65` (ISO 3166-2 Xinjiang), contains the keyword `XINJIANG` (case-insensitive), or whose `readPoint` contains the coordinate pair `43.8256,87.6168`.\n- **EUDR** — flags any node whose `readPoint` parses as `geo:,` (or bare `,`) coordinates inside the sample deforestation polygon lat −5.0…−3.0, lng −65.0…−60.0.\n\nThese are geographic screening heuristics evaluated against the data registered on this node — not a legal compliance determination.\n\n**Permission:** `passport:read` (a read permission despite the POST verb — no subscription gating). Cookie-session clients must send the `X-CSRF-Token` header; Bearer clients are exempt. Tenant scoping and the `SUPER_ADMIN` bypass are identical to the lineage endpoint. **No request body is read** — send an empty body (an empty or absent JSON body is accepted).\n\n**Rate limit:** global limiter, 100 requests/min per IP (standard `x-ratelimit-*` headers).\n\nWhen zero violations are found, the response embeds a `TraceabilityComplianceCertificate` object (status `VERIFIED_COMPLIANT`, standards `EUDR-2026` / `UFLPA-2026`); otherwise `certificate` is `null` and `errors` lists each violation as a human-readable string. ANY failure — unknown event id, other-tenant id, or even a circular lineage graph — is reported as the same generic 404 body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "EPCIS event id — the server-generated UUID returned as `eventId` by `POST /api/v1/events`. Used as the root of the audited lineage DAG." } ], "responses": { "200": { "description": "Audit completed (compliant or not — violations are reported in-band, not as HTTP errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceComplianceAuditResponse" }, "examples": { "compliant": { "value": { "success": true, "eventId": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "compliant": true, "errors": [], "auditedAt": "2026-06-12T09:41:00.000Z", "certificate": { "type": "TraceabilityComplianceCertificate", "rootEventId": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "status": "VERIFIED_COMPLIANT", "regulatoryStandards": [ "EUDR-2026", "UFLPA-2026" ] } } }, "nonCompliant": { "value": { "success": true, "eventId": "9b2fa884-1c3d-4e5f-8a6b-7c8d9e0f1a2b", "compliant": false, "errors": [ "UFLPA Compliance Failure: Event [4c81d2e6-9f0a-4b3c-8d5e-1a2b3c4d5e6f] contains raw materials originating from prohibited Xinjiang region (CN-65 Urumqi)." ], "auditedAt": "2026-06-12T09:41:00.000Z", "certificate": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The audit could not be completed: unknown event id, an event belonging to another tenant, or a circular lineage graph. The `error` value is `Compliance Audit Failed` (not the standard `Not Found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Compliance Audit Failed", "message": "Lineage compliance audit could not be completed." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/audit/verify": { "post": { "operationId": "verifyPassportSeal", "tags": [ "Traceability & Audit" ], "summary": "Publicly verify a passport's eIDAS seal, certificate chain and timestamp", "description": "**Public seal-verification API** — cryptographically verifies that a Digital Product Passport document was sealed by an economic-operator tenant registered on this node and has not been tampered with. No authentication required.\n\n**Rate limit:** custom in-memory token bucket, **30 requests/min per IP** (per app instance). This bucket emits no rate-limit headers of its own — any `x-ratelimit-*` headers on responses (including this 429) come from the global 100 req/min limiter and describe that budget, not the 30/min one. The 429 body is the two-field `{\"error\": \"Too Many Requests\", \"message\": \"Rate limit exceeded.\"}`.\n\n**Input resolution.** `payload` is required. `signature` and `publicKey` may be supplied top-level, or are extracted from the document's embedded proof block: `signature` ← `payload.proof.proofValue` (else `payload.proof.signatureValue`); `publicKey` ← `payload.proof.publicKeyPem`, else the leaf certificate's SPKI when `payload.proof.x5c` is present. If, after extraction, any of the three is still missing → 400. The public key is CRLF-normalized and trimmed before matching.\n\n**Verification pipeline (in order):**\n1. **Certificate-chain report (optional).** If `payload.proof.x5c` is a non-empty array of base64-DER certificates (leaf first), the chain is parsed and a `certificate` report is built: the leaf's `subject` / `issuer` / `validFrom` / `validTo` (X.509 textual dates such as `Jan 10 00:00:00 2026 GMT` — NOT ISO 8601), `chainValid` (every link signature-verifies against the next certificate, every certificate is inside its validity window, and the top of the chain is anchored to this node's seal CA — SHA-256 fingerprint match or signature under the CA key; the CA is published at `GET /.well-known/opendpp-seal-ca.pem`), and `keyMatchesProof` (the leaf SPKI equals the supplied `publicKey`, whitespace-insensitive; always `true` when no explicit key was supplied). An unparseable chain yields `{\"chainValid\": false, \"error\": \"Unparseable x5c certificate chain\"}` and does NOT fail the request. This reports the CERTIFIED identity of the seal creator (eIDAS Art. 36(1)(b)). The report is attached only to the final verification outcome (step 4) — the two policy-failure responses below omit it.\n2. **Key-registration gate.** The `publicKey` must exactly match the registered eIDAS public key of a tenant on this node (trailing-newline tolerant) — otherwise HTTP **200** with `verified: false` and an explanatory `message`. Verification-policy failures are reported in-band, never as HTTP errors.\n3. **Operator-binding gate (fail-closed).** If the payload declares an operator registration id (`payload.operator.regId`, else `payload.economicOperator.regId`), that id MUST resolve to an Economic Operator registered on this node AND that operator MUST be bound to the signing tenant (a workspace–operator binding registered on this node). A declared operator that is unregistered, or registered but not bound to the key-owning tenant, → 200 `verified: false` with an explanatory `message`. Payloads that declare no operator id skip this gate.\n4. **Signature verification (two phases).** *Phase 1 — Merkle seal:* when `payload.metadata` is an object (or, when the `metadata` key is entirely absent, the whole `payload` is treated as the metadata), the SHA-256 Merkle tree over the metadata's top-level properties is rebuilt and the base64 ECDSA (P-256 / SHA-256) `signature` is verified against the recomputed root. Every leaf is recomputed from the actual values — caller-supplied redacted-leaf hashes are NOT accepted (they would let a tampered field be smuggled past verification), so a publicly redacted document will not pass the Merkle phase: verify the unredacted, privileged document. *Phase 2 — fallback:* if the Merkle phase does not verify, the signature is verified over the deterministic key-sorted canonicalization of the entire `payload`.\n5. **RFC 3161 timestamp report (optional).** When `payload.proof.rfc3161.token` is a non-empty base64-DER TimeStampToken, the response includes `timestamp` with the TSA-asserted `genTime` parsed from the token's TSTInfo (or `genTime: null` plus a `note` when the token cannot be parsed). This reports presence + asserted time only — full cryptographic TSR validation is the verifier's own step (e.g. `openssl ts -verify` against the TSA certificate). Like `certificate`, it appears only on the final verification outcome.\n\n**Outcome.** A processed verification ALWAYS returns HTTP 200 with `verified: true|false`; 400 is reserved for missing parameters or an exception thrown while verifying (e.g. an undecodable public key). `certificate` and `timestamp` are attached only when verification proceeds past the key-registration and operator-binding gates — the two policy `verified: false` responses contain only `{success, verified, message}`, even when an x5c chain and/or an RFC 3161 token were supplied. The 400 bodies on this public endpoint are `{\"success\": false, \"message\": \"...\"}` — they include `success` but OMIT the `error` field. (A syntactically malformed JSON body is rejected earlier by the framework with its default `{statusCode, error, message}` body; a POST with no body at all — no `Content-Type` — fails before processing with a framework-default 500, so send at least `{}`. An empty `application/json` body is treated as `{}` and yields the documented 400.)", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealVerifyRequest" }, "example": { "payload": { "passportId": "9b2fa884-5b1d-4c0e-9a3f-2d7c8e1f6a45", "productId": "09501101530003", "operator": { "name": "OpenDPP Demo Eco Industries", "regId": "EU-DEFAULT-001" }, "metadata": { "category": "textiles", "originCountry": "PT", "materialComposition": [ { "material": "Organic Cotton", "percentage": 80 }, { "material": "Recycled Polyester", "percentage": 20 } ] }, "proof": { "type": "DataIntegrityProof", "proofValue": "MEQCIB3pZ8sVxampleMerkleRootSealSignatureFirstIntegerAiAW6kQexampleSecondDerIntegerValue0123456789abcd==", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEexampleDemoTenantSealPublicKey\n0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNO=\n-----END PUBLIC KEY-----", "x5c": [ "MIIB2zCCAYGgAwIBAgIUExampleLeafSealCertificateBase64Der", "MIIB4TCCAYagAwIBAgIUExampleNodeSealCaCertificateBase64Der" ], "rfc3161": { "token": "MIIKlAYJKoZIhvcNAQcCoIIKhTCCCoECAQMxDzANBglghkgBZQMEAgEFADCBExampleTimeStampTokenDer" } } } } } } }, "responses": { "200": { "description": "Verification processed. `verified` reports the cryptographic outcome; policy failures (unregistered key, unbound operator) come back as `verified: false` with a `message` — still HTTP 200, and WITHOUT `certificate`/`timestamp` even when an x5c chain or RFC 3161 token was supplied. Once verification proceeds past the policy gates, `certificate` is present for x5c-carrying proofs and `timestamp` when an RFC 3161 token was embedded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealVerifyResponse" }, "examples": { "sealVerified": { "summary": "Authentic seal with certificate chain and trusted timestamp", "value": { "success": true, "verified": true, "certificate": { "subject": "CN=OpenDPP Demo Eco Industries Seal", "issuer": "CN=OpenDPP Node Seal CA", "validFrom": "Jan 10 00:00:00 2026 GMT", "validTo": "Jan 10 00:00:00 2028 GMT", "chainValid": true, "keyMatchesProof": true }, "timestamp": { "present": true, "genTime": "2026-06-12T09:41:03.000Z" } } }, "unregisteredKey": { "summary": "Public key not registered to any tenant on this node", "value": { "success": true, "verified": false, "message": "Cryptographic verification failed: The public key used to seal this passport is not registered to any authorized economic operator tenant on this node." } }, "operatorNotBound": { "summary": "Declared operator not bound to the signing tenant (fail-closed)", "value": { "success": true, "verified": false, "message": "Cryptographic verification failed: The economic operator declared in this passport is not a registered operator bound to the signing tenant." } } } } } }, "400": { "description": "Missing cryptographic parameters (after proof-block extraction), or an exception during verification (e.g. undecodable key material). Body is `{success: false, message}` — NO `error` field on this public endpoint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string", "enum": [ "Missing cryptographic parameter: payload, signature, and publicKey are required", "Signature verification failed." ] } } }, "example": { "success": false, "message": "Missing cryptographic parameter: payload, signature, and publicKey are required" } } } }, "429": { "$ref": "#/components/responses/PublicRateLimited" } } } }, "/api/v1/webhooks/subscriptions": { "post": { "operationId": "createWebhookSubscription", "tags": [ "Webhooks" ], "summary": "Register a webhook subscription (signing secret returned once)", "description": "Registers an endpoint to receive passport lifecycle webhooks for the calling workspace.\n\n**Permission:** `webhook:write`. Cookie-session callers must send the `X-CSRF-Token` header (double-submit); Bearer API-key/JWT clients are exempt. Write permissions are additionally gated on an active workspace subscription (`402`).\n\n**URL validation (SSRF guard):** `url` must be an absolute `http(s)` URL. At registration the hostname is DNS-resolved and the request is rejected with `400` if any resolved A/AAAA record is loopback, RFC 1918/CGNAT private, link-local / cloud-metadata (`169.254.0.0/16`), multicast, or an equivalent IPv6 range. At delivery time the socket is pinned to the validated IP and redirects are never followed.\n\n**Event filters:** `events` must be a non-empty array drawn from `passport.ingested`, `passport.sealed`, `passport.recalled`, `*`. The `*` wildcard matches every emitted event — including `passport.status_updated`, which the platform emits but which cannot be subscribed to explicitly.\n\n**Signing secret — shown once:** the `201` response contains the full subscription row **including** the HMAC-SHA256 signing secret (`whsec_` + 32 lowercase hex chars, server-generated, never client-supplied). This is the only time the secret is ever returned: the list endpoint strips it and there is no rotation or update endpoint — delete and re-create to rotate.\n\n**Limits:** maximum **25 subscriptions per workspace** (`409 Conflict`). Global rate limit 100 requests/min/IP (`429` with `x-ratelimit-*` headers). Unknown request-body fields are ignored.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequest" }, "example": { "url": "https://erp.example.com/hooks/opendpp", "events": [ "passport.ingested", "passport.sealed" ] } } } }, "responses": { "201": { "description": "Subscription registered. `subscription` is the full row **including `secret`** — store it now; it is never returned again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateResponse" }, "example": { "success": true, "message": "Webhook subscription registered successfully", "subscription": { "id": "5e8d2c47-9a1b-4f63-8c0d-7b4e2f9a6d35", "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "url": "https://erp.example.com/hooks/opendpp", "secret": "whsec_00000000000000000000000000000000", "events": [ "passport.ingested", "passport.sealed" ], "isActive": true, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" } } } } }, "400": { "description": "Validation failure. Exact messages: `\"url must be a valid string URL\"` (missing, empty, or non-string `url`); `\"Outbound webhook URL rejected: \"` (SSRF guard — covers a malformed URL string (reason `Invalid URL format`), a non-http(s) scheme, an unresolvable host, or a private/loopback/metadata address); `\"events must be a non-empty array of strings\"`; `\"event '' is invalid. Allowed events: passport.ingested, passport.sealed, passport.recalled, *\"`. (A malformed JSON body instead yields a framework-default `{statusCode, error, message}` 400 body.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Bad Request", "message": "event 'passport.deleted' is invalid. Allowed events: passport.ingested, passport.sealed, passport.recalled, *" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "The workspace already has 25 webhook subscriptions (the per-tenant cap). Delete an existing subscription first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Conflict", "message": "Maximum of 25 webhook subscriptions per workspace reached." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Persistence failed (details logged server-side) — message `\"Failed to register webhook subscription.\"`. Auth-layer failures use the message `\"Authentication verification failed\"`. (A failure of the pre-create subscription-count query instead returns a framework-default `{statusCode, error, message}` body without `success`.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Internal Server Error", "message": "Failed to register webhook subscription." } } } } } }, "get": { "operationId": "listWebhookSubscriptions", "tags": [ "Webhooks" ], "summary": "List webhook subscriptions (signing secrets stripped)", "description": "Lists all webhook subscriptions of the calling workspace. Unpaginated (the per-workspace cap is 25).\n\n**Permission:** `webhook:read` (read permissions are not subscription-gated, so no `402`).\n\nThe HMAC signing `secret` is **stripped from every row** — it is returned exactly once, by the create endpoint. `isActive` is reported but no public endpoint toggles it; only active subscriptions receive deliveries. Global rate limit 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "All subscriptions of the workspace, secrets removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListResponse" }, "example": { "success": true, "subscriptions": [ { "id": "5e8d2c47-9a1b-4f63-8c0d-7b4e2f9a6d35", "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "url": "https://erp.example.com/hooks/opendpp", "events": [ "passport.ingested", "passport.sealed" ], "isActive": true, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z" }, { "id": "0c7b1e92-4d5a-4b38-a6f1-83e9d27c50b4", "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "url": "https://plm.example.com/integrations/opendpp/events", "events": [ "*" ], "isActive": true, "createdAt": "2026-05-30T14:02:11.000Z", "updatedAt": "2026-05-30T14:02:11.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error. Auth-layer failures return the standard `{success: false, error, message}` envelope (message `\"Authentication verification failed\"`); an unhandled database error in the handler itself instead returns a framework-default `{statusCode, error, message}` body without `success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } }, "/api/v1/webhooks/subscriptions/{id}": { "delete": { "operationId": "deleteWebhookSubscription", "tags": [ "Webhooks" ], "summary": "Delete a webhook subscription", "description": "Deletes a webhook subscription, stopping future deliveries to its endpoint.\n\n**Permission:** `webhook:write` (cookie sessions must send `X-CSRF-Token`; write permissions are subscription-gated, `402`).\n\nThe lookup is tenant-scoped: an `id` that exists but belongs to another workspace returns the same `404` with message `\"Webhook subscription not found under your tenant\"`. Deleting and re-creating is the only way to rotate a signing secret. Global rate limit 100 requests/min/IP.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription UUID (as returned at creation / by the list endpoint).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionDeleteResponse" }, "example": { "success": true, "message": "Webhook subscription successfully deleted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "description": "Unexpected server error. Auth-layer failures return the standard `{success: false, error, message}` envelope (message `\"Authentication verification failed\"`); an unhandled database error in the handler itself instead returns a framework-default `{statusCode, error, message}` body without `success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Internal Server Error", "message": "Authentication verification failed" } } } } } } } }, "webhooks": { "passport.ingested": { "post": { "operationId": "passportIngestedWebhook", "tags": [ "Webhooks" ], "summary": "Passport created or first published", "description": "Sent when a passport becomes active for the first time: a non-draft `POST /api/v1/passports` create, the **first publish** of a draft via `PUT /api/v1/passports/{id}`, or each successfully ingested row of `POST /api/v1/passports/bulk`. Draft creation does NOT emit it, non-publish updates and deletes emit nothing, and **AAS ingestion (`POST /api/v1/passports/aas/ingest`) emits no webhook events at all**. The payload is the freshly created passport: `status: \"ACTIVE\"` with `digitalSeal` and `proof` still `null` (unless a previously sealed draft is re-published). Emission is enqueued transactionally with the passport write (outbox pattern) and delivered asynchronously to every active subscription whose filter contains `passport.ingested` or `*`.\n\n**Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`):\n- The body is the raw **public (redacted) JSON-LD passport document** — there is **no envelope**; the event type travels ONLY in the `X-OpenDPP-Event` header. Owner-tier fields (facility street address, restricted metadata values) are never included. The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** — in `metadata`, flattened at top level, and in the `@context` term map — even when the passport never set that key; restricted metadata keys likewise appear masked, with their true leaf hashes preserved in `proof.redactedLeaves` once sealed.\n- **Success = any HTTP 2xx** returned within the **5-second** timeout. Redirects are **never followed** — a 3xx counts as failure. The response body is ignored.\n- **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt with exponential backoff — ~1 min, 5 min, 30 min, then 2 h after the previous failure. The **5th failed attempt dead-letters the event** (no further deliveries) and the workspace receives an in-app notification.\n- **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed when the same event is retried for sibling subscriptions. Still treat delivery as at-least-once (a 2xx the sender fails to record can re-deliver); no delivery-id header is sent, so deduplicate on payload content if you need exactly-once.\n- **Signature verification:** compute `HMAC-SHA256(secret, X-OpenDPP-Timestamp + \".\" + rawBody)` keyed with the FULL `whsec_…` secret (including the prefix), hex-encode lowercase, constant-time-compare with `X-OpenDPP-Signature` (bare hex — no `v1=`/`sha256=` prefix). Verify over the **raw body bytes** before any JSON parsing. Reject timestamps older than ~5 minutes; the timestamp and signature are **re-minted on every retry attempt**, so retried deliveries always carry a fresh, valid pair.", "security": [], "parameters": [ { "name": "X-OpenDPP-Event", "in": "header", "required": true, "description": "Event type — the ONLY place the event name appears (the body has no envelope).", "schema": { "type": "string", "const": "passport.ingested" } }, { "name": "X-OpenDPP-Timestamp", "in": "header", "required": true, "description": "Unix epoch seconds (decimal string) minted at this delivery attempt; bound into the signature. Reject if skewed more than ~5 minutes from your clock.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-OpenDPP-Signature", "in": "header", "required": true, "description": "Bare lowercase-hex HMAC-SHA256 of `.`, keyed with the full `whsec_…` subscription secret.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "OpenDPP-Webhook-Outbox/1.0" } } ], "requestBody": { "required": true, "description": "Raw public JSON-LD passport document (no envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "batteryChemistry": "https://w3id.org/dpp/context/v1#batteryChemistry", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003", "id": "9b2fa884-5c1d-4e7a-9f3b-6d2c8e0a4b71", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003", "digitalSeal": null, "signingPublicKey": null, "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T09:41:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "1d4f7a92-3b6e-4c08-8a5d-9e2b7c4f6a13", "name": "Volta Demo Industries GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "7c3e9b15-8d2a-4f6c-b1e7-0a5d4c8f2e96", "gln": "0950110153007", "name": "Demo Gigafactory One", "activity": "Cell manufacturing", "country": "DE" }, "metadata": { "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } }, "responses": { "2XX": { "description": "Your endpoint acknowledges the delivery. Any 2xx within 5 seconds marks this subscription delivered; the response body is ignored." }, "default": { "description": "Any non-2xx status (including 3xx — redirects are never followed), a response slower than 5 seconds, or a connection error counts as a failed attempt. Up to 5 attempts total with ~1m/5m/30m/2h backoff between attempts; the 5th failed attempt dead-letters the event." } } } }, "passport.sealed": { "post": { "operationId": "passportSealedWebhook", "tags": [ "Webhooks" ], "summary": "Passport sealed with an eIDAS advanced seal", "description": "Sent when a passport is sealed via `POST /api/v1/passports/{id}/seal`, transactionally with the seal write. The payload carries the populated `digitalSeal`, `signingPublicKey`, and the `proof` block: `merkleRoot` always; an `x5c` certificate chain binding the signing key to the tenant's legal identity **when the tenant's signing key has an issued chain**; an **optional** `rfc3161` trusted timestamp; and `redactedLeaves` hashes **when the passport carries masked metadata keys**. Delivered to every active subscription whose filter contains `passport.sealed` or `*`.\n\n**Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`):\n- The body is the raw **public (redacted) JSON-LD passport document** — there is **no envelope**; the event type travels ONLY in the `X-OpenDPP-Event` header. The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked, with their true leaf hashes in `proof.redactedLeaves`.\n- **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored.\n- **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app.\n- **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once. No delivery-id header is sent.\n- **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + \".\" + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt.", "security": [], "parameters": [ { "name": "X-OpenDPP-Event", "in": "header", "required": true, "description": "Event type — the ONLY place the event name appears (the body has no envelope).", "schema": { "type": "string", "const": "passport.sealed" } }, { "name": "X-OpenDPP-Timestamp", "in": "header", "required": true, "description": "Unix epoch seconds (decimal string) minted at this delivery attempt; bound into the signature. Reject if skewed more than ~5 minutes from your clock.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-OpenDPP-Signature", "in": "header", "required": true, "description": "Bare lowercase-hex HMAC-SHA256 of `.`, keyed with the full `whsec_…` subscription secret.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "OpenDPP-Webhook-Outbox/1.0" } } ], "requestBody": { "required": true, "description": "Raw public JSON-LD passport document (no envelope), with seal and proof populated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "batteryChemistry": "https://w3id.org/dpp/context/v1#batteryChemistry", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003", "id": "9b2fa884-5c1d-4e7a-9f3b-6d2c8e0a4b71", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003", "digitalSeal": "MEUCIQDx5n0L8q2vY7c3T1k9rWm4ZpB6aH8sJdQfN2eK0uXgRwIgVtY3mC1bL7pDqE5fS9hA2nO4xWzUjMK6cTiPeB8oG1s=", "signingPublicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEx7Qb1k2mP4cV9sJh3nT6fL0wR8dZ\n5yA1uE7gXiK2oB4qNvC6tS9jM8hW0aFrD3pUzGmYLk5eHxOI1cR7vJbT2g==\n-----END PUBLIC KEY-----\n", "status": "ACTIVE", "archivedAt": null, "retentionUntil": null, "proof": { "@type": [ "MerkleTreeAttestationProof" ], "type": "MerkleTreeAttestationProof", "signatureAlgorithm": "ECDSA-P256-SHA256-over-MerkleRoot", "created": "2026-06-12T10:15:02.000Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://opendpp-node.eu/passport/9b2fa884-5c1d-4e7a-9f3b-6d2c8e0a4b71#key-1", "signatureValue": "MEUCIQDx5n0L8q2vY7c3T1k9rWm4ZpB6aH8sJdQfN2eK0uXgRwIgVtY3mC1bL7pDqE5fS9hA2nO4xWzUjMK6cTiPeB8oG1s=", "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEx7Qb1k2mP4cV9sJh3nT6fL0wR8dZ\n5yA1uE7gXiK2oB4qNvC6tS9jM8hW0aFrD3pUzGmYLk5eHxOI1cR7vJbT2g==\n-----END PUBLIC KEY-----\n", "x5c": [ "MIIBxjCCAWygAwIBAgIUKp3c8f0AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbMAoGCCqGSM49BAMCMCExHzAdBgNVBAMMFk9wZW5EUFAgU2VhbCBJc3N1aW5nIENB" ], "merkleRoot": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069" }, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T10:15:02.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "1d4f7a92-3b6e-4c08-8a5d-9e2b7c4f6a13", "name": "Volta Demo Industries GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "7c3e9b15-8d2a-4f6c-b1e7-0a5d4c8f2e96", "gln": "0950110153007", "name": "Demo Gigafactory One", "activity": "Cell manufacturing", "country": "DE" }, "metadata": { "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } }, "responses": { "2XX": { "description": "Your endpoint acknowledges the delivery. Any 2xx within 5 seconds marks this subscription delivered; the response body is ignored." }, "default": { "description": "Any non-2xx status (including 3xx — redirects are never followed), a response slower than 5 seconds, or a connection error counts as a failed attempt. Up to 5 attempts total with ~1m/5m/30m/2h backoff between attempts; the 5th failed attempt dead-letters the event." } } } }, "passport.recalled": { "post": { "operationId": "passportRecalledWebhook", "tags": [ "Webhooks" ], "summary": "Passport recalled", "description": "Sent when `PUT /api/v1/passports/{id}/status` transitions a passport to `RECALLED`, transactionally with the status write. The payload is the public JSON-LD passport with `status: \"RECALLED\"` (seal/proof fields reflect whatever state the passport was in when recalled). Delivered to every active subscription whose filter contains `passport.recalled` or `*`.\n\n**Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`):\n- The body is the raw **public (redacted) JSON-LD passport document** — there is **no envelope**; the event type travels ONLY in the `X-OpenDPP-Event` header. The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked.\n- **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored.\n- **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app.\n- **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once. No delivery-id header is sent.\n- **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + \".\" + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt.", "security": [], "parameters": [ { "name": "X-OpenDPP-Event", "in": "header", "required": true, "description": "Event type — the ONLY place the event name appears (the body has no envelope).", "schema": { "type": "string", "const": "passport.recalled" } }, { "name": "X-OpenDPP-Timestamp", "in": "header", "required": true, "description": "Unix epoch seconds (decimal string) minted at this delivery attempt; bound into the signature. Reject if skewed more than ~5 minutes from your clock.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-OpenDPP-Signature", "in": "header", "required": true, "description": "Bare lowercase-hex HMAC-SHA256 of `.`, keyed with the full `whsec_…` subscription secret.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "OpenDPP-Webhook-Outbox/1.0" } } ], "requestBody": { "required": true, "description": "Raw public JSON-LD passport document (no envelope) with status RECALLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "batteryChemistry": "https://w3id.org/dpp/context/v1#batteryChemistry", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003", "id": "9b2fa884-5c1d-4e7a-9f3b-6d2c8e0a4b71", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003", "digitalSeal": null, "signingPublicKey": null, "status": "RECALLED", "archivedAt": null, "retentionUntil": null, "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T11:02:45.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "1d4f7a92-3b6e-4c08-8a5d-9e2b7c4f6a13", "name": "Volta Demo Industries GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "7c3e9b15-8d2a-4f6c-b1e7-0a5d4c8f2e96", "gln": "0950110153007", "name": "Demo Gigafactory One", "activity": "Cell manufacturing", "country": "DE" }, "metadata": { "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } }, "responses": { "2XX": { "description": "Your endpoint acknowledges the delivery. Any 2xx within 5 seconds marks this subscription delivered; the response body is ignored." }, "default": { "description": "Any non-2xx status (including 3xx — redirects are never followed), a response slower than 5 seconds, or a connection error counts as a failed attempt. Up to 5 attempts total with ~1m/5m/30m/2h backoff between attempts; the 5th failed attempt dead-letters the event." } } } }, "passport.status_updated": { "post": { "operationId": "passportStatusUpdatedWebhook", "tags": [ "Webhooks" ], "summary": "Passport status changed (decommission/reactivate) — wildcard-only", "description": "Sent when `PUT /api/v1/passports/{id}/status` performs a non-recall transition: decommissioning (`DECOMMISSIONED`, which also sets `retentionUntil` and starts the retention clock) or reactivation back to `ACTIVE`. **This event is NOT explicitly subscribable** — it is absent from the allowed `events` filter values of the subscription API, so it is delivered ONLY to subscriptions whose filter is the `*` wildcard.\n\n**Delivery contract** (sender `User-Agent: OpenDPP-Webhook-Outbox/1.0`):\n- The body is the raw **public (redacted) JSON-LD passport document** — there is **no envelope**; the event type travels ONLY in the `X-OpenDPP-Event` header. The owner-only `facilityDetails` metadata key **always appears with the masked value `[REDACTED - Privileged Access Required]`** (in `metadata`, flattened at top level, and in the `@context` term map) even when the passport never set that key; restricted metadata keys likewise appear masked.\n- **Success = any HTTP 2xx** within the **5-second** timeout. Redirects are **never followed** (3xx = failure). Response body ignored.\n- **Retries:** up to **5 delivery attempts** total. Failed attempts 1–4 schedule the next attempt ~1 min / 5 min / 30 min / 2 h after the previous failure; the **5th failed attempt dead-letters the event** and the workspace is notified in-app.\n- **Per-subscription dedup:** endpoints that already returned 2xx are not re-POSTed on retries; still treat delivery as at-least-once. No delivery-id header is sent.\n- **Signature verification:** `HMAC-SHA256(secret, X-OpenDPP-Timestamp + \".\" + rawBody)` keyed with the FULL `whsec_…` secret, lowercase hex, constant-time compare against `X-OpenDPP-Signature` (bare hex, no scheme prefix). Verify over the **raw body bytes**; reject >~5 min timestamp skew; timestamp+signature are re-minted per retry attempt.", "security": [], "parameters": [ { "name": "X-OpenDPP-Event", "in": "header", "required": true, "description": "Event type — the ONLY place the event name appears (the body has no envelope).", "schema": { "type": "string", "const": "passport.status_updated" } }, { "name": "X-OpenDPP-Timestamp", "in": "header", "required": true, "description": "Unix epoch seconds (decimal string) minted at this delivery attempt; bound into the signature. Reject if skewed more than ~5 minutes from your clock.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-OpenDPP-Signature", "in": "header", "required": true, "description": "Bare lowercase-hex HMAC-SHA256 of `.`, keyed with the full `whsec_…` subscription secret.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "const": "OpenDPP-Webhook-Outbox/1.0" } } ], "requestBody": { "required": true, "description": "Raw public JSON-LD passport document (no envelope) with the new status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPassportJsonLd" }, "example": { "@context": [ "https://w3id.org/dpp/context/v1", { "DigitalProductPassport": "https://w3id.org/dpp#DigitalProductPassport", "economicOperator": "https://w3id.org/dpp#economicOperator", "manufacturingFacility": "https://w3id.org/dpp#manufacturingFacility", "metadata": "https://w3id.org/dpp#metadata", "digitalSeal": "https://w3id.org/dpp#digitalSeal", "signingPublicKey": "https://w3id.org/dpp#signingPublicKey", "status": "https://w3id.org/dpp#status", "archivedAt": "https://w3id.org/dpp#archivedAt", "retentionUntil": "https://w3id.org/dpp#retentionUntil", "category": "https://w3id.org/dpp/context/v1#category", "originCountry": "https://w3id.org/dpp/context/v1#originCountry", "batteryChemistry": "https://w3id.org/dpp/context/v1#batteryChemistry", "facilityDetails": "https://w3id.org/dpp/context/v1#facilityDetails" } ], "@type": "DigitalProductPassport", "@id": "https://opendpp-node.eu/01/09501101530003", "id": "9b2fa884-5c1d-4e7a-9f3b-6d2c8e0a4b71", "productId": "09501101530003", "digitalLinkUri": "https://opendpp-node.eu/01/09501101530003", "digitalSeal": null, "signingPublicKey": null, "status": "DECOMMISSIONED", "archivedAt": null, "retentionUntil": "2041-06-12T10:30:00.000Z", "proof": null, "createdAt": "2026-06-12T09:41:00.000Z", "updatedAt": "2026-06-12T10:30:00.000Z", "economicOperator": { "@type": "EconomicOperator", "id": "1d4f7a92-3b6e-4c08-8a5d-9e2b7c4f6a13", "name": "Volta Demo Industries GmbH", "regId": "EU-DEFAULT-001", "role": "Manufacturer" }, "manufacturingFacility": { "@type": "Facility", "id": "7c3e9b15-8d2a-4f6c-b1e7-0a5d4c8f2e96", "gln": "0950110153007", "name": "Demo Gigafactory One", "activity": "Cell manufacturing", "country": "DE" }, "metadata": { "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" }, "category": "batteries", "originCountry": "DE", "batteryChemistry": "LFP", "facilityDetails": "[REDACTED - Privileged Access Required]" } } } }, "responses": { "2XX": { "description": "Your endpoint acknowledges the delivery. Any 2xx within 5 seconds marks this subscription delivered; the response body is ignored." }, "default": { "description": "Any non-2xx status (including 3xx — redirects are never followed), a response slower than 5 seconds, or a connection error counts as a failed attempt. Up to 5 attempts total with ~1m/5m/30m/2h backoff between attempts; the 5th failed attempt dead-letters the event." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Tenant API key (`op_dpp_token_…`), created in the Client Console (Developers → API keys) and shown once at creation. Keys carry a role, optional narrowed permissions, and optional expiry. Session JWTs from the Console use the same header; API-key clients are exempt from CSRF requirements." } }, "schemas": { "Error": { "type": "object", "description": "Standard error body. Authenticated-API errors include `success: false`; some endpoints (and all public resolution errors) omit `success` and return only `error` + `message`.", "required": [ "error", "message" ], "properties": { "success": { "type": "boolean", "description": "Always `false` when present. Omitted by public endpoints and some self-service endpoints." }, "error": { "type": "string", "description": "Short error title (usually the HTTP reason phrase).", "examples": [ "Bad Request", "Not Found", "Validation Failed" ] }, "message": { "type": "string", "description": "Human-readable explanation." } } }, "ValidationErrorItem": { "type": "object", "description": "One field-level finding from ESPR category validation. `path` uses dot/bracket notation into the metadata object (e.g. `materialComposition[0].percentage`).", "required": [ "path", "message" ], "properties": { "path": { "type": "string", "description": "Dot/bracket path of the offending metadata field." }, "message": { "type": "string", "description": "Technical validation message." }, "friendlyMessage": { "type": "string", "description": "Localized, human-friendly explanation (language from `?lang=` or `Accept-Language`; 28 languages, default `en`)." } } }, "BatteryUnitStatus": { "type": "string", "enum": [ "IN_SERVICE", "DECOMMISSIONED", "RECALLED", "REPURPOSED", "REMANUFACTURED", "REUSED", "WASTE", "RECYCLED" ], "description": "Annex XIII battery-status vocabulary (Battery Reg. (EU) 2023/1542). `RECYCLED` means the passport has ceased to exist (Art. 77(8)): the public unit view answers 410 Gone whenever `status` is `RECYCLED` **or** `ceasedAt` is set. Terminality is enforced via `ceasedAt`, which only the events-route transition stamps (and never clears): the predecessor-refusal check keys on `ceasedAt` alone, so a unit *created* with initial status `RECYCLED` (no `ceasedAt`) is already a public 410 tombstone yet can still be referenced as a predecessor; conversely, once `ceasedAt` is set the events endpoint will still accept later `status` values, but the 410 tombstone and the predecessor refusal persist." }, "BatteryUnitEventType": { "type": "string", "enum": [ "SOH_MEASUREMENT", "CHARGE_CYCLE", "STATUS_CHANGE", "NEGATIVE_EVENT", "OTHER" ], "description": "Per-unit dynamic-data event category (Annex XIII / Art. 77 telemetry)." }, "FastifyDefaultBadRequest": { "type": "object", "description": "Fastify's default 400 error body, returned when a syntactically malformed JSON request body is rejected by the framework **before the handler runs** (so none of the handler-built `{success:false, ...}` shapes apply).", "properties": { "statusCode": { "type": "integer", "const": 400 }, "code": { "type": "string", "description": "Fastify error code, e.g. `FST_ERR_CTP_INVALID_JSON_BODY`. May be absent." }, "error": { "type": "string", "const": "Bad Request" }, "message": { "type": "string" } }, "required": [ "statusCode", "error", "message" ] }, "BatteryUnitRow": { "type": "object", "description": "One physical serialised battery (raw persisted row — these routes declare no Fastify response schema, so all model fields are returned as-is). A `BatteryUnit` is an individual instance of a SKU/type-level passport, carrying its real serial in GS1 AI-21.", "properties": { "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$", "description": "The battery's real physical serial number (GS1 AI-21 value). 1–64 URL-safe characters; GS1 recommends ≤ 20." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "Per-unit GS1 Digital Link: `{BASE_URL}/{01|8003}/{productId}/21/{serialNumber}` — AI `01` for GTIN (and non-GS1 SKUs), `8003` for GRAI. Unique platform-wide." }, "passportId": { "type": "string", "description": "The SKU/type-level passport this unit is an instance of." }, "tenantId": { "type": "string", "description": "Owning tenant id (the demo tenant uses the fixed id `tenant-demo-opendpp`; regular tenants use UUIDs)." }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus" }, "ceasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Stamped when the events endpoint transitions `status` to `RECYCLED` (Art. 77(8) cease-to-exist); never cleared afterwards, even if a later event changes `status` again. Non-null means the public unit view is a 410 tombstone and the unit is refused as a `predecessorUnitId`. Note: a unit *created* with initial status `RECYCLED` does NOT get `ceasedAt` stamped (the public view still tombstones on the status alone, but the predecessor refusal does not apply)." }, "predecessorUnitId": { "type": [ "string", "null" ], "description": "Art. 77(7) lineage: the original unit this battery was repurposed/remanufactured from (`null` for first-life units)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serialNumber", "digitalLinkUri", "passportId", "tenantId", "manufacturedAt", "status", "ceasedAt", "predecessorUnitId", "createdAt", "updatedAt" ] }, "BatteryUnitEventRow": { "type": "object", "description": "One immutable per-unit telemetry record (raw persisted row). Append-only: no update or delete path exists.", "properties": { "id": { "type": "string" }, "batteryUnitId": { "type": "string" }, "tenantId": { "type": "string" }, "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "State of health, percent." }, "cycleCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative full-equivalent cycles (truncated to an integer on write)." }, "remainingCapacityAh": { "type": [ "number", "null" ], "minimum": 0, "description": "Measured remaining capacity, ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "minimum": -273.15, "maximum": 10000, "description": "Observed temperature, °C." }, "payload": { "type": [ "object", "array", "null" ], "description": "Free-form additional telemetry/context as persisted: a JSON object **or array** (both pass the server's `typeof` check and are stored verbatim); `null` when omitted or when the submitted value was dropped (any non-object, non-array value)." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied; server time when omitted)." }, "createdAt": { "type": "string", "format": "date-time", "description": "Immutable append timestamp (server-assigned)." } }, "required": [ "id", "batteryUnitId", "tenantId", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt", "createdAt" ] }, "BatteryUnitCreateItem": { "type": "object", "description": "One unit to serialise. Validation is per-item: an invalid item is skipped (its error string collected) without failing the rest of the batch.", "properties": { "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$", "description": "Required. The battery's real physical serial (GS1 AI-21). Trimmed, then must match `^[A-Za-z0-9._-]{1,64}$`. Must be unique within the passport (duplicates are skipped with an item error)." }, "manufacturedAt": { "type": [ "string", "number" ], "description": "Optional. Any value accepted by JavaScript `Date` parsing (ISO 8601 recommended; epoch milliseconds also work). Invalid dates skip the item." }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus", "description": "Optional initial status. Defaults to `IN_SERVICE`. Note: creating a unit directly with `RECYCLED` makes the public view a 410 tombstone but does NOT stamp `ceasedAt` (only the events-route transition does), so such a unit can still be referenced as a predecessor.", "default": "IN_SERVICE" }, "predecessorUnitId": { "type": "string", "description": "Optional Art. 77(7) linkage: id of an existing unit **in your tenant** (any passport) that this battery was repurposed/remanufactured from. A recycled predecessor (`ceasedAt` set) is refused — the check keys on `ceasedAt`, which only the events-route `RECYCLED` transition stamps. Atomically with creation, a `STATUS_CHANGE` event (`{status, successorUnitId, successorSerial}`) is appended to the predecessor and its status set to `predecessorStatus`." }, "predecessorStatus": { "type": "string", "enum": [ "REPURPOSED", "REMANUFACTURED", "REUSED" ], "default": "REPURPOSED", "description": "Optional; only meaningful with `predecessorUnitId`. The status the predecessor transitions to. Defaults to `REPURPOSED`." } }, "required": [ "serialNumber" ] }, "SerializeBatteryUnitsRequest": { "description": "Either a single unit object, or a batch wrapper `{units: [...]}`. Precedence: when `units` is present **and is an array** it is used; otherwise the whole body is treated as one unit. (`anyOf`, not `oneOf`: a body carrying both a top-level `serialNumber` and a `units` array matches both shapes and is accepted by the server — `units` wins.)", "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitCreateItem" }, { "type": "object", "properties": { "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitCreateItem" }, "minItems": 1, "maxItems": 200, "description": "1–200 units per request. An empty array is rejected with 400 `Bad Request`; more than 200 likewise." } }, "required": [ "units" ] } ] }, "SerializeBatteryUnitsResponse": { "type": "object", "description": "Returned (201) when at least one unit was created. Partial success is possible: skipped items are reported in `errors` while `units` holds the created rows.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "E.g. `Serialised 2 individual unit(s)` or `Serialised 1 individual unit(s), skipped 1`." }, "count": { "type": "integer", "minimum": 1, "description": "Number of units actually created (equals `units.length`)." }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitRow" } }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Present only when some items were skipped — one plain-English string per skipped item, generally prefixed `[]`." } }, "required": [ "success", "message", "count", "units" ] }, "BatteryUnitSerialisationFailedError": { "type": "object", "description": "400 body when **every** item in the serialisation batch failed. Note: `errors` is an array of plain strings and there is **no `message` field** (unlike the standard error triple).", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Serialisation Failed" }, "errors": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "success", "error", "errors" ] }, "BatteryUnitListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "minimum": 0, "description": "Equals `units.length` (the endpoint is unpaginated)." }, "productId": { "type": "string", "description": "The passport's caller-supplied product identifier (GTIN-14 / GRAI / SKU)." }, "units": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitRow" }, "description": "All units of the passport, `createdAt` DESC." } }, "required": [ "success", "count", "productId", "units" ] }, "BatteryUnitDynamicDataEvent": { "type": "object", "description": "One telemetry event in the JSON-LD `dynamicData` history (privileged view only).", "properties": { "@type": { "type": "string", "const": "BatteryUnitEvent" }, "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ] }, "cycleCount": { "type": [ "integer", "null" ] }, "remainingCapacityAh": { "type": [ "number", "null" ] }, "temperatureC": { "type": [ "number", "null" ] }, "payload": { "type": [ "object", "array", "null" ], "description": "The persisted free-form payload — a JSON object **or array** (arrays pass the write-path `typeof` check), `null` when absent." }, "recordedAt": { "type": "string", "format": "date-time" } }, "required": [ "@type", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt" ] }, "BatteryUnitJsonLd": { "type": "object", "description": "JSON-LD document for one serialised battery unit, **privileged tenant view** (`isPrivileged=true`): includes `currentState` + `dynamicData` telemetry (restricted to legitimate-interest holders/authorities on the public view, where a `restrictedData` marker appears instead — never on this endpoint).", "properties": { "@context": { "type": "array", "description": "JSON-LD context: the shared `https://w3id.org/dpp/context/v1` IRI plus an inline term map for the battery-unit vocabulary.", "items": { "type": [ "string", "object" ] } }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri", "description": "The unit's GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, "digitalLinkUri": { "type": "string", "format": "uri" }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus" }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "repurposedFrom": { "oneOf": [ { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, { "type": "null" } ], "description": "Art. 77(7) predecessor link. **Always `null` on `GET /api/v1/units/{id}`** — the authenticated handler does not load the lineage relation; use the public resolver `GET /unit/{id}` to see resolved lineage." }, "successorUnits": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, "description": "Units repurposed/remanufactured from this one. **Always `[]` on `GET /api/v1/units/{id}`** (relation not loaded; see `repurposedFrom`)." }, "ofModel": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The SKU/type-level passport this unit is an instance of. On this authenticated endpoint it is rendered in the **owner (privileged, unredacted) variant**: legitimate-interest-tier metadata keys and owner-only keys (e.g. `facilityDetails`) are NOT masked, unlike the anonymous public document this schema describes. The passport's own `@context` inline map always carries 9 fixed terms (DigitalProductPassport, economicOperator, manufacturingFacility, metadata, digitalSeal, signingPublicKey, status, archivedAt, retentionUntil) plus one dynamically generated term per metadata key." }, "currentState": { "oneOf": [ { "$ref": "#/components/schemas/BatteryUnitCurrentState" }, { "type": "null" } ] }, "dynamicData": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitDynamicDataEvent" }, "maxItems": 500, "description": "Full telemetry history, newest first by `recordedAt`, capped at the 500 most recent events." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "@context", "@type", "@id", "id", "serialNumber", "digitalLinkUri", "status", "manufacturedAt", "repurposedFrom", "successorUnits", "ofModel", "currentState", "dynamicData", "createdAt", "updatedAt" ] }, "BatteryUnitDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Battery unit deleted." } }, "required": [ "success", "message" ] }, "RecordBatteryUnitEventRequest": { "type": "object", "description": "One telemetry record. All measurements are optional and independently nullable; numeric ranges are enforced with 400 on violation.", "properties": { "eventType": { "$ref": "#/components/schemas/BatteryUnitEventType" }, "stateOfHealth": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "State of health, percent (0–100)." }, "cycleCount": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Cumulative full-equivalent cycles. Fractional values are accepted but truncated to an integer before persisting." }, "remainingCapacityAh": { "type": [ "number", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Remaining capacity, ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "minimum": -273.15, "maximum": 10000, "description": "Observed temperature, °C." }, "payload": { "type": [ "object", "array", "null" ], "description": "Free-form JSON with additional telemetry/context. Objects **and arrays** pass the server's `typeof` check and are persisted verbatim; any other value (string, number, boolean) — and an explicit `null` — is silently dropped and stored as `null`." }, "recordedAt": { "type": [ "string", "number" ], "description": "When the measurement was taken. Any value accepted by JavaScript `Date` parsing (ISO 8601 recommended; epoch milliseconds also work); 400 if unparseable. Defaults to the server's current time." }, "status": { "$ref": "#/components/schemas/BatteryUnitStatus", "description": "Optional status transition, applied to the unit in the same transaction when it differs from the current status (works with any `eventType`; conventionally paired with `STATUS_CHANGE`). Transitioning to `RECYCLED` stamps `ceasedAt` (if not already set; never cleared) and turns the public unit view into a 410 tombstone (Art. 77(8)); `status` itself is not locked afterwards — a later event may still set a different value — but `ceasedAt` persists, so the 410 and the predecessor refusal are permanent." } }, "required": [ "eventType" ] }, "RecordBatteryUnitEventResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Dynamic data recorded" }, "event": { "$ref": "#/components/schemas/BatteryUnitEventRow" } }, "required": [ "success", "message", "event" ] }, "BatteryUnitEventListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "minimum": 0, "maximum": 500, "description": "Equals `events.length`; never exceeds 500." }, "serialNumber": { "type": "string", "description": "The unit's physical serial (GS1 AI-21 value)." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitEventRow" }, "maxItems": 500, "description": "Newest first by `recordedAt`, capped at the 500 most recent." } }, "required": [ "success", "count", "serialNumber", "events" ] }, "FacilityRow": { "type": "object", "description": "A facility (GS1 GLN) master-data row, exactly as stored. Returned in full to the owning tenant. Public exposure in passport documents differs by format: the *JSON-LD* document exposes `id`, `gln`, `name`, `activity` and `country` of a linked facility; the *AAS* export emits only the GLN, name and country (`manufacturingFacilityGln`/`Name`/`Country`). `streetAddress`, `city` and `postalCode` are emitted only to the owning/bound tenant in both formats.", "required": [ "id", "gln", "name", "activity", "streetAddress", "city", "postalCode", "country", "operatorId", "tenantId", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Facility id (UUID)." }, "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 Global Location Number — 13 digits with a valid GS1 modulo-10 check digit. Unique platform-wide. Immutable after registration (it is the resolvable UFI)." }, "name": { "type": "string", "description": "Facility display name (trimmed, non-empty)." }, "activity": { "type": [ "string", "null" ], "description": "Free-text activity, e.g. \"Cell assembly\", \"Final manufacturing\", \"Recycling\". Public in JSON-LD; not emitted in the AAS export." }, "streetAddress": { "type": [ "string", "null" ], "description": "Street address. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "city": { "type": [ "string", "null" ], "description": "City. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "postalCode": { "type": [ "string", "null" ], "description": "Postal code. Owner-only: redacted from public JSON-LD and never emitted in AAS." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "2-letter ISO 3166-1 alpha-2 country code, stored uppercase. Public in both JSON-LD and AAS." }, "operatorId": { "type": [ "string", "null" ], "description": "Id of the owning Economic Operator, or null for a tenant-level facility. Set at creation; not updatable via PUT." }, "tenantId": { "type": "string", "description": "Owning tenant workspace id." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "FacilityCreateRequest": { "type": "object", "required": [ "gln", "name", "country" ], "properties": { "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 GLN-13. Trimmed, then validated: exactly 13 digits with a valid GS1 modulo-10 check digit. Unique platform-wide (409 on duplicate). Immutable after registration." }, "name": { "type": "string", "minLength": 1, "description": "Facility name. Must be a non-empty string; stored trimmed." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "2-letter ISO country code (case-insensitive on input; stored uppercase)." }, "activity": { "type": "string", "description": "Optional activity, e.g. \"Cell assembly\". Trimmed; empty/whitespace is stored as null." }, "streetAddress": { "type": "string", "description": "Optional street address (owner-only in public views). Trimmed; empty is stored as null." }, "city": { "type": "string", "description": "Optional city (owner-only in public views). Trimmed; empty is stored as null." }, "postalCode": { "type": "string", "description": "Optional postal code (owner-only in public views). Trimmed; empty is stored as null." }, "operatorId": { "type": "string", "description": "Optional owning Economic Operator id. Must be bound to your tenant workspace (403 otherwise). Empty/whitespace is treated as absent. Operator-scoped API keys may only use their own operator id (it is applied automatically when omitted)." } } }, "FacilityUpdateRequest": { "type": "object", "description": "Partial update. `gln` and `operatorId` are immutable — if present they are silently ignored, as is any unknown key. For `activity`/`streetAddress`/`city`/`postalCode` the *presence* of the key matters: the value is stringified and trimmed, and anything that trims to empty (null, \"\", or a whitespace-only string) clears the field to null — the same normalization as POST.", "properties": { "name": { "type": "string", "minLength": 1, "description": "New name. Applied only when a non-empty string; empty/whitespace or non-string values are silently ignored (the name can never be cleared)." }, "activity": { "type": [ "string", "null" ], "description": "New activity, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "streetAddress": { "type": [ "string", "null" ], "description": "New street address, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "city": { "type": [ "string", "null" ], "description": "New city, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "postalCode": { "type": [ "string", "null" ], "description": "New postal code, or null/\"\" to clear. A whitespace-only string is stored as \"\" (see schema description)." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "New 2-letter ISO country code (400 if a string that does not match; stored uppercase; non-string values are silently ignored)." } } }, "FacilityCreatedEnvelope": { "type": "object", "required": [ "success", "message", "facility" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Facility registered successfully" }, "facility": { "$ref": "#/components/schemas/FacilityRow" } } }, "FacilityListEnvelope": { "type": "object", "required": [ "success", "count", "facilities" ], "properties": { "success": { "type": "boolean", "const": true }, "count": { "type": "integer", "minimum": 0, "description": "Number of facilities returned (the list is unpaginated)." }, "facilities": { "type": "array", "items": { "$ref": "#/components/schemas/FacilityRow" }, "description": "All facilities in the workspace, sorted by createdAt descending. Operator-scoped keys see only their operator's facilities." } } }, "FacilityEnvelope": { "type": "object", "required": [ "success", "facility" ], "properties": { "success": { "type": "boolean", "const": true }, "facility": { "$ref": "#/components/schemas/FacilityRow" } } }, "FacilityDeletedEnvelope": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true } } }, "GrantRow": { "type": "object", "description": "Tenant-facing projection of an access grant. The token hash, issuer user id, revoking actor and request IP are never exposed; raw capability tokens appear only in the one-time issuance/approval responses. All fields are always present (nullable ones serialize as `null`).", "required": [ "id", "status", "kind", "granteeName", "granteeEmail", "organization", "purpose", "scopeType", "passportId", "batteryUnitId", "issuerType", "issuerEmail", "decidedAt", "decidedBy", "expiresAt", "revokedAt", "lastUsedAt", "useCount", "createdAt", "revocable" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "DENIED", "REVOKED" ], "description": "`PENDING` = undecided third-party request (no token exists yet); `ACTIVE` = usable token; `DENIED` = rejected request; `REVOKED` = soft-revoked." }, "kind": { "type": "string", "enum": [ "LEGITIMATE_INTEREST", "AUTHORITY" ], "description": "`LEGITIMATE_INTEREST` (`dpp_li_…` tokens, tenant-issued or approved from a request) or `AUTHORITY` (`dpp_auth_…` tokens, platform-issued for market surveillance; not tenant-revocable)." }, "granteeName": { "type": "string", "maxLength": 160 }, "granteeEmail": { "type": [ "string", "null" ], "maxLength": 254 }, "organization": { "type": [ "string", "null" ], "maxLength": 200 }, "purpose": { "type": [ "string", "null" ], "maxLength": 2000, "description": "The stated legitimate interest." }, "scopeType": { "type": "string", "enum": [ "UNIT", "PASSPORT", "TENANT" ], "description": "What the token unlocks on the public resolvers: a single battery unit, a single passport, or the whole workspace." }, "passportId": { "type": [ "string", "null" ], "description": "Set for `PASSPORT` scope, and also for `UNIT` scope (the unit's parent passport). `null` for `TENANT` scope." }, "batteryUnitId": { "type": [ "string", "null" ], "description": "Set only for `UNIT` scope." }, "issuerType": { "type": "string", "enum": [ "TENANT", "PLATFORM", "REQUEST" ], "description": "`TENANT` = issued directly via this API; `REQUEST` = submitted by a third party through the hosted request-access page; `PLATFORM` = platform-admin-issued (AUTHORITY grants)." }, "issuerEmail": { "type": [ "string", "null" ], "description": "E-mail of the issuing user; `null` when issued by an API key or created from a public request." }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When a PENDING request was approved/denied; `null` for direct issuances." }, "decidedBy": { "type": [ "string", "null" ], "description": "The deciding actor: a user e-mail, `API_KEY_` when decided via an API key, or the literal `unknown` in degenerate authentication states." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Hard expiry; the public resolvers reject the token after this instant. PENDING requests carry a provisional 90-day expiry that is replaced on approval." }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful use on a public resolver (book-kept best-effort)." }, "useCount": { "type": "integer", "description": "Successful public-resolver uses (incremented best-effort)." }, "createdAt": { "type": "string", "format": "date-time" }, "revocable": { "type": "boolean", "description": "Computed: `false` for `AUTHORITY` grants (platform-managed), `true` otherwise." } } }, "GrantRouteError": { "type": "object", "description": "Error body used by the grants endpoints' route-level errors (400/403/404/409). Unlike the standard error envelope, it has NO `success` field.", "required": [ "error", "message" ], "not": { "required": [ "success" ] }, "properties": { "error": { "type": "string", "description": "HTTP reason phrase, e.g. `Bad Request`, `Not Found`, `Conflict`, `Forbidden`." }, "message": { "type": "string", "description": "Human-readable explanation." } } }, "GrantListResponse": { "type": "object", "description": "List envelope for `GET /api/v1/grants`. Note: no `success` field.", "required": [ "grants" ], "properties": { "grants": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/GrantRow" }, "description": "At most 500 rows, ordered by `status` ascending then `createdAt` descending." } } }, "GrantIssuedResponse": { "type": "object", "description": "Returned by direct issuance (201) and request approval (200). `token` is the raw capability token — shown ONCE here (and, on approval, in the grantee's inspection-link e-mail); only its SHA-256 hash is persisted.", "required": [ "success", "grant", "token" ], "properties": { "success": { "type": "boolean", "const": true }, "grant": { "$ref": "#/components/schemas/GrantRow" }, "token": { "type": "string", "pattern": "^dpp_li_[0-9a-f]{32}$", "description": "Legitimate-interest capability token (`dpp_li_` + 32 lowercase hex). Present it to public resolution endpoints as `Authorization: Bearer ` or `?grant=`. Treat like a password — it cannot be retrieved again." } } }, "GrantDecisionResponse": { "type": "object", "description": "Returned by deny and revoke: the updated grant, no token.", "required": [ "success", "grant" ], "properties": { "success": { "type": "boolean", "const": true }, "grant": { "$ref": "#/components/schemas/GrantRow" } } }, "CreateGrantRequest": { "type": "object", "description": "Direct-issuance body. Over-length strings are silently truncated to the documented maximum, not rejected; unknown fields are ignored. The grant kind is always `LEGITIMATE_INTEREST` — there is no `kind`/`type` field.", "required": [ "granteeName", "scopeType", "expiresAt" ], "properties": { "granteeName": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Required (whitespace-only is rejected as missing). Truncated to 160 characters." }, "granteeEmail": { "type": "string", "format": "email", "maxLength": 254, "description": "Optional. Truncated to 254 characters, then must match a basic e-mail pattern (`x@y.z`) or the request fails with 400 `granteeEmail is invalid`. Stored as given (not lowercased)." }, "organization": { "type": "string", "maxLength": 200, "description": "Optional. Truncated to 200 characters." }, "purpose": { "type": "string", "maxLength": 2000, "description": "Optional stated legitimate interest. Truncated to 2000 characters." }, "scopeType": { "type": "string", "enum": [ "UNIT", "PASSPORT", "TENANT" ], "description": "Required. `UNIT` needs `batteryUnitId`; `PASSPORT` needs `passportId`; `TENANT` is workspace-wide. Any other value ⇒ 400." }, "passportId": { "type": "string", "maxLength": 64, "description": "Required when `scopeType` is `PASSPORT`; ignored otherwise. Must be a non-DRAFT passport in this workspace — a missing, cross-tenant, or `DRAFT` id (or omitting the field entirely) returns 404." }, "batteryUnitId": { "type": "string", "maxLength": 64, "description": "Required when `scopeType` is `UNIT`; ignored otherwise. Must be a battery unit in this workspace — a missing or cross-tenant id (or omitting the field entirely) returns 404." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Required. Date parsing is lenient (some non-ISO values may be accepted) — ISO 8601 is strongly recommended. Must be in the future and at most 366 days from now." } } }, "ApproveGrantRequest": { "type": "object", "description": "Approval body — only the final expiry is supplied; everything else comes from the original request.", "required": [ "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "Required. Date parsing is lenient (some non-ISO values may be accepted) — ISO 8601 is strongly recommended. Must be in the future and at most 366 days from now. Replaces the request's provisional 90-day expiry." } } }, "OperatorRow": { "type": "object", "description": "An economic-operator record (`EconomicOperator`). Operators are deduplicated platform-wide on `regId` and may be shared between workspaces via tenant bindings. Returned verbatim from the database (no field stripping); nullable fields are serialized as `null`.", "required": [ "id", "name", "regId", "regIdScheme", "role", "archivedAt", "createdAt" ], "properties": { "id": { "type": "string", "description": "Operator UUID." }, "name": { "type": "string", "description": "Legal/display name of the operator." }, "regId": { "type": "string", "description": "Official registration id (EORI number, VAT id, DUNS, or national business-registry id). Unique platform-wide and immutable after registration." }, "regIdScheme": { "type": [ "string", "null" ], "enum": [ "EORI", "VAT", "DUNS", "NATIONAL", "OTHER", null ], "description": "Which kind of registration id `regId` is. `null` = unspecified national/business id. When `EORI`, `regId` is guaranteed to satisfy the EORI syntax `^[A-Z]{2}[A-Za-z0-9]{1,15}$`." }, "role": { "type": "string", "description": "Supply-chain role, free text — e.g. `\"MANUFACTURER\"`, `\"IMPORTER\"`, `\"RETAILER\"`. Defaults to `\"MANUFACTURER\"` at registration." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete / cessation-of-trading marker. Non-null = the operator is archived (its passports are retained and still publicly resolvable)." }, "createdAt": { "type": "string", "format": "date-time" } } }, "RegisterOperatorRequest": { "type": "object", "required": [ "name", "regId" ], "properties": { "name": { "type": "string", "description": "Legal/display name. Ignored if an operator with this `regId` already exists platform-wide (the existing record is bound instead)." }, "regId": { "type": "string", "description": "Official registration id (EORI, VAT, DUNS, or national registry id). Unique platform-wide; immutable after registration. Fabricated `EORI-MOCK…` ids are rejected. When `regIdScheme` is `EORI`, must match `^[A-Z]{2}[A-Za-z0-9]{1,15}$` (e.g. `DE1234567890`)." }, "regIdScheme": { "type": [ "string", "null" ], "description": "Optional declaration of what kind of id `regId` is. Allowed values: `EORI`, `VAT`, `DUNS`, `NATIONAL`, `OTHER` — matched case-insensitively (uppercased server-side). Any other value is rejected with `400`. Omit or send `null` for an unspecified national/business id. Ignored when binding to an existing operator." }, "role": { "type": "string", "default": "MANUFACTURER", "description": "Supply-chain role, free text — e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`. Defaults to `MANUFACTURER`. Ignored when binding to an existing operator." } } }, "RegisterOperatorResponse": { "type": "object", "required": [ "success", "message", "operator" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Always `\"Economic Operator supplier registered successfully\"` (also when an existing operator was bound rather than created)." }, "operator": { "$ref": "#/components/schemas/OperatorRow" } } }, "UpdateOperatorRequest": { "type": "object", "description": "Both fields are optional. Values must be non-empty strings after trimming; anything else (missing, non-string, whitespace-only) is silently ignored. `regId` and `regIdScheme` cannot be changed. An omitted body or an empty object `{}` is accepted and returns the unchanged row.", "properties": { "name": { "type": "string", "description": "New display name (trimmed)." }, "role": { "type": "string", "description": "New supply-chain role, free text (trimmed) — e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`." } } }, "UpdateOperatorResponse": { "type": "object", "required": [ "success", "operator" ], "properties": { "success": { "type": "boolean", "const": true }, "operator": { "$ref": "#/components/schemas/OperatorRow" } } }, "DeleteOperatorResponse": { "type": "object", "required": [ "success", "archived" ], "properties": { "success": { "type": "boolean", "const": true }, "archived": { "type": "boolean", "description": "`true` = the operator was archived (soft-deleted; passports retained, restorable). `false` = the operator was hard-deleted (it had no passports)." }, "archivedPassports": { "type": "integer", "minimum": 0, "description": "Number of active passports archived alongside the operator. Present only on the primary archive path (operator had passports); absent on hard deletes and on the foreign-key fallback archive." } } }, "RestoreOperatorResponse": { "type": "object", "required": [ "success", "restoredPassports" ], "properties": { "success": { "type": "boolean", "const": true }, "restoredPassports": { "type": "integer", "minimum": 0, "description": "Number of archived passports returned to the active catalogue (`archivedAt` and `retentionUntil` cleared). Passports independently DECOMMISSIONED are not restored and not counted." } } }, "RotateTenantKeysResponse": { "type": "object", "required": [ "success", "message", "publicKey" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Always `\"eIDAS Asymmetric Key Pair generated and rotated in secure DB custody successfully\"`." }, "publicKey": { "type": "string", "description": "The new ECDSA prime256v1 (P-256) public key, PEM-encoded (SPKI, `-----BEGIN PUBLIC KEY-----` block, trailing newline). The matching private key is held only AES-256-GCM-encrypted in the platform vault and is never returned." } } }, "OperatorMinimalError": { "type": "object", "description": "Minimal error envelope used by the operator/key self-service handlers — note the standard `error` key is ABSENT (unlike the shared Error schema).", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" } } }, "PassportMetadataInput": { "type": "object", "description": "The ESPR product metadata payload. For non-draft ingestion and for the validate-only endpoints, `category` is mandatory and must be one of the 9 ESPR categories; each category then mandates its own field set (e.g. textiles require `fiberComposition`, `careInstructions`, `size`; batteries require `batteryCategory`, `chemistry`, `electrochemicalCapacity`, `durability`, `recycledContentShare`, `carbonFootprint`). For five categories — textiles, batteries, electronics, chemicals, construction — the authoritative per-category JSON Schema (required fields, value constraints, field help) is served live at `GET /api/v1/schemas/{category}`; the other four (cosmetics, toys, iron-steel, aluminium) are validated by built-in server-side rules and `GET /api/v1/schemas/{category}` returns 404 for them. Cross-field rules are enforced on top: `materialComposition` (and textile `fiberComposition`) percentages must sum to 100 ±0.1, `originCountry` must be a real ISO 3166-1 alpha-2 code, textile hazardous-substance concentrations are checked against REACH ppm limits. A documented set of supplementary objects (e.g. `technicalProperties`, `environmentalFootprint`, `circularityAttributes`, `esgDueDiligence`, `detailedPerformance`) produce non-blocking `warnings` instead of `errors` when malformed. With `draft: true` (single ingestion only) validation is skipped entirely and any object is accepted.", "properties": { "category": { "type": "string", "enum": [ "textiles", "batteries", "electronics", "cosmetics", "toys", "iron-steel", "aluminium", "chemicals", "construction" ], "description": "ESPR product category; selects the validation rules. Required whenever validation runs (i.e. always, except `draft: true` single ingestion)." }, "originCountry": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code (validated against the full 249-code set)." } }, "additionalProperties": true }, "PassportEnrichmentInput": { "type": "object", "description": "Optional presentational (non-regulatory) marketing enrichment, stored OUTSIDE the ESPR-validated metadata and the Merkle seal; it never appears in the JSON-LD passport document. Server-side it is whitelist-sanitized rather than rejected: unknown keys are dropped; `tagline` is trimmed and capped at 200 chars, `description` at 4000, image `caption` at 200, link `label` at 120; at most 24 `images` and 24 `links` are kept; URLs must be http, https, or mailto (any other scheme, e.g. `javascript:` or `data:`, is silently dropped). An enrichment that sanitizes down to nothing is stored as null.", "properties": { "tagline": { "type": "string", "description": "Short marketing tagline (server-capped at 200 chars)." }, "description": { "type": "string", "description": "Marketing description (server-capped at 4000 chars)." }, "images": { "type": "array", "description": "Up to 24 kept. Items without a valid http/https/mailto `url` are dropped.", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "http, https, or mailto only." }, "caption": { "type": "string", "description": "Server-capped at 200 chars." } } } }, "links": { "type": "array", "description": "Up to 24 kept. Items without a valid http/https/mailto `url` are dropped; a missing `label` defaults to the URL.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Server-capped at 120 chars." }, "url": { "type": "string", "format": "uri", "description": "http, https, or mailto only." } } } } }, "additionalProperties": true }, "PassportCreateRequest": { "type": "object", "required": [ "productId", "metadata" ], "properties": { "productId": { "type": "string", "minLength": 1, "description": "Product identifier: a GTIN-14 (exactly 14 digits with a valid GS1 mod-10 check digit — auto-copied to `metadata.gtin`), a GRAI (14-digit numeric asset id with valid check digit + optional up to 16 alphanumeric serial chars, total 14–30 — auto-copied to `metadata.grai`), or a free-form SKU. Determines the GS1 Application Identifier (`01` vs `8003`) in the generated Digital Link URI. Whitespace-only values are rejected 400. Unique per economic operator (409 on duplicate)." }, "operatorId": { "type": "string", "description": "UUID of an EconomicOperator bound to your tenant workspace (403 if not bound). Defaults to your workspace's first bound operator. Operator-scoped API keys force their own operator (403 on mismatch)." }, "facilityId": { "type": "string", "description": "Optional UUID of a Facility (GLN-backed Unique Facility Identifier) in your workspace; 400 if not found." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" }, "draft": { "type": "boolean", "default": false, "description": "When true: skips ALL ESPR/traceability validation, stores the passport with `status: \"DRAFT\"` (not publicly resolvable), and emits no webhook. Publish later via a validated edit." }, "enrichment": { "$ref": "#/components/schemas/PassportEnrichmentInput" } } }, "PassportIngestCreated": { "type": "object", "required": [ "success", "message", "passport", "warnings" ], "description": "201 envelope of `POST /api/v1/passports`. Only these four top-level keys are ever emitted.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "\"Digital Product Passport successfully validated and ingested\", or \"Draft passport saved\" when `draft: true`." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The PUBLIC redacted JSON-LD passport document (unsealed at creation: `digitalSeal`/`proof` are null). The owner-only metadata key `facilityDetails` is always replaced with the literal string \"[REDACTED - Privileged Access Required]\" — even in this creator-facing echo, and even when the submitted metadata did not contain it. For `category: \"batteries\"`, the restricted legitimate-interest keys `detailedPerformance`, `lifecycleAndInUse`, and `circularityAndDisassembly` are masked the same way when present." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Non-blocking validation findings. Always present; empty array when none and always empty for drafts." } } }, "PassportValidateOnlyRequest": { "type": "object", "required": [ "productId", "metadata" ], "properties": { "productId": { "type": "string", "minLength": 1, "description": "Product identifier (GTIN-14 / GRAI / SKU). Required and checked non-empty (whitespace-only → 400), but not otherwise used by the dry-run." }, "operatorId": { "type": "string", "description": "Accepted by the body schema but IGNORED by the validate-only handlers." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" } } }, "PassportValidateOnlyResult": { "type": "object", "required": [ "success", "message", "category", "errors" ], "description": "200 envelope of the validate-only endpoints (only the declared keys are emitted).", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Passport metadata payload is 100% valid and ESPR category compliant" }, "category": { "type": "string", "description": "Echo of `metadata.category` (or \"unknown\" if absent)." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "maxItems": 0, "description": "Always an empty array on 200." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Non-blocking findings (e.g. malformed supplementary objects like `circularityAttributes`). The key is OMITTED entirely when there are no warnings — it is never an empty array." } } }, "PassportValidateOnlyError": { "type": "object", "required": [ "error", "message" ], "description": "400 envelope of the validate-only endpoints. Three variants: ESPR validation failure (`error: \"Validation Failed\"`, with `success`, `category`, `errors[]`, optional `warnings[]` — omitted when none; category-validity error items carry no `friendlyMessage`); whitespace-only `productId` (`error: \"Bad Request\"`, `category: \"unknown\"`, `errors: []`, no `warnings`); and structural request rejections (body-schema violations, malformed JSON), which return only `error` + `message`.", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "enum": [ "Bad Request", "Validation Failed" ] }, "message": { "type": "string" }, "category": { "type": "string", "description": "`metadata.category` echo, or \"unknown\" for structural failures." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Omitted when there are no warnings." } } }, "PassportBulkRow": { "type": "object", "description": "One bulk-ingestion row. The HTTP layer only requires each row to be an object; rows missing `productId` or `metadata`, failing ESPR validation, referencing unbound operators/unknown facilities, or duplicating an existing `(productId, operatorId)` pair are SKIPPED and reported as strings in the response `errors[]` — they never fail the whole request (unless every row fails). Bulk rows do not support `draft` or `enrichment`, are always created with `status: \"ACTIVE\"`, skip the EPCIS traceability audit, and do NOT get `metadata.gtin`/`metadata.grai` auto-injected.", "properties": { "productId": { "type": "string", "description": "GTIN-14 / GRAI / free-form SKU (required in practice; rows without it are skipped with an error string)." }, "operatorId": { "type": "string", "description": "Optional EconomicOperator UUID bound to your workspace; defaults to the workspace's first bound operator. Operator-scoped API keys force their operator." }, "facilityId": { "type": "string", "description": "Optional Facility UUID in your workspace; unknown ids skip the row." }, "metadata": { "$ref": "#/components/schemas/PassportMetadataInput" } }, "additionalProperties": true }, "PassportBulkRequest": { "type": "object", "required": [ "passports" ], "properties": { "passports": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/PassportBulkRow" }, "description": "1–200 rows. The bounds are enforced before any row is processed; violations return the default `{statusCode, code, error, message}` error body." } } }, "PassportBulkResult": { "type": "object", "required": [ "success", "message", "insertedCount", "results" ], "description": "201 partial-success envelope of `POST /api/v1/passports/bulk`. Returned whenever at least one row was inserted, even if other rows failed.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "description": "Template: \"Bulk CSV ingestion finished. Registered passports, skipped rows with errors.\"" }, "insertedCount": { "type": "integer", "minimum": 0, "description": "Number of rows actually inserted (= `results.length`)." }, "results": { "type": "array", "items": { "type": "object", "required": [ "productId", "digitalLinkUri" ], "properties": { "productId": { "type": "string" }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "Generated GS1 Digital Link URI `https://opendpp-node.eu/{01|8003}/{productId}/21/{passportId}`." } } } }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Human-readable per-row failure strings, prefixed `[SKU: ]` (or \"Missing or invalid productId in spreadsheet row\"). Present ONLY when at least one row failed — omitted otherwise." } } }, "PassportBulkFailure": { "type": "object", "required": [ "success", "error", "errors" ], "description": "400 body of `POST /api/v1/passports/bulk` when EVERY row failed. Note: `errors` is an array of STRINGS (not objects) and there is NO `message` field.", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Bulk Ingestion Failed" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "One human-readable string per failed row, prefixed `[SKU: ]` where the productId was readable." } } }, "AasEnvironmentInput": { "type": "object", "required": [ "submodels" ], "description": "An Asset Administration Shell (AAS) JSON Environment — the format produced by OpenDPP's AAS export of a passport. MUST contain a submodel with `idShort: \"ComplianceMetadata\"` whose `submodelElements` (AAS `Property` elements and `SubmodelElementCollection`s) are parsed back into the passport metadata object; absence fails 400 `Ingestion Failed`. MAY contain an `eidasVerificationSeal` submodel (elements `digitalSealHash`, `cryptographicSignature`, `pemPublicKey`) — when present, the seal is verified against the tenant's SERVER-HELD eIDAS public key (the embedded `pemPublicKey` is never trusted as the verification key). Body limit 256 KiB.", "properties": { "assetAdministrationShells": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "AAS shells. The first shell's `assetInformation.specificAssetIds` entry with `name: \"productId\"` is the last-resort productId source (after `metadata.gtin`/`metadata.grai`/`metadata.productId`)." }, "submodels": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Must include the `ComplianceMetadata` submodel; may include `eidasVerificationSeal`." }, "conceptDescriptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "AasIngestCreated": { "type": "object", "required": [ "success", "message", "passportId", "productId", "isSealed", "signatureVerified" ], "description": "201 envelope of `POST /api/v1/passports/aas/ingest`. Returned for both newly created passports and in-place updates of existing UNSEALED passports. No webhook event is emitted by this endpoint.", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Digital Product Passport successfully ingested from AAS" }, "passportId": { "type": "string" }, "productId": { "type": "string" }, "isSealed": { "type": "boolean", "description": "True when the environment embedded an `eidasVerificationSeal` submodel (the seal is then stored on the passport)." }, "signatureVerified": { "type": "boolean", "description": "True when the embedded seal verified against the tenant's server-held eIDAS public key. Always false for unsealed documents. (A sealed-but-unverified document never reaches 201 — it fails 400.)" } } }, "PassportListResponse": { "type": "object", "description": "Envelope of GET /api/v1/passports. The response is serialized against a declared response schema: top-level keys other than these four are stripped. There is NO total count.", "required": [ "success", "page", "limit", "passports" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "page": { "type": "integer", "minimum": 1, "description": "Effective page after server-side clamping (min 1)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Effective page size after server-side clamping (default 10, max 100)." }, "passports": { "type": "array", "items": { "$ref": "#/components/schemas/PassportListItem" } } } }, "PassportAasEnvironment": { "type": "object", "description": "IDTA Asset Administration Shell environment (returned when `Accept` contains `application/aas+json`), role-filtered for the caller's access tier. Identifiers use `urn:opendpp:*` forms: the shell id is `urn:opendpp:aas:` with idShort `AAS_` and `globalAssetId` `urn:opendpp:asset::` (plus `specificAssetIds` carrying the productId and, when a facility is assigned, its GLN). The environment always contains two submodels — `GeneralProductInformation` (`urn:opendpp:submodel:general:`) and `ComplianceMetadata` (`urn:opendpp:submodel:compliance`) — and an `eidasVerificationSeal` submodel is appended when the tenant has signing keys configured. Loose schema — the full AAS document structure is documented with the public resolution endpoints.", "required": [ "assetAdministrationShells", "submodels", "conceptDescriptions" ], "properties": { "assetAdministrationShells": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "submodels": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "conceptDescriptions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "PassportUpdateRequest": { "type": "object", "description": "Body of PUT /api/v1/passports/{id}. Unknown keys are ignored.", "required": [ "metadata" ], "additionalProperties": true, "properties": { "metadata": { "type": "object", "description": "Full replacement ESPR metadata object. `metadata.category` must be one of: textiles, batteries, electronics, cosmetics, toys, iron-steel, aluminium, chemicals, construction. Validated against the category's compliance rules unless `draft: true` (400 with `errors[]` on failure — no `warnings` on this route). A machine-readable JSON Schema is published at GET /api/v1/schemas/{category} for **textiles, batteries, electronics, chemicals and construction only** — cosmetics, toys, iron-steel and aluminium are validated by built-in rules and return 404 from that endpoint." }, "draft": { "type": "boolean", "default": false, "description": "true = save as draft: skips ESPR validation and forces status DRAFT (this also demotes an already-published passport back to DRAFT). false/absent = validated save; a DRAFT passport is published (status ACTIVE, emits the passport.ingested webhook)." }, "changeReason": { "type": "string", "description": "Free-text reason recorded on the version-history snapshot. Defaults to \"API Update\"." }, "facilityId": { "type": [ "string", "null" ], "description": "GLN-backed facility assignment. Omit to leave unchanged; null or \"\" detaches; a UUID attaches a facility that must be owned by your tenant (otherwise 400)." }, "enrichment": { "oneOf": [ { "$ref": "#/components/schemas/PassportEnrichmentInput" }, { "type": "null" } ], "description": "Presentational marketing block stored OUTSIDE the ESPR-validated metadata and the Merkle seal. Include the key (even null/{}) to overwrite; omit to leave unchanged. An empty result after sanitation clears the block." } } }, "PassportUpdateResponse": { "type": "object", "description": "200 envelope of PUT /api/v1/passports/{id}. The passport document is serialized at the PUBLIC redaction tier (owner-only/restricted metadata keys masked) even for the owner.", "required": [ "success", "message", "passport" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "enum": [ "Draft published", "Digital Product Passport successfully updated and history versioned" ], "description": "\"Draft published\" when a validated save promoted a DRAFT to ACTIVE; the longer message otherwise." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" } } }, "PassportUpdateValidationError": { "type": "object", "description": "400 ESPR validation failure body of PUT /api/v1/passports/{id}. DIVERGENCE from POST /api/v1/passports: there is never a `warnings` array on this route.", "required": [ "success", "error", "message", "errors" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "Validation Failed" }, "message": { "type": "string", "const": "Dynamic metadata payload failed ESPR category compliance validation" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorItem" }, "description": "Blocking validation errors. `friendlyMessage` is localized via the `lang` query parameter / Accept-Language (default en)." } } }, "PassportSealResponse": { "type": "object", "description": "200 envelope of POST /api/v1/passports/{id}/seal. `digitalSeal` is duplicated inside `passport.digitalSeal` and `passport.proof.signatureValue`. The passport document is serialized at the PUBLIC redaction tier; masked keys keep their true leaf hashes in `proof.redactedLeaves`. Note: despite the message wording, this endpoint does not change the passport's `status`.", "required": [ "success", "message", "digitalSeal", "signingPublicKey", "passport" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "const": "Passport sealed with the tenant's eIDAS advanced electronic seal and published." }, "digitalSeal": { "type": "string", "description": "Base64 ECDSA P-256 (prime256v1) SHA-256 signature over the metadata Merkle root (eIDAS ADVANCED electronic seal — not a qualified seal, not a W3C DataIntegrityProof)." }, "signingPublicKey": { "type": "string", "description": "PEM-encoded public key of the tenant's signing key pair; verify the seal offline against `proof.merkleRoot`." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" } } }, "PassportStatusUpdateRequest": { "type": "object", "description": "Body of PUT /api/v1/passports/{id}/status. Only `status` is read; any other keys are ignored (there is no `reason` field).", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Target lifecycle state. DECOMMISSIONED starts the retention clock (retentionUntil = now + the configured retention period, default 15 years); ACTIVE reactivates (clears retentionUntil and archivedAt); RECALLED marks the product recalled. DRAFT is not a valid target — drafts are published via PUT /api/v1/passports/{id}." } } }, "PassportStatusUpdateResponse": { "type": "object", "description": "200 envelope of PUT /api/v1/passports/{id}/status. The passport document is serialized at the PUBLIC redaction tier.", "required": [ "success", "message", "status", "passport" ], "properties": { "success": { "type": "boolean", "description": "Always true on 200." }, "message": { "type": "string", "description": "`Passport status successfully updated to `." }, "status": { "type": "string", "enum": [ "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "The passport's new lifecycle state." }, "passport": { "$ref": "#/components/schemas/PublicPassportJsonLd" } } }, "PassportListItem": { "type": "object", "description": "One JSON-LD passport document as it appears in `GET /api/v1/passports` list responses. Same shape as `PublicPassportJsonLd` with list-specific divergences imposed by the route's declared response serialization: `economicOperator` never carries `role`; `manufacturingFacility` is always `null`; the `@context` term map (second array element) is emptied to `{}`; and `proof` is emptied to `{}` on sealed items (`null` on unsealed) — fetch the single passport for the verifiable proof block.", "additionalProperties": true, "required": [ "@context", "@type", "@id", "id", "productId", "digitalLinkUri", "digitalSeal", "signingPublicKey", "status", "archivedAt", "retentionUntil", "proof", "createdAt", "updatedAt", "economicOperator", "manufacturingFacility", "metadata" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "Exactly two entries: the context URL `https://w3id.org/dpp/context/v1` and an inline term map covering the 9 fixed DPP terms (`DigitalProductPassport`, `economicOperator`, `manufacturingFacility`, `metadata`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`) plus one generated term per metadata key (`https://w3id.org/dpp/context/v1#`)." }, "@type": { "type": "string", "const": "DigitalProductPassport" }, "@id": { "type": "string", "format": "uri", "description": "The passport's canonical GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string", "description": "Server-assigned passport UUID." }, "productId": { "type": "string", "description": "Caller-supplied product identifier: a GTIN-14 (`^[0-9]{14}$` with valid GS1 modulo-10 check digit), a GRAI (`^[0-9]{14}[A-Za-z0-9]{0,16}$`), or a free-form SKU." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "SKU/type-level GS1 Digital Link URI: `{BASE_URL}/{01|8003}/{productId}/21/{passportId}` (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial instead)." }, "digitalSeal": { "type": [ "string", "null" ], "description": "eIDAS ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. `null` when the passport has not been sealed." }, "signingPublicKey": { "type": [ "string", "null" ], "description": "PEM public key that verifies `digitalSeal`. `null` when unsealed." }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Passport lifecycle status (serialized as `ACTIVE` when unset). `DRAFT` is only ever visible to owner-tier callers — public/grant resolution of a draft returns 404." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete marker (owner off-boarded / decommissioned). Archived passports remain publicly resolvable (ESPR persistence duty)." }, "retentionUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Minimum-availability deadline; the passport is never purged before this instant." }, "proof": { "anyOf": [ { "type": "object", "additionalProperties": false, "description": "Always the empty object on sealed items — proof contents are stripped by the list serialization." }, { "type": "null" } ], "description": "`{}` when sealed, `null` when unsealed. The full `MerkleTreeAttestationProof` is only available on single-passport reads." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "economicOperator": { "anyOf": [ { "$ref": "#/components/schemas/EconomicOperatorNode" }, { "type": "null" } ], "description": "The economic operator (manufacturer/importer/retailer) responsible for the product. Public in all tiers." }, "manufacturingFacility": { "type": "null", "description": "Always `null` in list responses (facility nodes are only embedded on single-passport reads)." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string `[REDACTED - Privileged Access Required]` instead of their value." } } }, "PublicPassportJsonLd": { "type": "object", "description": "The public, redacted JSON-LD Digital Product Passport document (`application/ld+json`). All listed top-level keys are ALWAYS present (`null` where not applicable). Additionally, every key of the (masked) `metadata` object — except the reserved document keys (`@context`, `@type`, `@id`, `id`, `productId`, `digitalLinkUri`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`, `proof`, `createdAt`, `updatedAt`, `economicOperator`, `manufacturingFacility`, `metadata`) — is ALSO flattened onto the document root for direct semantic-graph querying (hence `additionalProperties: true`); flattened values are identical to the corresponding `metadata` values, including redaction placeholders. Tier-masked metadata keys are replaced (in both places) with the literal string `[REDACTED - Privileged Access Required]`. Masking by tier: anonymous public callers lose the per-category restricted keys (category `batteries`: `detailedPerformance`, `lifecycleAndInUse`, `circularityAndDisassembly` — masked only when actually present) AND the owner-only key `facilityDetails`; legitimate-interest/authority grant holders lose only `facilityDetails`; owner-tier responses are unmasked and additionally include the facility street address fields. Note: `facilityDetails` is placeholder-masked in EVERY non-owner response, even when the underlying metadata never contained the key — in that case it has no entry in `proof.redactedLeaves`. Each masked key that exists in the sealed metadata keeps its true Merkle leaf hash in `proof.redactedLeaves`, so the eIDAS seal stays verifiable offline after redaction (see `MerkleTreeAttestationProof` for the reconstruction rule).", "additionalProperties": true, "required": [ "@context", "@type", "@id", "id", "productId", "digitalLinkUri", "digitalSeal", "signingPublicKey", "status", "archivedAt", "retentionUntil", "proof", "createdAt", "updatedAt", "economicOperator", "manufacturingFacility", "metadata" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "Exactly two entries: the context URL `https://w3id.org/dpp/context/v1` and an inline term map covering the 9 fixed DPP terms (`DigitalProductPassport`, `economicOperator`, `manufacturingFacility`, `metadata`, `digitalSeal`, `signingPublicKey`, `status`, `archivedAt`, `retentionUntil`) plus one generated term per metadata key (`https://w3id.org/dpp/context/v1#`)." }, "@type": { "type": "string", "const": "DigitalProductPassport" }, "@id": { "type": "string", "format": "uri", "description": "The passport's canonical GS1 Digital Link URI (same value as `digitalLinkUri`)." }, "id": { "type": "string", "description": "Server-assigned passport UUID." }, "productId": { "type": "string", "description": "Caller-supplied product identifier: a GTIN-14 (`^[0-9]{14}$` with valid GS1 modulo-10 check digit), a GRAI (`^[0-9]{14}[A-Za-z0-9]{0,16}$`), or a free-form SKU." }, "digitalLinkUri": { "type": "string", "format": "uri", "description": "SKU/type-level GS1 Digital Link URI: `{BASE_URL}/{01|8003}/{productId}/21/{passportId}` (AI-21 carries the passport UUID at SKU level; individual units carry their physical serial instead)." }, "digitalSeal": { "type": [ "string", "null" ], "description": "eIDAS ADVANCED electronic seal: base64 ECDSA prime256v1 (P-256) signature over the Merkle root of the key-sorted metadata. `null` when the passport has not been sealed." }, "signingPublicKey": { "type": [ "string", "null" ], "description": "PEM public key that verifies `digitalSeal`. `null` when unsealed." }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "RECALLED", "DECOMMISSIONED" ], "description": "Passport lifecycle status (serialized as `ACTIVE` when unset). `DRAFT` is only ever visible to owner-tier callers — public/grant resolution of a draft returns 404." }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete marker (owner off-boarded / decommissioned). Archived passports remain publicly resolvable (ESPR persistence duty)." }, "retentionUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Minimum-availability deadline; the passport is never purged before this instant." }, "proof": { "anyOf": [ { "$ref": "#/components/schemas/MerkleTreeAttestationProof" }, { "type": "null" } ], "description": "Present (non-null) only when the passport is sealed (`digitalSeal` set)." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "economicOperator": { "anyOf": [ { "$ref": "#/components/schemas/EconomicOperatorNode" }, { "type": "null" } ], "description": "The economic operator (manufacturer/importer/retailer) responsible for the product. Public in all tiers." }, "manufacturingFacility": { "anyOf": [ { "$ref": "#/components/schemas/PublicFacilityNode" }, { "type": "null" } ], "description": "GLN-backed Unique Facility Identifier node (EN 18219), or `null` when no facility is linked. GLN, name, activity and country are public; street-address fields appear only in owner-tier responses." }, "metadata": { "type": "object", "additionalProperties": true, "description": "The ESPR category metadata, tier-masked: keys above the caller's tier hold the literal string `[REDACTED - Privileged Access Required]` instead of their value." } } }, "MerkleTreeAttestationProof": { "type": "object", "description": "OpenDPP's own proof type — an eIDAS ADVANCED electronic seal: an ECDSA prime256v1 signature over a SHA-256 Merkle root of the key-sorted metadata (one leaf per top-level metadata key). Deliberately NOT a W3C DataIntegrityProof / `ecdsa-jcs-2019` Verifiable Credential (no RFC 8785 JCS canonicalization). Verifiable offline: rebuild the Merkle root from `metadata` — substituting each `redactedLeaves` hash for its placeholder-masked key, and EXCLUDING any placeholder-masked key that has no `redactedLeaves` entry (such a key was never present in the sealed metadata; the serializer injects the owner-only placeholder unconditionally) — then verify `signatureValue` with `publicKeyPem`; the `x5c` chain validates against the platform seal CA (`GET /.well-known/opendpp-seal-ca.pem`) and the `rfc3161` token via `openssl ts -verify`.", "required": [ "@type", "type", "signatureAlgorithm", "created", "proofPurpose", "verificationMethod", "signatureValue", "publicKeyPem", "merkleRoot" ], "properties": { "@type": { "type": "array", "items": { "type": "string", "const": "MerkleTreeAttestationProof" }, "description": "Always `[\"MerkleTreeAttestationProof\"]`." }, "type": { "type": "string", "const": "MerkleTreeAttestationProof" }, "signatureAlgorithm": { "type": "string", "const": "ECDSA-P256-SHA256-over-MerkleRoot" }, "created": { "type": "string", "format": "date-time", "description": "Mirrors the passport's `updatedAt`." }, "proofPurpose": { "type": "string", "const": "assertionMethod" }, "verificationMethod": { "type": "string", "format": "uri", "description": "`https://opendpp-node.eu/passport/{passportId}#key-1`." }, "signatureValue": { "type": "string", "description": "Base64 ECDSA P-256/SHA-256 signature over the hex Merkle root string (same value as the document's `digitalSeal`)." }, "publicKeyPem": { "type": "string", "description": "PEM public key for verification (same value as the document's `signingPublicKey`)." }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "OPTIONAL (omitted when no chain was recorded at seal time). X.509 chain as base64 DER (no PEM armor), leaf first, binding the signing key to the tenant's legal identity; issued by the platform seal CA. Denormalised at seal time, so later key/cert rotations never retroactively change a proof." }, "rfc3161": { "type": "object", "description": "OPTIONAL (omitted when timestamping was off/unavailable at seal time). RFC 3161 trusted timestamp over SHA-256(merkleRoot) — an independent existed-at anchor from the configured TSA.", "required": [ "genTime", "token" ], "properties": { "genTime": { "type": [ "string", "null" ], "format": "date-time", "description": "TSA generation time." }, "token": { "type": "string", "description": "Base64 DER RFC 3161 TimeStampToken; verifies offline via `openssl ts -verify`." } } }, "merkleRoot": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Hex SHA-256 Merkle root over the key-sorted metadata leaves." }, "redactedLeaves": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "OPTIONAL — present only when at least one masked key actually exists in the underlying sealed metadata. Maps each such metadata key to its TRUE hex leaf hash, so the Merkle root can be reconstructed from the redacted document. A masked key that was never present in the metadata (the owner-only key is placeholder-injected unconditionally for non-owner tiers) yields NO entry here — verifiers must exclude placeholder-valued keys without an entry when rebuilding the tree." } } }, "EconomicOperatorNode": { "type": "object", "description": "Embedded economic-operator JSON-LD node (public in all tiers).", "required": [ "@type", "id", "name", "regId" ], "properties": { "@type": { "type": "string", "const": "EconomicOperator" }, "id": { "type": "string" }, "name": { "type": "string" }, "regId": { "type": "string", "description": "EORI number or official business-registry identifier (unique platform-wide), e.g. `EU-DEFAULT-001`." }, "role": { "type": "string", "description": "Operator role in the supply chain, e.g. `MANUFACTURER`, `IMPORTER`, `RETAILER`. Always present in detail/resolution responses; absent from `GET /api/v1/passports` list items." } } }, "PublicFacilityNode": { "type": "object", "description": "Embedded manufacturing-facility JSON-LD node — the GS1 GLN-backed Unique Facility Identifier (UFI, EN 18219). The five listed fields are public; `streetAddress`/`city`/`postalCode` appear ONLY in owner-tier responses (never via legitimate-interest grants).", "required": [ "@type", "id", "gln", "name", "activity", "country" ], "properties": { "@type": { "type": "string", "const": "Facility" }, "id": { "type": "string" }, "gln": { "type": "string", "pattern": "^[0-9]{13}$", "description": "GS1 GLN-13 with a valid modulo-10 check digit." }, "name": { "type": "string" }, "activity": { "type": [ "string", "null" ], "description": "What the facility does in the chain, e.g. `cell assembly`." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "streetAddress": { "type": [ "string", "null" ], "description": "Owner tier only — omitted from public and grant-tier responses." }, "city": { "type": [ "string", "null" ], "description": "Owner tier only." }, "postalCode": { "type": [ "string", "null" ], "description": "Owner tier only." } } }, "AasEnvironment": { "type": "object", "description": "An Asset Administration Shell (AAS) v3.0 environment export of the passport, served as `application/aas+json`. Three top-level keys: `assetAdministrationShells` (asset identity — `urn:opendpp:aas:{passportId}` / `urn:opendpp:asset:{operatorId}:{productId}`, GS1 GLN-qualified specific asset ids), `submodels`, and `conceptDescriptions` (semantic concept records from the admin-curated registry, `urn:opendpp:concept:…`; empty array when the registry is empty). Submodels: a `GeneralProductInformation` submodel (`urn:opendpp:submodel:general:{passportId}`), a `ComplianceMetadata` submodel (`urn:opendpp:submodel:compliance`) mapping the passport metadata through the concept registry, and — whenever the issuing tenant's eIDAS signing key is provisioned (the normal case) — an `eidasVerificationSeal` submodel (`urn:opendpp:submodel:security-seal:{passportId}`) carrying `digitalSealHash`, `cryptographicSignature`, `pemPublicKey` and an optional `x509CertificateChain`. The seal submodel is present for EVERY access tier. Role filtering strips restricted and commercial owner-only elements from the `ComplianceMetadata` submodel before sending: owner credentials are filtered by their API-key role, grant holders by the `legitimate_interest` tier, anonymous callers by the `public` tier. Submodel internals are intentionally not enumerated in this specification.", "additionalProperties": true }, "PublicBatteryUnitJsonLd": { "type": "object", "description": "Public JSON-LD document for one individual serialised battery unit (Reg. (EU) 2023/1542 Art. 77(2)). The listed required keys are always present. EXACTLY ONE of two tier-dependent groups is added: anonymous (public) responses carry `restrictedData` (Annex XIII(2)-(4) notice) and OMIT `currentState`/`dynamicData` entirely; owner/grant (privileged) responses carry `currentState` (latest measurement or `null`) and `dynamicData` (up to 500 events, newest first) and omit `restrictedData`. The embedded `ofModel` passport is masked by the caller's tier like `GET /passport/{id}`.", "additionalProperties": false, "required": [ "@context", "@type", "@id", "id", "serialNumber", "digitalLinkUri", "status", "manufacturedAt", "repurposedFrom", "successorUnits", "ofModel", "createdAt", "updatedAt" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "description": "The context URL `https://w3id.org/dpp/context/v1` plus a fixed inline term map for the battery-unit terms." }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri", "description": "The unit's GS1 Digital Link URI (AI-21 = the real physical serial)." }, "id": { "type": "string" }, "serialNumber": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$", "description": "The physical battery serial (the real GS1 AI-21 value; unique within its SKU/type passport)." }, "digitalLinkUri": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "IN_SERVICE", "DECOMMISSIONED", "RECALLED", "REPURPOSED", "REMANUFACTURED", "REUSED", "WASTE", "RECYCLED" ], "description": "Annex XIII battery-status vocabulary. A `RECYCLED` (or ceased) unit is never served as a 200 — its URL answers 410 with the tombstone document instead." }, "manufacturedAt": { "type": [ "string", "null" ], "format": "date-time" }, "repurposedFrom": { "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, { "type": "null" } ], "description": "Art. 77(7) lineage: the original unit this repurposed/remanufactured battery came from. The link itself is public." }, "successorUnits": { "type": "array", "items": { "$ref": "#/components/schemas/BatteryUnitLineageRef" }, "description": "Units re-placed on the market under a new passport derived from this one (empty array when none)." }, "ofModel": { "$ref": "#/components/schemas/PublicPassportJsonLd", "description": "The SKU/type-level passport this physical unit is an instance of, masked by the caller's tier." }, "restrictedData": { "$ref": "#/components/schemas/BatteryUnitRestrictedDataNotice", "description": "Present ONLY in anonymous (public-tier) responses." }, "currentState": { "anyOf": [ { "$ref": "#/components/schemas/BatteryUnitCurrentState" }, { "type": "null" } ], "description": "Present ONLY in owner/grant-tier responses: the most recent recorded measurement, or `null` when the unit has no events." }, "dynamicData": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/BatteryUnitEventNode" }, "description": "Present ONLY in owner/grant-tier responses: append-only telemetry history, newest first, capped at the 500 most recent events." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BatteryUnitLineageRef": { "type": "object", "description": "Public lineage pointer between battery units (Art. 77(7)).", "required": [ "unitId", "serialNumber", "digitalLinkUri", "unitUrl" ], "properties": { "unitId": { "type": "string" }, "serialNumber": { "type": "string" }, "digitalLinkUri": { "type": "string", "format": "uri" }, "unitUrl": { "type": "string", "description": "Relative public unit URL: `/unit/{unitId}`." } } }, "BatteryUnitCurrentState": { "type": "object", "description": "Latest recorded measurement of the unit (owner/grant tiers only). All measurement fields are `null` when the latest event did not carry them.", "required": [ "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "recordedAt" ], "properties": { "stateOfHealth": { "type": [ "number", "null" ], "description": "State of health, percent (0-100)." }, "cycleCount": { "type": [ "integer", "null" ], "description": "Cumulative full-equivalent charge cycles." }, "remainingCapacityAh": { "type": [ "number", "null" ], "description": "Measured remaining capacity in ampere-hours." }, "temperatureC": { "type": [ "number", "null" ], "description": "Observed temperature in degrees Celsius." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied)." } } }, "BatteryUnitEventNode": { "type": "object", "description": "One append-only telemetry event (owner/grant tiers only).", "required": [ "@type", "eventType", "stateOfHealth", "cycleCount", "remainingCapacityAh", "temperatureC", "payload", "recordedAt" ], "properties": { "@type": { "type": "string", "const": "BatteryUnitEvent" }, "eventType": { "type": "string", "enum": [ "SOH_MEASUREMENT", "CHARGE_CYCLE", "STATUS_CHANGE", "NEGATIVE_EVENT", "OTHER" ] }, "stateOfHealth": { "type": [ "number", "null" ], "description": "Percent, 0-100." }, "cycleCount": { "type": [ "integer", "null" ] }, "remainingCapacityAh": { "type": [ "number", "null" ] }, "temperatureC": { "type": [ "number", "null" ] }, "payload": { "type": [ "object", "array", "null" ], "additionalProperties": true, "description": "Free-form additional telemetry/context supplied at ingestion. Ingestion accepts any JSON object OR array, so both shapes can appear here." }, "recordedAt": { "type": "string", "format": "date-time", "description": "When the measurement was taken (client-supplied at ingestion)." } } }, "BatteryUnitRestrictedDataNotice": { "type": "object", "description": "Marker replacing per-unit telemetry in anonymous (public-tier) responses, with a pointer for requesting legitimate-interest access (Reg. (EU) 2023/1542, Annex XIII(2)-(4)).", "required": [ "reason", "reference", "description", "howToRequest" ], "properties": { "reason": { "type": "string", "const": "LEGITIMATE_INTEREST_REQUIRED" }, "reference": { "type": "string", "const": "Regulation (EU) 2023/1542, Annex XIII(2)-(4)" }, "description": { "type": "string", "const": "Per-unit dynamic data (state of health, cycle counts, negative events, temperature) is accessible only to persons with a legitimate interest and to authorities." }, "howToRequest": { "type": "string", "description": "Relative URL `/request-access?unit={unitId}` where a legitimate-interest grant can be requested." } } }, "BatteryUnitTombstoneJsonLd": { "type": "object", "description": "Art. 77(8) tombstone (HTTP 410): once a battery is recycled its passport has ceased to exist. This minimal record confirms the unit existed, that it was recycled and when, plus the (still living) model-passport link. Grants and owner credentials do not override the tombstone on the public URL; the underlying data is retained internally for the statutory retention window.", "additionalProperties": false, "required": [ "@context", "@type", "@id", "id", "serialNumber", "status", "ceasedAt", "notice", "ofModelUrl" ], "properties": { "@context": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, "@type": { "type": "string", "const": "BatteryUnit" }, "@id": { "type": "string", "format": "uri" }, "id": { "type": "string" }, "serialNumber": { "type": "string" }, "status": { "type": "string", "const": "RECYCLED" }, "ceasedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the unit's passport ceased to exist (stamped when the status transitioned to RECYCLED)." }, "notice": { "type": "string", "const": "This battery has been recycled. Its battery passport has ceased to exist (Regulation (EU) 2023/1542, Art. 77(8))." }, "ofModelUrl": { "type": [ "string", "null" ], "description": "Relative URL of the still-living SKU/type passport: `/passport/{passportId}`." } } }, "SectorJsonSchemaDocument": { "type": "object", "description": "A JSON Schema **draft-07** document describing the ESPR `metadata` payload for one product category, served as `application/schema+json`. Each known field is annotated server-side with a plain-English `description` from the platform's field-help registry (annotations are AJV-ignored; validation behavior is identical to the raw schema). The same schema (without annotations) validates `metadata` on `POST /api/v1/passports` and the validate-only endpoints.", "additionalProperties": true, "required": [ "$schema", "title", "type", "required", "properties" ], "properties": { "$schema": { "type": "string", "const": "http://json-schema.org/draft-07/schema#" }, "title": { "type": "string" }, "type": { "type": "string", "const": "object" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true } } }, "SectorVocabularyContext": { "type": "object", "description": "Per-category JSON-LD vocabulary context, returned by `GET /api/v1/schemas/{category}` when `Accept` contains `application/ld+json`. Fixed shape: `@vocab` is `https://w3id.org/opendpp/schemas/{category}#` plus mappings for `id`, `type`, `category`, `materialComposition`, `originCountry`, `facilityDetails` and `regulatoryCompliance`.", "additionalProperties": false, "required": [ "@context" ], "properties": { "@context": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DppJsonLdContextDocument": { "type": "object", "description": "The fixed W3C JSON-LD context document served by `GET /context/v1`: maps `DigitalProductPassport`, `economicOperator`, `metadata`, `digitalSeal`, `signingPublicKey` and `proof` to `https://w3id.org/dpp#…` IRIs, and `createdAt`/`updatedAt` to schema.org `dateCreated`/`dateModified`.", "additionalProperties": false, "required": [ "@context" ], "properties": { "@context": { "type": "object", "additionalProperties": { "type": "string" } } } }, "HealthStatus": { "type": "object", "description": "Health-check body of `GET /health`.", "additionalProperties": false, "required": [ "status", "service", "timestamp" ], "properties": { "status": { "type": "string", "const": "OK" }, "service": { "type": "string", "const": "OpenDPP B2B Enterprise Engine" }, "timestamp": { "type": "string", "format": "date-time", "description": "Current server time, ISO 8601 UTC with milliseconds." } } }, "MaterialVocabularyRow": { "type": "object", "description": "One entry of the platform-curated material vocabulary. Entries are unique per (`kind`, `name`).", "required": [ "id", "name", "kind", "casNumber", "description" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Canonical display name, e.g. \"Organic Cotton\" or \"Lithium Iron Phosphate (LFP)\"." }, "kind": { "type": "string", "enum": [ "material", "fiber", "chemistry", "substance", "hazard", "crm" ], "description": "Vocabulary kind. `crm` = critical raw material." }, "casNumber": { "type": [ "string", "null" ], "description": "Optional CAS registry number (chemicals/substances); null when not applicable." }, "description": { "type": [ "string", "null" ], "description": "Optional short note shown in the picker; null when unset." } } }, "MaterialVocabularyListResponse": { "type": "object", "description": "Envelope of `GET /api/v1/materials`. Caveat: unlike most authenticated endpoints there is NO `success` field.", "required": [ "materials" ], "properties": { "materials": { "type": "array", "description": "Active vocabulary entries, ordered by `kind` ascending then `name` ascending, capped at `limit` (max 1000).", "items": { "$ref": "#/components/schemas/MaterialVocabularyRow" } } } }, "UntpEventCredential": { "type": "object", "description": "A UNTP/EPCIS 2.0 traceability event wrapped as a W3C-style Verifiable Credential. The only hard structural requirement is `credentialSubject`; a missing or unverifiable `proof` is rejected with the 400 `Cryptographic Verification Failed` body. Extra properties are permitted — the entire credential (with `proof.proofValue` blanked) is what the signature covers.", "required": [ "credentialSubject", "proof" ], "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "description": "Credential id (e.g. `urn:uuid:...`). NOT used as the stored event id — the event primary key is always server-generated." }, "type": { "type": "array", "items": { "type": "string" } }, "issuer": { "type": "string", "description": "Issuer DID. Unless a trusted x5c chain is embedded, the verification key is resolved by EXACT match of the DID's trailing `:`-segment against registered tenant subdomains/company names — e.g. `did:web:opendpp-node.eu:demo` resolves the workspace with subdomain `demo`. For operator-scoped API keys the issuer DID must ALSO contain the bound operator's registration id somewhere in the string (the issuer is checked in preference to `credentialSubject.responsibleOperatorDid`), e.g. `did:web:opendpp-node.eu:EU-DEFAULT-001:demo`. Stored verbatim as the event's `issuerDid`." }, "issuanceDate": { "type": "string", "format": "date-time", "description": "Fallback for the stored `eventTime` when `credentialSubject.eventTime` is absent." }, "credentialSubject": { "$ref": "#/components/schemas/UntpEventCredentialSubject" }, "proof": { "$ref": "#/components/schemas/UntpEventProof" } } }, "UntpEventCredentialSubject": { "type": "object", "description": "The EPCIS event payload. `eventType` is effectively required: it is persisted into a server-side enum, and a missing or unknown value is rejected at the persistence layer (surfacing as the 500 `Database Persistence Failed` body, not a 400).", "required": [ "eventType" ], "properties": { "id": { "type": "string", "description": "EPC identifier of the subject (e.g. `urn:epc:id:sgtin:0950110153.0003.SN-2026-000123`). When `epcList` is not supplied as an array, the stored EPC list defaults to `[id]` (or `[]` if absent)." }, "eventType": { "type": "string", "enum": [ "ObjectEvent", "AggregationEvent", "TransformationEvent", "AssociationEvent" ], "description": "EPCIS 2.0 event type (server-side enum)." }, "action": { "type": "string", "enum": [ "ADD", "OBSERVE", "DELETE" ], "description": "EPCIS action (server-side enum). Optional — but MUST be absent (or null) on `TransformationEvent`, otherwise 400 `Schema Validation Error`. An unknown value is rejected at the persistence layer (500)." }, "bizStep": { "type": "string", "default": "urn:epcglobal:cbv:bizstep:receiving", "description": "CBV business step URI. Defaults to `urn:epcglobal:cbv:bizstep:receiving`." }, "disposition": { "type": "string", "default": "urn:epcglobal:cbv:disp:in_progress", "description": "CBV disposition URI. Defaults to `urn:epcglobal:cbv:disp:in_progress`." }, "readPoint": { "type": "string", "description": "Where the event was observed (e.g. `geo:41.1496,-8.6109`). When absent and `originLocation` is present, defaults to `geo:,`." }, "bizLocation": { "type": "string", "description": "Business location (SGLN URI, DID, or free identifier). When absent, defaults to `responsibleOperatorDid`." }, "eventTime": { "type": "string", "format": "date-time", "description": "When the event occurred (anything `new Date()` parses). Defaults to the credential `issuanceDate`, else the server clock." }, "epcList": { "type": "array", "items": { "type": "string" }, "description": "EPC URIs observed by the event. A non-array value is replaced with `[credentialSubject.id]` (or `[]`)." }, "parentEpc": { "type": "string", "description": "Parent EPC for AggregationEvent." }, "childEpcs": { "type": "array", "items": { "type": "string" }, "description": "Child EPCs for AggregationEvent (stored as JSON verbatim)." }, "inputEpcList": { "type": "array", "items": { "type": "string" }, "description": "Input EPCs for TransformationEvent (stored as JSON verbatim)." }, "outputEpcList": { "type": "array", "items": { "type": "string" }, "description": "Output EPCs for TransformationEvent (stored as JSON verbatim)." }, "originLocation": { "type": "object", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" }, "eudrPlotId": { "type": "string" } }, "description": "Geographic origin; used only to derive a default `readPoint` (`geo:,`) when `readPoint` is absent. `latitude`/`longitude` are required here for correct usage but NOT enforced server-side: an `originLocation` missing them is not rejected — the derived `readPoint` is then silently persisted as the malformed literal `geo:undefined,undefined`." }, "responsibleOperatorDid": { "type": "string", "description": "DID of the responsible economic operator. Fallback for `bizLocation`, and (only when `issuer` is absent) for the operator-scope check on operator-scoped API keys." } } }, "UntpEventProof": { "type": "object", "description": "Credential proof. Verified with ECDSA P-256 / SHA-256 over OpenDPP's deterministic key-sorted JSON canonicalization of the credential with `proofValue` blanked (NOT RFC 8785 JCS — not a conformant W3C Data Integrity suite).", "required": [ "proofValue" ], "properties": { "type": { "type": "string", "description": "e.g. `DataIntegrityProof`." }, "created": { "type": "string", "format": "date-time" }, "proofPurpose": { "type": "string", "description": "e.g. `assertionMethod`." }, "verificationMethod": { "oneOf": [ { "type": "string", "description": "Public-key identifier / DID URL." }, { "$ref": "#/components/schemas/UntpVerificationMethod" } ], "description": "Either a key-identifier string or an embedded object carrying an `x5c` certificate chain." }, "proofValue": { "type": "string", "description": "Base64 ECDSA signature. Stored verbatim with the event." } } }, "UntpVerificationMethod": { "type": "object", "description": "Embedded verification-method object. The `x5c` chain (base64 DER, leaf first) is honoured ONLY when the node has eIDAS trust anchors configured, every certificate is currently valid, each link verifies against the next, the top is anchored, and the leaf attests the credential issuer — otherwise it is ignored and the registered tenant key is used instead.", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "controller": { "type": "string" }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "X.509 certificate chain, base64 DER, leaf first." } } }, "TraceEventRegistered": { "type": "object", "description": "201 envelope of POST /api/v1/events. Note: `status: \"success\"` (string), not the usual `success: true` boolean.", "required": [ "status", "eventId", "untpVerified" ], "properties": { "status": { "type": "string", "const": "success" }, "eventId": { "type": "string", "description": "Server-generated event id. Use it with `GET /api/v1/events/{id}/lineage` and `POST /api/v1/events/{id}/audit`." }, "untpVerified": { "type": "boolean", "const": true } } }, "TraceLineageNode": { "type": "object", "description": "One node of the recursive upstream lineage DAG. All keys are always present; `location`, `readPoint` and `issuerDid` are null when unset. `location` mirrors the stored `bizLocation`. A shared ancestor reached through multiple downstream paths appears once under each path (the DAG is expanded into a tree).", "required": [ "eventId", "eventType", "bizStep", "disposition", "eventTime", "epcs", "location", "readPoint", "isUntpCompliant", "issuerDid", "parents" ], "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "ObjectEvent", "AggregationEvent", "TransformationEvent", "AssociationEvent" ] }, "bizStep": { "type": "string" }, "disposition": { "type": "string" }, "eventTime": { "type": "string", "format": "date-time" }, "epcs": { "type": "array", "items": { "type": "string" }, "description": "EPC URIs parsed from the stored EPC list (degrades to `[]` when unparseable)." }, "location": { "type": [ "string", "null" ], "description": "The event's stored `bizLocation`." }, "readPoint": { "type": [ "string", "null" ] }, "isUntpCompliant": { "type": "boolean" }, "issuerDid": { "type": [ "string", "null" ] }, "parents": { "type": "array", "items": { "$ref": "#/components/schemas/TraceLineageNode" }, "description": "Upstream parent events (recursive). Empty array at the origin of the chain." } } }, "TraceLineageResponse": { "type": "object", "required": [ "success", "lineage" ], "properties": { "success": { "type": "boolean", "const": true }, "lineage": { "$ref": "#/components/schemas/TraceLineageNode" } } }, "TraceComplianceAuditResponse": { "type": "object", "required": [ "success", "eventId", "compliant", "errors", "auditedAt", "certificate" ], "properties": { "success": { "type": "boolean", "const": true }, "eventId": { "type": "string", "description": "Echo of the audited root event id." }, "compliant": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Human-readable violation strings, e.g. `UFLPA Compliance Failure: Event [] contains raw materials originating from prohibited Xinjiang region ().` or `EUDR Compliance Failure: Farm coordinates [, ] intersect with deforested area plots.` Empty when compliant." }, "auditedAt": { "type": "string", "format": "date-time" }, "certificate": { "oneOf": [ { "$ref": "#/components/schemas/TraceComplianceCertificate" }, { "type": "null" } ], "description": "Present only when `compliant` is true; `null` otherwise." } } }, "TraceComplianceCertificate": { "type": "object", "required": [ "type", "rootEventId", "status", "regulatoryStandards" ], "properties": { "type": { "type": "string", "const": "TraceabilityComplianceCertificate" }, "rootEventId": { "type": "string" }, "status": { "type": "string", "const": "VERIFIED_COMPLIANT" }, "regulatoryStandards": { "type": "array", "items": { "type": "string", "enum": [ "EUDR-2026", "UFLPA-2026" ] }, "description": "Always `[\"EUDR-2026\", \"UFLPA-2026\"]`." } } }, "SealVerifyRequest": { "type": "object", "description": "Verification request. Only `payload` is strictly required: `signature` and `publicKey` are extracted from `payload.proof` (proofValue/signatureValue, publicKeyPem, or the x5c leaf SPKI) when omitted, and the request fails 400 only if either is still missing after extraction.", "required": [ "payload" ], "properties": { "payload": { "type": "object", "description": "The sealed passport document to verify — typically the JSON-LD passport document exactly as resolved from the public endpoints, or any `{passportId, productId, metadata, operator}` payload. Only the fields below are interpreted; all other properties are preserved and participate in the whole-payload signature fallback.", "properties": { "metadata": { "type": "object", "description": "The sealed metadata object — the SHA-256 Merkle tree is rebuilt over its top-level properties (every leaf recomputed from the actual values; caller-supplied redacted-leaf hashes are not accepted). When the `metadata` key is entirely ABSENT, the whole `payload` object is treated as the metadata for the Merkle phase; a present-but-non-object value skips the Merkle phase (only the whole-payload fallback runs)." }, "operator": { "type": "object", "description": "Declared economic operator. A present `regId` triggers the fail-closed operator-binding gate.", "properties": { "name": { "type": "string" }, "regId": { "type": "string", "description": "Operator registration id (e.g. EORI-style `EU-DEFAULT-001`). Must resolve to a registered Economic Operator bound to the signing tenant, or verification fails (`verified: false`)." } } }, "economicOperator": { "type": "object", "description": "Alternative location for the declared operator id — `economicOperator.regId` is checked when `operator.regId` is absent.", "properties": { "regId": { "type": "string" } } }, "proof": { "type": "object", "description": "Embedded W3C-style proof block. Sources for the signature, public key, certificate chain and RFC 3161 token when the top-level fields are omitted.", "properties": { "type": { "type": "string" }, "proofValue": { "type": "string", "description": "Base64 ECDSA seal — used as `signature` when the top-level field is absent." }, "signatureValue": { "type": "string", "description": "Legacy alias for `proofValue` (checked second)." }, "publicKeyPem": { "type": "string", "description": "PEM (SPKI) public key — used as `publicKey` when the top-level field is absent." }, "x5c": { "type": "array", "items": { "type": "string" }, "description": "X.509 certificate chain, base64 DER, LEAF FIRST. Enables the `certificate` report; the leaf's SPKI also serves as the public key when none is otherwise supplied." }, "rfc3161": { "type": "object", "properties": { "token": { "type": "string", "description": "RFC 3161 TimeStampToken (base64 DER CMS ContentInfo) — enables the `timestamp` report." } } } } } }, "additionalProperties": true }, "signature": { "type": "string", "description": "Base64 ECDSA (P-256 / SHA-256) seal signature. Optional when `payload.proof.proofValue` (or `signatureValue`) is present." }, "publicKey": { "type": "string", "description": "PEM (SPKI) public key of the sealing tenant. Optional when `payload.proof.publicKeyPem` or an `x5c` chain is present. CRLF line endings are normalized before matching." } } }, "SealVerifyResponse": { "type": "object", "description": "Always HTTP 200 once the request is well-formed. `verified: false` covers both cryptographic failure and the two registration/binding policy failures — the policy failures add a `message` and OMIT `certificate`/`timestamp` even when an x5c chain or RFC 3161 token was supplied.", "required": [ "success", "verified" ], "properties": { "success": { "type": "boolean", "const": true }, "verified": { "type": "boolean" }, "message": { "type": "string", "description": "Present only on the two policy failures: unregistered public key, or a declared operator not bound to the signing tenant.", "enum": [ "Cryptographic verification failed: The public key used to seal this passport is not registered to any authorized economic operator tenant on this node.", "Cryptographic verification failed: The economic operator declared in this passport is not a registered operator bound to the signing tenant." ] }, "certificate": { "$ref": "#/components/schemas/SealCertificateReport" }, "timestamp": { "$ref": "#/components/schemas/SealTimestampReport" } } }, "SealCertificateReport": { "type": "object", "description": "Present only for x5c-carrying proofs AND only when verification proceeds past the key-registration and operator-binding gates (the two policy `verified: false` responses omit it): the certified legal identity of the seal creator (eIDAS Art. 36(1)(b)). On an unparseable chain only `chainValid: false` and `error` are present.", "required": [ "chainValid" ], "properties": { "subject": { "type": "string", "description": "Leaf-certificate subject (multi-line RDN string as produced by Node's X509Certificate, e.g. `CN=OpenDPP Demo Eco Industries Seal`)." }, "issuer": { "type": "string", "description": "Leaf-certificate issuer RDN string." }, "validFrom": { "type": "string", "description": "X.509 textual date, e.g. `Jan 10 00:00:00 2026 GMT` — NOT ISO 8601." }, "validTo": { "type": "string", "description": "X.509 textual date — NOT ISO 8601." }, "chainValid": { "type": "boolean", "description": "True only when every chain link signature-verifies, every certificate is within its validity window, AND the top of the chain is anchored to this node's seal CA (fingerprint match or signature under the CA key)." }, "keyMatchesProof": { "type": "boolean", "description": "True when the leaf SPKI equals the supplied `publicKey` (whitespace-insensitive), or when no explicit public key was supplied (the leaf key was used)." }, "error": { "type": "string", "const": "Unparseable x5c certificate chain", "description": "Present only when the chain could not be parsed." } } }, "SealTimestampReport": { "type": "object", "description": "Present only when `payload.proof.rfc3161.token` was supplied AND verification proceeds past the key-registration and operator-binding gates (the two policy `verified: false` responses omit it). Reports presence and the TSA-asserted genTime from the token's TSTInfo — full cryptographic TSR validation is the verifier's own step.", "required": [ "present", "genTime" ], "properties": { "present": { "type": "boolean", "const": true }, "genTime": { "type": [ "string", "null" ], "format": "date-time", "description": "TSA-asserted generation time (ISO 8601), or null when the token's TSTInfo could not be parsed." }, "note": { "type": "string", "const": "token present but TSTInfo could not be parsed", "description": "Present only when `genTime` is null." } } }, "WebhookEventFilter": { "type": "string", "enum": [ "passport.ingested", "passport.sealed", "passport.recalled", "*" ], "description": "Subscribable event filter values. `*` matches every emitted event — including `passport.status_updated`, which is emitted by the platform but is NOT in this list and therefore cannot be subscribed to explicitly." }, "WebhookSubscriptionCreateRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Absolute http(s) endpoint URL of your receiver (e.g. a PLM/ERP integration endpoint). DNS-resolved and SSRF-guarded at registration: malformed URLs, loopback, private (RFC 1918/CGNAT), link-local/cloud-metadata, multicast, and equivalent IPv6 ranges are rejected with 400. Redirects are never followed at delivery time." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEventFilter" }, "description": "Non-empty list of event filters. Any value outside the allowed set is rejected with 400." } } }, "WebhookSubscriptionRow": { "type": "object", "description": "A webhook subscription row with the HMAC signing `secret` stripped (it is shown exactly once, in the 201 create response).", "required": [ "id", "tenantId", "url", "events", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Subscription id." }, "tenantId": { "type": "string", "description": "Owning workspace (tenant) id." }, "url": { "type": "string", "format": "uri", "description": "Receiver endpoint URL." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventFilter" }, "description": "Event filters this subscription matches (validated at creation)." }, "isActive": { "type": "boolean", "description": "Always `true` for API-created subscriptions; only active subscriptions receive deliveries. No public endpoint toggles this flag." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WebhookSubscriptionWithSecret": { "description": "The full subscription row as returned ONLY by the 201 create response — includes the HMAC-SHA256 signing secret.", "allOf": [ { "$ref": "#/components/schemas/WebhookSubscriptionRow" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "pattern": "^whsec_[0-9a-f]{32}$", "description": "Server-generated HMAC-SHA256 signing key (`whsec_` + 32 lowercase hex chars). Shown ONCE, here only — the list endpoint strips it and there is no rotation endpoint. The FULL string, including the `whsec_` prefix, is the HMAC key for delivery signatures." } } } ] }, "WebhookSubscriptionCreateResponse": { "type": "object", "required": [ "success", "message", "subscription" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Webhook subscription registered successfully" }, "subscription": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecret" } } }, "WebhookSubscriptionListResponse": { "type": "object", "required": [ "success", "subscriptions" ], "properties": { "success": { "type": "boolean", "const": true }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscriptionRow" } } } }, "WebhookSubscriptionDeleteResponse": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "const": "Webhook subscription successfully deleted" } } } }, "responses": { "Unauthorized": { "description": "Missing, invalid, revoked or expired credentials. Send a valid `Authorization: Bearer op_dpp_token_…` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Unauthorized", "message": "Missing or invalid authentication. Expected Bearer API key, JWT, or active session cookie." } } } }, "PaymentRequired": { "description": "The workspace subscription is lapsed or its grace period has expired — write operations are blocked until billing is restored. Read operations are unaffected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Payment Required", "message": "Your workspace subscription status is 'past_due'. Write access is suspended." } } } }, "Forbidden": { "description": "Authenticated but not allowed: the key lacks the required permission, the request crosses workspaces, or an MFA-gated write was attempted without an MFA session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Forbidden", "message": "Insufficient permissions. Required: \"passport:create\"." } } } }, "NotFound": { "description": "The resource does not exist or is not visible to the calling workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Not Found", "message": "Resource not found." } } } }, "TooManyRequests": { "description": "Global rate limit exceeded (100 requests/min per IP). Inspect the `x-ratelimit-*` headers and retry after the indicated window.", "headers": { "x-ratelimit-limit": { "description": "Request ceiling for the current window.", "schema": { "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "x-ratelimit-reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "retry-after": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Fastify rate-limit plugin default body.", "required": [ "statusCode", "error", "message" ], "properties": { "statusCode": { "type": "integer" }, "code": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } } }, "example": { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 1 minute" } } } }, "PublicRateLimited": { "description": "Public-resolution rate limit exceeded (30 requests/min per IP; no rate-limit headers). With `Accept: text/html` an HTML page is returned instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Too Many Requests", "message": "Rate limit exceeded. Public passport resolutions are limited to 30 requests per minute." } } } }, "InternalError": { "description": "Unexpected server error. Unhandled errors are normalized by the global error handler to this envelope with a generic message; some routes catch their own failures and return the same envelope with a route-specific message. Details are logged server-side and never returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Internal Server Error", "message": "An unexpected error occurred" } } } } }, "parameters": { "PageParam": { "name": "page", "in": "query", "required": false, "description": "1-based page number (digits only).", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "LimitParam": { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } } } }