Dokumentacja · v1

Itemoo DPP Life Cycle API (EN 18222:2026)

Cykl życia i wyszukiwanie paszportu według EN 18222:2026: odczyt (także na dzień i po identyfikatorze produktu), tworzenie i zmiana w modelu EN 18223:2026. Odczyt bez klucza, zapis kluczem marki.

Pobierz OpenAPI (JSON)Historia zmian

Opisy tras i pól są po angielsku — tak samo jak kody i nazwy pól w API.

https://itemoo.eu/dpp-api/v1

Digital Product Passport life cycle and search API per EN 18222:2026 (HTTPS/REST binding of clause 8), with the payload per EN 18223:2026 and errors as Result objects (7.2). The dppApiEndpoint of Itemoo passports in the EU registry is https://itemoo.eu/dpp-api.

Access. Reading needs no key: you get the public level. Authorization: Bearer ipa_… (recipient token issued by the brand) gives the level of that grant; a brand API key itm_… with the passport scope gives all levels of the brand’s own passports and is required for writing. Access levels follow Regulation (EU) 2024/1781 Art. 10(1)(g) and Annex XIII of Regulation (EU) 2023/1542. A back-up grant (ipa_…, issued by the brand to its back-up DPP service provider) reads every passport of the brand at all levels and may also list them (GET /backupDpps) with their versions (GET /dpps/{dppId}/versions) — Itemoo extensions for EN 18221:2026 4.5 replication.

Representation. ?representation=compressed (default) or full; Accept: application/ld+json returns the Itemoo JSON-LD document instead.

Errors. { message: [{ messageType, code, text, correlationId, timestamp, itemooCode?, params? }] } — code is the generic status (Table 15), itemooCode the stable Itemoo code. A retired code answers 404 with itemooCode: codeRetired. Every response carries X-Request-Id (sent by you or generated) — it is the correlationId.

Timestamps. Every timestamp in responses is ISO 8601 in UTC with whole seconds (2026-10-26T12:00:00Z, EN 18222:2026 7.1). A date sent in the address (date) needs a time zone (Z or ±hh:mm) or is a plain date (YYYY-MM-DD, start of the day in UTC).

Limits. 120 calls per minute per IP address, or per key with a brand key. Over the limit the API answers HTTP 429 with a Retry-After header (seconds). This is a deliberate deviation from EN 18222:2026 Table 15, which has no status for rate limiting: the Result body carries the generic ClientErrorBadRequest with itemooCode rateLimited (rateBlocked — a longer block after repeated excess), while the HTTP status stays 429 so that standard HTTP clients back off. DELETE /dpps/{dppId} answers 405 — a passport is never deleted.

Registration. The EU DPP registry serves POST v1/registerDPP (EN 18222:2026 5.2); Itemoo does not register on behalf of the brand — the panel exports the registry entry (unique identifiers, dppApiEndpoint, backup operator).

Life cycle

ReadDPPById — the passport

get/dpp-api/v1/dpps/{dppId}

bez klucza

EN 18222:2026 4.2. The current passport at the access level of the caller. CORS is open; public answers are cached for 5 minutes.

Parametry

Pole	Typ	Opis
`dppId` path · wymagane	string	Passport identifier: the Itemoo code or the passport URI `https://itemoo.eu/q/{code}` (percent-encoded) Przykład: A1B2C3D4
`representation` query	"compressed" \| "full"	compressed (default) — header and data elements keyed by elementId (EN 18223:2026 5.2); full — `elements[]` with objectType (EN 18223:2026 Annex A)
`lang` query	string	Two-letter language of the texts; without it the Accept-Language header decides
`Authorization` header	string	Optional. `Bearer ipa_…` — recipient token issued by the brand (legitimate interest or authority level); `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope: all levels of the brand’s own passports. Without it: the public level.
`Accept` header	string	`application/ld+json` (without `representation`) returns the Itemoo JSON-LD document of the passport instead.
`Accept-Language` header	string	Preferred language of the texts and of error messages.

Odpowiedź 200 · application/json

DigitalProductPassport

digitalProductPassportIdstringwymagane
Globally unique passport URI
uniqueProductIdentifierstringwymagane
GS1 Digital Link of the code level (with batch and serial number) or the code URI (EN 18219:2026)
granularity"model" | "batch" | "item"wymagane
dppSchemaVersionstringwymagane
dppStatus"active" | "inactive" | "archived"wymagane
active (also during a recall — see recall), inactive (end of life of the unit, passport closed by the brand), archived (read-only archive after the brand left Itemoo). The detailed Itemoo status is in lifecycle
lastUpdatedstring (date-time)wymagane
UTC, whole seconds
economicOperatorIdstring | nullwymagane
Manufacturer identifier per EN 18219:2026 (ISO/IEC 6523 ICD:value, e.g. 0088: + GLN); null when the brand has not entered one
facilityIdstring
contentSpecificationIdsstring[]wymagane
Legal acts the passport content follows, e.g. EU 2024/1781, EU 2023/1542

Błędy

400	`DPP_ID_INVALID` — This is not an Itemoo passport identifier (a code or an https://…/q/CODE address). `DPP_REPRESENTATION_INVALID` — representation: compressed or full.
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked. `API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand` `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

DeleteDPPById — not allowed

delete/dpp-api/v1/dpps/{dppId}

bez klucza

EN 18222:2026 4.8. A passport must stay available for the whole product lifetime (Regulation (EU) 2024/1781 Art. 9–10), so it is never deleted: always 405 ClientMethodNotAllowed with Allow: GET, PATCH. End of life is a passport status (dppStatus, lifecycle).

Parametry

Pole	Typ	Opis
`dppId` path · wymagane	string	Passport identifier: the Itemoo code or the passport URI `https://itemoo.eu/q/{code}` (percent-encoded) Przykład: A1B2C3D4

Odpowiedź 200 · application/json

null

Błędy

405	`DPP_DELETE_NOT_ALLOWED` — A passport is not deleted: it must stay available for the whole product lifetime (ESPR Art. 9–10). End of life is a passport status.
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X DELETE 'https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4', {
  method: 'DELETE',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

ReadDPPByProductId — the passport of a product

get/dpp-api/v1/dppsByProductId/{productId}

bez klucza

EN 18222:2026 4.3. The current passport of the product identified by its unique product identifier (EN 18219:2026): a GS1 Digital Link (https://…/01/{gtin}, optionally /10/{lot} and /21/{serial}), a GTIN, a passport URI or a code — percent-encoded. A GS1 address on a brand domain searches that brand only. One GTIN used by several brands answers 409 DPP_PRODUCT_AMBIGUOUS — use POST /dppsByProductIds.

Parametry

Pole	Typ	Opis
`productId` path · wymagane	string	Unique product identifier, percent-encoded Przykład: https%3A%2F%2Fitemoo.eu%2F01%2F05901234123457%2F10%2FL1
`representation` query	"compressed" \| "full"	compressed (default) — header and data elements keyed by elementId (EN 18223:2026 5.2); full — `elements[]` with objectType (EN 18223:2026 Annex A)
`lang` query	string	Two-letter language of the texts; without it the Accept-Language header decides
`Authorization` header	string	Optional. `Bearer ipa_…` — recipient token issued by the brand (legitimate interest or authority level); `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope: all levels of the brand’s own passports. Without it: the public level.
`Accept` header	string	`application/ld+json` (without `representation`) returns the Itemoo JSON-LD document of the passport instead.
`Accept-Language` header	string	Preferred language of the texts and of error messages.

Odpowiedź 200 · application/json

DigitalProductPassport

digitalProductPassportIdstringwymagane
Globally unique passport URI
uniqueProductIdentifierstringwymagane
GS1 Digital Link of the code level (with batch and serial number) or the code URI (EN 18219:2026)
granularity"model" | "batch" | "item"wymagane
dppSchemaVersionstringwymagane
dppStatus"active" | "inactive" | "archived"wymagane
active (also during a recall — see recall), inactive (end of life of the unit, passport closed by the brand), archived (read-only archive after the brand left Itemoo). The detailed Itemoo status is in lifecycle
lastUpdatedstring (date-time)wymagane
UTC, whole seconds
economicOperatorIdstring | nullwymagane
Manufacturer identifier per EN 18219:2026 (ISO/IEC 6523 ICD:value, e.g. 0088: + GLN); null when the brand has not entered one
facilityIdstring
contentSpecificationIdsstring[]wymagane
Legal acts the passport content follows, e.g. EU 2024/1781, EU 2023/1542

Błędy

400	`DPP_PRODUCT_ID_INVALID` — This is not a product identifier: a GS1 Digital Link (…/01/GTIN, optionally /10/LOT and /21/SERIAL), a GTIN, a …/q/CODE address or a code. `DPP_REPRESENTATION_INVALID` — representation: compressed or full.
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked. `API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand` `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data).
409	`DPP_PRODUCT_AMBIGUOUS` — This product identifier matches {n} passports — use POST dppsByProductIds or the GS1 address on the brand domain. params: `n`
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/dppsByProductId/05901234123457'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dppsByProductId/05901234123457', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dppsByProductId/05901234123457');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

ReadDPPVersionByIdAndDate — the passport at a point in time

get/dpp-api/v1/dppsByIdAndDate/{dppId}

bez klucza

EN 18222:2026 4.4. The passport as it was at date, rebuilt from the append-only version history. date is an ISO 8601 timestamp with a time zone (Z or an offset such as +02:00) or a plain date (YYYY-MM-DD = start of that day in UTC); a timestamp without a time zone answers 400 DATE_INVALID. A timestamp without fractional seconds covers that whole second, so the passportVersion.at of a response finds that version again. A date in the future answers 400 DATE_IN_FUTURE (up to 60 seconds ahead counts as now and returns the current passport).

Parametry

Pole	Typ	Opis
`dppId` path · wymagane	string	Passport identifier: the Itemoo code or the passport URI `https://itemoo.eu/q/{code}` (percent-encoded) Przykład: A1B2C3D4
`representation` query	"compressed" \| "full"	compressed (default) — header and data elements keyed by elementId (EN 18223:2026 5.2); full — `elements[]` with objectType (EN 18223:2026 Annex A)
`lang` query	string	Two-letter language of the texts; without it the Accept-Language header decides
`date` query · wymagane	string	Point in time: ISO 8601 with a time zone (`Z` or `±hh:mm`) or a plain date (start of the day, UTC) Przykład: 2026-10-01T00:00:00Z
`Authorization` header	string	Optional. `Bearer ipa_…` — recipient token issued by the brand (legitimate interest or authority level); `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope: all levels of the brand’s own passports. Without it: the public level.
`Accept` header	string	`application/ld+json` (without `representation`) returns the Itemoo JSON-LD document of the passport instead.
`Accept-Language` header	string	Preferred language of the texts and of error messages.

Odpowiedź 200 · application/json

DigitalProductPassport

digitalProductPassportIdstringwymagane
Globally unique passport URI
uniqueProductIdentifierstringwymagane
GS1 Digital Link of the code level (with batch and serial number) or the code URI (EN 18219:2026)
granularity"model" | "batch" | "item"wymagane
dppSchemaVersionstringwymagane
dppStatus"active" | "inactive" | "archived"wymagane
active (also during a recall — see recall), inactive (end of life of the unit, passport closed by the brand), archived (read-only archive after the brand left Itemoo). The detailed Itemoo status is in lifecycle
lastUpdatedstring (date-time)wymagane
UTC, whole seconds
economicOperatorIdstring | nullwymagane
Manufacturer identifier per EN 18219:2026 (ISO/IEC 6523 ICD:value, e.g. 0088: + GLN); null when the brand has not entered one
facilityIdstring
contentSpecificationIdsstring[]wymagane
Legal acts the passport content follows, e.g. EU 2024/1781, EU 2023/1542

Błędy

400	`DPP_ID_INVALID` — This is not an Itemoo passport identifier (a code or an https://…/q/CODE address). `DPP_DATE_REQUIRED` — Send the date in the date parameter (ISO 8601, UTC). `DATE_INVALID` — Invalid date. `DATE_IN_FUTURE` — The date is in the future — the passport only has states up to now. `DPP_REPRESENTATION_INVALID` — representation: compressed or full.
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked. `API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand` `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/dppsByIdAndDate/A1B2C3D4?date=2026-10-01T00%3A00%3A00Z'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dppsByIdAndDate/A1B2C3D4?date=2026-10-01T00%3A00%3A00Z', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dppsByIdAndDate/A1B2C3D4?date=2026-10-01T00%3A00%3A00Z');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

ReadDPPIdsByProductIds — passport identifiers for product identifiers

post/dpp-api/v1/dppsByProductIds

bez klucza

EN 18222:2026 4.5. Passport URIs of every passport matching the product identifiers (same forms as dppsByProductId), page by page: pass pagingMetadata.cursor as cursor with the same productIds until it is missing. Unknown identifiers simply match nothing.

Parametry

Pole	Typ	Opis
`limit` query	string	Page size 1–1000 (default 100) Przykład: 100
`cursor` query	string	The cursor of the previous page (opaque, never empty)

Treść żądania application/json

productIdsstring[]wymagane
Unique product identifiers (1–1000)

Odpowiedź 200 · application/json

object

payloadstring[]wymagane
Passport URIs (digitalProductPassportId)
pagingMetadataobjectwymagane
Pola
- cursorstring

Błędy

400	`DPP_PRODUCT_IDS_EXPECTED` — Send productIds: 1 to 1000 product identifiers. `DPP_LIMIT_INVALID` — limit: an integer from 1 to 1000. `DPP_CURSOR_INVALID` — The cursor is empty or does not come from the previous page of this query.
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X POST 'https://itemoo.eu/dpp-api/v1/dppsByProductIds?limit=100' \
  -H 'Content-Type: application/json' \
  -d '{"productIds":["https://itemoo.eu/01/05901234123457"]}'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dppsByProductIds?limit=100', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "productIds": [
      "https://itemoo.eu/01/05901234123457"
    ]
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dppsByProductIds?limit=100');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"productIds":["https://itemoo.eu/01/05901234123457"]}',
]);
$data = json_decode(curl_exec($ch), true);

CreateDPP — a passport of a batch or an item

post/dpp-api/v1/dpps

bez klucza

EN 18222:2026 4.6. Creates the passport of a new batch (uniqueProductIdentifier with /10/{lot}) or a new item (/21/{serial}) of a product of the brand that has a passport; data elements in the body are saved with it in one transaction. A model passport exists from the moment the product exists — for a model the answer is 409 (exists) or 400 DPP_PASSPORT_BLOCK_REQUIRED. Answers 201 with Location.

Parametry

Pole	Typ	Opis
`Authorization` header	string	Required. `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope, not read-only.
`Accept-Language` header	string	Preferred language of the texts and of error messages.

Treść żądania application/json

digitalProductPassportIdstring
Globally unique passport URI
uniqueProductIdentifierstringwymagane
granularity"model" | "batch" | "item"
dppSchemaVersionstring
dppStatus"active" | "inactive" | "archived"
active (also during a recall — see recall), inactive (end of life of the unit, passport closed by the brand), archived (read-only archive after the brand left Itemoo). The detailed Itemoo status is in lifecycle
lastUpdatedstring (date-time)
UTC, whole seconds
economicOperatorIdstring | null
Manufacturer identifier per EN 18219:2026 (ISO/IEC 6523 ICD:value, e.g. 0088: + GLN); null when the brand has not entered one
facilityIdstring
contentSpecificationIdsstring[]
Legal acts the passport content follows, e.g. EU 2024/1781, EU 2023/1542

Odpowiedź 201 · application/json

Created

object

digitalProductPassportIdstringwymagane

Błędy

400	`DPP_KEY_REQUIRED` — Writing a passport needs a brand API key with the passport scope. `DPP_UNIQUE_ID_REQUIRED` — A new passport needs a uniqueProductIdentifier: the GS1 Digital Link of a brand product with a batch (/10/) or a serial number (/21/). `DPP_GRANULARITY_MISMATCH` — granularity {granularity} does not match the uniqueProductIdentifier. params: `granularity` `DPP_GRANULARITY_UNSUPPORTED` — The product has no unit codes — an item passport cannot be created (set the identification level to unit). `DPP_PASSPORT_BLOCK_REQUIRED` — The product has no passport: add the “Digital product passport” block in the panel (or the product must be under a passport obligation). `DPP_PATCH_INVALID` — The passport patch must be a JSON object (RFC 7396); element {element} has the wrong shape. params: `element` `DPP_HEADER_READONLY` — The passport header attribute {element} cannot be changed. params: `element` `DPP_ELEMENT_READONLY` — Element {element} is computed by Itemoo — it cannot be changed through the API. params: `element` `DPP_ELEMENT_UNKNOWN` — Unknown element {element}: dictionary fields go in their collection (e.g. battery), the brand’s own fields in brandFields. params: `element` `PASSPORT_FIELDS_INVALID` — Passport data: send fields as { key: value } or { key: { value, access } }; text up to 2,000 characters. `PASSPORT_FIELD_KEY_INVALID` — Passport field key: a letter, then letters, digits, _ . - (up to 64 characters). `PASSPORT_FIELD_UNKNOWN` — Field {key} is not in the passport field dictionary — check the name or use your own key outside the dictionary namespaces. params: `key` `PASSPORT_FIELD_NOT_WRITABLE` — Field {key} is filled by the system (code, manufacturer data) or by a unit event — it cannot be entered manually. params: `key` `PASSPORT_FIELD_SCOPE` — Field {key} does not belong to this level — enter model data on the product or variant and batch data on the batch. params: `key` `PASSPORT_VALUE_INVALID` — {key}: the value does not match the field type — check the format in the passport field dictionary. params: `key` `PASSPORT_PERSONAL_DATA` — Field {key} contains personal data ({kind}) — it is not stored in the passport because the passport history cannot be changed. params: `key`, `kind` `PASSPORT_UNIT_RECYCLED` — The battery has been recycled — its passport has ceased to exist and accepts no entries (Regulation 2023/1542, Art. 77(8)). `SERIALS_REQUIRED` — No serial numbers
401	`API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`PRODUCT_NOT_FOUND` — Product not found
409	`DPP_EXISTS` — This passport already exists — change it with PATCH. `BATCH_EXISTS` — Batch {lot} already exists params: `lot` `BATCH_RECALLED_NO_UNITS` — Batch {lot} has been recalled — no new units can be added to it. Give the new production run a different LOT. params: `lot` `CODES_SEQ_CONFLICT` — The unit numbers clash with ones already saved (e.g. from an imported serial list) — nothing was saved. Try again, and if the error comes back, write to us.
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X POST 'https://itemoo.eu/dpp-api/v1/dpps' \
  -H 'Content-Type: application/json' \
  -d '{"uniqueProductIdentifier":"https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001","battery":{"manufacturingDate":"2026-10-01"}}'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dpps', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "uniqueProductIdentifier": "https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001",
    "battery": {
      "manufacturingDate": "2026-10-01"
    }
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dpps');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"uniqueProductIdentifier":"https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001","battery":{"manufacturingDate":"2026-10-01"}}',
]);
$data = json_decode(curl_exec($ch), true);

Back-up

Version history of a passport (Itemoo extension)

get/dpp-api/v1/dpps/{dppId}/versions

bez klucza

Not part of EN 18222:2026 — it makes replication to the back-up DPP service provider possible through this API (EN 18221:2026 4.5). Every version of the passport layers (model, variant, batch, item) with its hash chain, at the access level of the caller: changed fields and values only where the caller sees them, leaf hashes at the authority level. Read a version with GET /dppsByIdAndDate/{dppId}.

Parametry

Pole	Typ	Opis
`dppId` path · wymagane	string	Passport identifier: the Itemoo code or the passport URI `https://itemoo.eu/q/{code}` (percent-encoded) Przykład: A1B2C3D4
`Authorization` header	string	Optional. `Bearer ipa_…` — recipient token issued by the brand (legitimate interest or authority level); `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope: all levels of the brand’s own passports. Without it: the public level.

Odpowiedź 200 · application/json

object

codestringwymagane
levelstringwymagane
versionobject | null
versionsobject[]wymagane
Versions, newest first (up to 500)

Błędy

400	`DPP_ID_INVALID` — This is not an Itemoo passport identifier (a code or an https://…/q/CODE address).
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked. `API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand` `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data).
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/versions'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/versions', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/versions');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

All passports of the brand for its back-up provider (Itemoo extension)

get/dpp-api/v1/backupDpps

bez klucza

Not part of EN 18222:2026. The back-up DPP service provider chosen by the brand (EN 18221:2026 4.3, 4.5) pulls the list of every passport of the brand page by page, then each passport (GET /dpps/{dppId}), its versions and its documents (the document URLs of the passport) with the same token. Requires Authorization: Bearer ipa_… of a back-up grant issued by the brand (all levels, read-only). Itemoo does not push data: the recovery point objective is how often the provider pulls.

Parametry

Pole	Typ	Opis
`limit` query	string	Page size 1–1000 (default 100) Przykład: 100
`cursor` query	string	The cursor of the previous page (opaque, never empty)
`Authorization` header	string	Required. `Bearer ipa_…` — token of the brand’s back-up grant.

Odpowiedź 200 · application/json

object

payloadstring[]wymagane
Passport URIs (digitalProductPassportId)
pagingMetadataobjectwymagane
Pola
- cursorstring

Błędy

400	`DPP_LIMIT_INVALID` — limit: an integer from 1 to 1000. `DPP_CURSOR_INVALID` — The cursor is empty or does not come from the previous page of this query.
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked.
403	`DPP_BACKUP_GRANT_REQUIRED` — This route is only for the brand’s back-up provider — a token of an active “Back-up provider” grant.
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/backupDpps?limit=100'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/backupDpps?limit=100', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/backupDpps?limit=100');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Data elements

ReadDataElement — one data element

get/dpp-api/v1/dpps/{dppId}/elements/{elementIdPath}

bez klucza

EN 18222:2026 6.2. The element at the JSONPath in the compressed passport visible to the caller — a value, or with representation=full a typed data element (SingleValuedDataElement, DataElementCollection, …).

Parametry

Pole	Typ	Opis
`dppId` path · wymagane	string	Passport identifier: the Itemoo code or the passport URI `https://itemoo.eu/q/{code}` (percent-encoded) Przykład: A1B2C3D4
`elementIdPath` path · wymagane	string	JSONPath (RFC 9535) from `$` with name selectors (`.name`, `['name']`); an index (`[0]`) only when reading Przykład: $.battery.chemistry
`representation` query	"compressed" \| "full"	compressed (default) — header and data elements keyed by elementId (EN 18223:2026 5.2); full — `elements[]` with objectType (EN 18223:2026 Annex A)
`lang` query	string	Two-letter language of the texts; without it the Accept-Language header decides
`Authorization` header	string	Optional. `Bearer ipa_…` — recipient token issued by the brand (legitimate interest or authority level); `Bearer itm_…` (or `X-Api-Key`) — brand API key with the `passport` scope: all levels of the brand’s own passports. Without it: the public level.
`Accept-Language` header	string	Preferred language of the texts and of error messages.

Odpowiedź 200 · application/json

any

Błędy

400	`DPP_ID_INVALID` — This is not an Itemoo passport identifier (a code or an https://…/q/CODE address). `DPP_ELEMENT_PATH_UNSUPPORTED` — Element path: JSONPath from $ with names (.name or ['name']); an index only when reading. `DPP_REPRESENTATION_INVALID` — representation: compressed or full.
401	`PASSPORT_GRANT_INVALID` — The passport access is invalid, expired or revoked. `API_KEY_INVALID` — Missing or invalid API key
403	`API_KEY_SCOPE_MISSING` — This key doesn’t have the “{scope}” scope params: `scope` `KEY_READ_ONLY` — This API key is read-only — writing needs a regular key. `BRAND_SUSPENDED` — The brand account is suspended `INTEGRATIONS_DISABLED` — The integrations module is disabled for this brand `PLAN_MODULE_MISSING` — This feature is not part of your company’s plan — it is available on a higher plan (Billing → Plan).
404	`unknownCode` — Unknown code `codeRetired` — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: `brand` `PASSPORT_NONE` — This product has no passport — the manufacturer did not add the “Digital product passport” block. The product data is in the machine data of the code (/data). `DPP_ELEMENT_NOT_FOUND` — The passport has no element {path} (or it is not visible at this access level). params: `path`
429	`rateLimited` — Too many requests. Please try again in a moment. `rateBlocked` — Too many attempts from this address. Please try again in about 15 minutes.

Przykład

cURL

curl -X GET 'https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/elements/%24.productInfo.name'

JavaScript

const res = await fetch('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/elements/%24.productInfo.name', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/dpp-api/v1/dpps/A1B2C3D4/elements/%24.productInfo.name');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Itemoo DPP Life Cycle API (EN 18222:2026)

Wprowadzenie

Life cycle

Parametry

Odpowiedź 200 · application/json

Przykład

Parametry

Odpowiedź 200 · application/json

Przykład

Parametry

Odpowiedź 200 · application/json

Przykład

Parametry

Odpowiedź 200 · application/json

Przykład

Parametry

Treść żądania application/json

Odpowiedź 200 · application/json

Przykład

Parametry

Treść żądania application/json

Odpowiedź 201 · application/json

Przykład

Back-up

Parametry

Odpowiedź 200 · application/json

Przykład

Parametry

Odpowiedź 200 · application/json

Przykład

Data elements

Parametry

Odpowiedź 200 · application/json

Przykład