Chuyển đến nội dung

Tài liệu tham chiếu · v1

Itemoo Public Product Data API

Dữ liệu sản phẩm kèm nguồn gốc, schema.org JSON-LD, hộ chiếu dành cho người nhận và trình phân giải GS1 Digital Link. Không cần khóa.

Mô tả endpoint và trường bằng tiếng Anh — giống như mã và tên trường trong API.

Giới thiệu

https://itemoo.eu

Read-only product data published by producers on Itemoo — no key needed. The same QR code serves a person (HTML page) and a machine (JSON). Every fact points to the document that proves it; machine data is never richer or poorer than the page a person sees.

Languages. ?lang=xx or Accept-Language; texts fall back to the brand default language.

Errors. { statusCode, error, code, params?, message } — rely on code. A code of a product that is no longer maintained returns 410.

Limits. Calls are rate-limited per IP address (429 when exceeded); responses are cacheable — respect Cache-Control.

Product data

Product data with provenance

get/q/{code}/data

không cần khóa

Everything the human page shows, for machines: identity (GTIN, LOT, serial), product, facts with the document behind each, documents, FAQ, recall status and a trust section. Only the published version of the page is exposed. CORS is open (Access-Control-Allow-Origin: *); responses are cached for 5 minutes.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
lang
query
stringTwo-letter language; without it the Accept-Language header decides
Ví dụ: en
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.

Phản hồi 200 · application/json

ProductData

  • identityProductIdentitybắt buộc
    Các trường · ProductIdentity
    • codestringbắt buộc
      Itemoo code from the QR label
    • level"unit" | "batch" | "variant" | "model"bắt buộc
    • gtinstring | nullbắt buộc
    • skustring | nullbắt buộc
    • variantobject
      Các trường
      • labelstringbắt buộc
      • catalogNostring | nullbắt buộc
    • lotstring | nullbắt buộc
    • serialstring | nullbắt buộc
    • expiresAtstring (date-time) | nullbắt buộc
    • statusstringbắt buộc
      Batch status: ACTIVE | RECALLED | …
    • uniqueProductIdentifierstringbắt buộc
      Unique product identifier of this code (EN 18219:2026): GS1 Digital Link with the batch and serial number of the code level, or the code address /q/{code} without a GTIN
  • productProductSummarybắt buộc
    Các trường · ProductSummary
    • namestringbắt buộc
    • brandstringbắt buộc
    • category"chemicals" | "cosmetics" | "medical" | "food" | "supplements" | "electronics" | "appliances" | "batteries" | "textiles" | "furniture" | "toys" | "construction" | "other" | nullbắt buộc
      Regulatory product type — decides the mandatory information: chemicals | cosmetics | medical | food | supplements | electronics | appliances | batteries | textiles | furniture | toys | construction | other
    • descriptionstringbắt buộc
    • imagestring
    • translationsobject
      Name and description in every language the brand provides (ISO 639-1 code → text); name and description above are in the language of the response
      Các trường
      • namemap<string, string>bắt buộc
      • descriptionmap<string, string>bắt buộc
  • manufacturerEconomicOperator | nullbắt buộc
    Manufacturer with postal address and contact; null when the brand has not filled it in
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • responsiblePersonEconomicOperator | nullbắt buộc
    Responsible person in the EU; null when none is given
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • importerEconomicOperator | nullbắt buộc
    Importer (Regulation (EU) 2024/1781 Annex III point (j)); for a batch or unit code the batch importer
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • authorisedRepresentativeEconomicOperator | nullbắt buộc
    Authorised representative of the manufacturer
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • facilityEconomicOperator | nullbắt buộc
    Manufacturing facility (Annex III point (i)); publicly only the town and country unless the brand made the full address public
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • passportFieldsobjectbắt buộc
    Model passport fields with the public access level (empty until the page is published)
  • languagestringbắt buộc
    Language of the texts (requested one when the brand has it)
  • publishedbooleanbắt buộc
    false = the product page is not published yet; facts are empty
  • machineTranslatedbooleanbắt buộc
  • passportbooleanbắt buộc
    The product has a Digital Product Passport: the brand added the “Digital product passport” block or the product is under a passport obligation. Public passport data fields (passportFields) are published for every product
  • passportStatus"NONE" | "ACTIVE" | "CLOSED"bắt buộc
    Passport state: NONE — no passport; ACTIVE; CLOSED — closed by the brand after the product was placed on the market (the passport shows the state as of the closing date)
  • recallRecall | nullbắt buộc
    Các trường · Recall
    • activetruebắt buộc
    • certainbooleanbắt buộc
      true = this exact code is recalled; false = the batch is unknown and may be affected
    • scope"product" | "batch" | "lotRange"bắt buộc
      product = the whole product; batch = one batch; lotRange = a range of batch numbers (lotFrom–lotTo)
    • reasonstringbắt buộc
    • instructionsstring | nullbắt buộc
    • lotFromstring | nullbắt buộc
    • lotTostring | nullbắt buộc
    • kind"recall" | "notice"
      recall = the product is recalled; notice = safety notice, the product is not withdrawn
  • factsProvenanceFact[]bắt buộc
    Các trường · ProvenanceFact
    • keystring
      Stable English key of a standard fact (origin, materials, battery.capacityAh, chemical.ufi, …); absent for parameters defined by the brand — match on it, not on the translated name
    • namestringbắt buộc
      Fact name in the response language
    • valuestringbắt buộc
    • provenanceobject
      Các trường
      • sourcestringbắt buộc
        Document or block the fact comes from
      • versionstring
      • documentUrlstring
      • assertedBystringbắt buộc
        Brand that published the fact
      • assertedAtstring
  • offersobject[]bắt buộc
    Các trường
    • namestringbắt buộc
    • pricenumberbắt buộc
    • currencystringbắt buộc
  • documentsDocument[]bắt buộc
    Các trường · Document
    • titlestringbắt buộc
    • urlstringbắt buộc
    • kindstringbắt buộc
      certificate | declaration | repair | dpp | manual | sds | …
    • versionstring
    • accessstring
      public | legit | authority — present on documents beyond the public level
    • docIdstring
      Library document identifier — the same as in { docId } values of document fields
    • languagestring
      Language of the file (ISO 639-1 code, e.g. de), set by the brand at the document version; absent — multilingual file or not specified
  • faqobject[]bắt buộc
    Các trường
    • questionstringbắt buộc
    • answerstringbắt buộc
  • trustobjectbắt buộc
    Các trường
    • assertedBystringbắt buộc
    • publishedVia"Itemoo"bắt buộc
    • evidencePolicystringbắt buộc
    • factsWithProvenanceintegerbắt buộc
    • factsTotalintegerbắt buộc
    • lastUpdatedstring (date-time)bắt buộc
Lỗi
404
  • unknownCode — Unknown code
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/data'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/data', {
  method: 'GET',
});
const data = await res.json();

PHP

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

schema.org Product (JSON-LD)

get/q/{code}/schema.json

không cần khóa

The same product as schema.org Product in JSON-LD — for search engines and standard agents. Facts become additionalProperty with valueReference to the source document; the recall status is the first property (recallStatus).

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
lang
query
stringTwo-letter language; without it the Accept-Language header decides
Ví dụ: en
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.

Phản hồi 200 · application/ld+json

object

  • @context"https://schema.org"bắt buộc
  • @type"Product"bắt buộc
  • namestringbắt buộc
Lỗi
404
  • unknownCode — Unknown code
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/schema.json'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/schema.json', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/schema.json');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Parameter profile file

get/q/{code}/profile

không cần khóa

One parameter profile of the product (e.g. print settings for a resin) as a file: format=json gives { product, profile, params: [{ name, value }] }, ini (default) and cfg give key = value text for slicers.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
i
query
stringProfile index, 0 by default
format
query
"json" | "ini" | "cfg"
lang
query
string

Phản hồi 200 · application/json, text/plain

Profile file (attachment)

Lỗi
404
  • unknownCode — Unknown code
  • profileNotFound — Profile not found
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/profile?format=json'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/profile?format=json', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/profile?format=json');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Capabilities for AI agents

get/.well-known/agent-interface.json

không cần khóa

Entry point for an agent that landed on the domain: the endpoints above and the evidence policy.

Phản hồi 200 · application/json

object

  • namestringbắt buộc
  • descriptionstringbắt buộc
  • versionstringbắt buộc
  • endpointsobject[]bắt buộc
    Các trường
    • pathstringbắt buộc
    • methodstringbắt buộc
    • returnsstringbắt buộc
    • descriptionstringbắt buộc
  • evidencePolicystringbắt buộc
Lỗi
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/.well-known/agent-interface.json'

JavaScript

const res = await fetch('https://itemoo.eu/.well-known/agent-interface.json', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/.well-known/agent-interface.json');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Passport

Digital Product Passport (JSON-LD)

get/q/{code}/dpp.jsonld

không cần khóa

The passport in JSON-LD with the Itemoo context (https://itemoo.eu/ns/dpp/1.1/context.jsonld; version 1.0 stays published): fields map to the CIRPASS-2 ontology (https://w3id.org/eudpp#, battery modules) where the meaning matches, the rest to the Itemoo vocabulary. The product node is the unit, batch or model of the code; the passport node carries the version hash, backup copy, predecessor and successors, components and lifecycle status. The same document is returned by /q/{code} and the GS1 Digital Link addresses for Accept: application/ld+json (with Content-Location). With a recipient token or session it shows that level (then never cached). The CIRPASS-2 ontology is a project recommendation, not an EU data model; conformity with the EU semantic repository (Implementing Regulation (EU) 2026/1778) is not claimed. Only products with a passport have it — the brand added the “Digital product passport” block or the product is under a passport obligation (e.g. EV, LMT and industrial batteries above 2 kWh); other products answer 404 PASSPORT_NONE and publish their data in /q/{code}/data. A closed passport has lifecycle.status = closed and shows the state as of the closing date.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
lang
query
stringTwo-letter language; without it the Accept-Language header decides
Ví dụ: en
Authorization
header
stringBearer ipa_… — optional recipient token
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.

Phản hồi 200 · application/ld+json

object

  • @contextstringbắt buộc
  • idstringbắt buộc
  • type"Product"bắt buộc
  • passportobjectbắt buộc
    Các trường
    • type"DigitalProductPassport"bắt buộc
Lỗi
401
  • PASSPORT_GRANT_INVALID — The passport access is invalid, expired or revoked.
404
  • unknownCode — Unknown code
  • 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).
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/dpp.jsonld'

JavaScript

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

PHP

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

JSON-LD context of Itemoo passports

get/ns/dpp/{version}/context.jsonld

không cần khóa

Immutable, versioned context (@protected). A change of content means a new version; documents name the version they use.

Tham số

TrườngKiểuMô tả
version
path · bắt buộc
stringContext version
Ví dụ: 1.0

Phản hồi 200 · application/ld+json

object

  • @contextobjectbắt buộc
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/ns/dpp/1.0/context.jsonld'

JavaScript

const res = await fetch('https://itemoo.eu/ns/dpp/1.0/context.jsonld', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/ns/dpp/1.0/context.jsonld');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Itemoo passport vocabulary

get/ns/dpp/{version}/vocab

không cần khóa

RDFS terms (itm:) used by the context for fields without a CIRPASS-2 equivalent, with labels in Polish and English; mapped fields are listed as equivalent properties.

Tham số

TrườngKiểuMô tả
version
path · bắt buộc
stringVocabulary version
Ví dụ: 1.0

Phản hồi 200 · application/ld+json

object

  • @idstringbắt buộc
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/ns/dpp/1.0/vocab'

JavaScript

const res = await fetch('https://itemoo.eu/ns/dpp/1.0/vocab', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/ns/dpp/1.0/vocab');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Data model catalogue (DCAT-AP)

get/.well-known/dpp

không cần khóa

DCAT-AP description of the Itemoo passport data models (context, vocabulary, ontologies they build on) and of the resolver service. No index of products or brands.

Phản hồi 200 · application/ld+json

object

  • @idstringbắt buộc
  • @type"dcat:Catalog"bắt buộc
Lỗi
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/.well-known/dpp'

JavaScript

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

PHP

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

Digital Product Passport

get/q/{code}/passport

không cần khóa

Public passport data; with a recipient token issued by the producer (legitimate interest or authority) also the fields, documents and unit history of that level. Send the token as Authorization: Bearer ipa_…. Never cached. A browser (Accept: text/html without a token) gets a readable passport page at the same address; format=json returns JSON anyway. Only products with a passport have it — the brand added the “Digital product passport” block or the product is under a passport obligation (e.g. EV, LMT and industrial batteries above 2 kWh); other products answer 404 PASSPORT_NONE and publish their data in /q/{code}/data. A closed passport has lifecycle.status = closed and shows the state as of the closing date.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
lang
query
stringTwo-letter language; without it the Accept-Language header decides
Ví dụ: en
at
query
stringThe passport as it was at that moment, from the version history (a stable address of a version): ISO 8601 with a time zone (Z or ±hh:mm) or a plain date (start of the day, UTC). Without a time zone — 400 DATE_INVALID; in the future (over 60 s) — 400 DATE_IN_FUTURE
Ví dụ: 2027-03-01T10:00:00Z
format
query
"json" | "html"json — JSON even for a browser; html — the passport page. Without it the Accept header decides.
Authorization
header
stringBearer ipa_… — optional recipient token
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.

Phản hồi 200 · application/json

Passport

  • level"public" | "legit" | "authority"bắt buộc
  • recipientstring
    Name of the access grant used
  • versionPassportVersion | nullbắt buộc
    Các trường · PassportVersion
    • hashstringbắt buộc
      SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
    • layersobject[]bắt buộc
      Các trường
      • subject"product" | "variant" | "batch" | "unit"bắt buộc
      • versionintegerbắt buộc
      • hashstringbắt buộc
    • eventsHeadstring | nullbắt buộc
    • atstring (date-time)
      Present for a passport read at a point in time (?at=)
  • backupobject | nullbắt buộc
    Backup copy of the passport kept by a DPP service provider (Regulation (EU) 2024/1781 Annex III point (l)), when the brand designated one
    Các trường
    • providerstringbắt buộc
    • urlstringbắt buộc
  • identityProductIdentitybắt buộc
    Các trường · ProductIdentity
    • codestringbắt buộc
      Itemoo code from the QR label
    • level"unit" | "batch" | "variant" | "model"bắt buộc
    • gtinstring | nullbắt buộc
    • skustring | nullbắt buộc
    • variantobject
      Các trường
      • labelstringbắt buộc
      • catalogNostring | nullbắt buộc
    • lotstring | nullbắt buộc
    • serialstring | nullbắt buộc
    • expiresAtstring (date-time) | nullbắt buộc
    • statusstringbắt buộc
      Batch status: ACTIVE | RECALLED | …
    • uniqueProductIdentifierstringbắt buộc
      Unique product identifier of this code (EN 18219:2026): GS1 Digital Link with the batch and serial number of the code level, or the code address /q/{code} without a GTIN
  • productProductSummarybắt buộc
    Các trường · ProductSummary
    • namestringbắt buộc
    • brandstringbắt buộc
    • category"chemicals" | "cosmetics" | "medical" | "food" | "supplements" | "electronics" | "appliances" | "batteries" | "textiles" | "furniture" | "toys" | "construction" | "other" | nullbắt buộc
      Regulatory product type — decides the mandatory information: chemicals | cosmetics | medical | food | supplements | electronics | appliances | batteries | textiles | furniture | toys | construction | other
    • descriptionstringbắt buộc
    • imagestring
    • translationsobject
      Name and description in every language the brand provides (ISO 639-1 code → text); name and description above are in the language of the response
      Các trường
      • namemap<string, string>bắt buộc
      • descriptionmap<string, string>bắt buộc
  • manufacturerEconomicOperator | nullbắt buộc
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • responsiblePersonEconomicOperator | nullbắt buộc
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • importerEconomicOperator | nullbắt buộc
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • authorisedRepresentativeEconomicOperator | nullbắt buộc
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • facilityEconomicOperator | nullbắt buộc
    Các trường · EconomicOperator
    • namestringbắt buộc
    • addressobjectbắt buộc
      Các trường
      • streetstring | nullbắt buộc
      • postalCodestring | nullbắt buộc
      • citystring | nullbắt buộc
      • countrystring | nullbắt buộc
        ISO 3166-1 alpha-2
    • emailstring | nullbắt buộc
    • phonestring | nullbắt buộc
      Shown only at the access level the brand chose for it (default: persons with a legitimate interest)
    • source"company" | "registry"bắt buộc
      company = the brand company data; registry = an operator from the company operator register designated in the passport
    • tradeNamestring | null
      Registered trade name or trade mark (Regulation (EU) 2024/1781 Art. 27(6), 29(3))
    • identifiersobject[]
      Unique operator or facility identifiers (Regulation (EU) 2024/1781 Annex III points (g)–(k), Art. 12; EN 18219:2026 Clause 6 — ISO/IEC 6523 or ISO/IEC 15459)
      Các trường
      • scheme"gln" | "duns" | "lei" | "vat" | "iso15459"bắt buộc
        gln = GS1 GLN, duns = D-U-N-S, lei = Legal Entity Identifier (ISO 17442), vat = EU VAT number with country prefix, iso15459 = identifier of another ISO/IEC 15459 issuing agency
      • iacstring
        Issuing agency code (ISO/IEC 15459-2 register): 0–9 for GS1, UN for D&B, otherwise the registered agency code; absent for lei and vat
      • valuestringbắt buộc
    • eoristring | null
      EORI number (importer, Annex III point (j)) — shown only at the access level the brand chose for it (default: legitimate interest)
  • languagestringbắt buộc
  • publishedbooleanbắt buộc
  • recallRecall | nullbắt buộc
    Các trường · Recall
    • activetruebắt buộc
    • certainbooleanbắt buộc
      true = this exact code is recalled; false = the batch is unknown and may be affected
    • scope"product" | "batch" | "lotRange"bắt buộc
      product = the whole product; batch = one batch; lotRange = a range of batch numbers (lotFrom–lotTo)
    • reasonstringbắt buộc
    • instructionsstring | nullbắt buộc
    • lotFromstring | nullbắt buộc
    • lotTostring | nullbắt buộc
    • kind"recall" | "notice"
      recall = the product is recalled; notice = safety notice, the product is not withdrawn
  • factsProvenanceFact[]bắt buộc
    Các trường · ProvenanceFact
    • keystring
      Stable English key of a standard fact (origin, materials, battery.capacityAh, chemical.ufi, …); absent for parameters defined by the brand — match on it, not on the translated name
    • namestringbắt buộc
      Fact name in the response language
    • valuestringbắt buộc
    • provenanceobject
      Các trường
      • sourcestringbắt buộc
        Document or block the fact comes from
      • versionstring
      • documentUrlstring
      • assertedBystringbắt buộc
        Brand that published the fact
      • assertedAtstring
  • documentsDocument[]bắt buộc
    Các trường · Document
    • titlestringbắt buộc
    • urlstringbắt buộc
    • kindstringbắt buộc
      certificate | declaration | repair | dpp | manual | sds | …
    • versionstring
    • accessstring
      public | legit | authority — present on documents beyond the public level
    • docIdstring
      Library document identifier — the same as in { docId } values of document fields
    • languagestring
      Language of the file (ISO 639-1 code, e.g. de), set by the brand at the document version; absent — multilingual file or not specified
  • componentsPassportComponent[]bắt buộc
    Components with their own passport visible at this level (Regulation (EU) 2024/1781 Art. 2(4); CIRPASS-2 D4.1 recommendation 5)
    Các trường · PassportComponent
    • codestring | nullbắt buộc
      Itemoo code of the component passport (unit, batch, variant or model — also of another brand)
    • uristring | nullbắt buộc
      Address of a component passport outside Itemoo (DPP URL or GS1 Digital Link)
    • urlstringbắt buộc
      Where to read the component passport
    • rolestring | nullbắt buộc
    • nameanybắt buộc
    • quantitynumber | nullbắt buộc
    • unitstring | nullbắt buộc
    • level"model" | "unit"bắt buộc
      model — bill of components of the model; unit — installed in this unit (assembly events)
    • sincestring | nullbắt buộc
      When the component was installed in this unit
  • lifecycleobjectbắt buộc
    Lifecycle status of the passport: recalled — an active recall covers the code (a safety notice does not); end_of_life — the unit was recycled or became waste; archived — the brand left Itemoo and the passport is kept read-only; closed — the brand closed the passport after the product was placed on the market (the passport shows the state as of the closing date, since). A passport is never deleted: removal is a status (CIRPASS-2 D4.1 recommendation 3); a retired code answers 410
    Các trường
    • status"active" | "recalled" | "end_of_life" | "archived" | "closed"bắt buộc
    • sincestring (date-time) | nullbắt buộc
  • modelobjectbắt buộc
    Model passport fields visible at this level
  • unitobject | nullbắt buộc
    Các trường
    • serialstring | nullbắt buộc
    • dataobjectbắt buộc
    • stateobjectbắt buộc
      Các trường
      • statusstring | nullbắt buộc
        original | repurposed | re-used | remanufactured | waste | recycled (Regulation (EU) 2023/1542 Annex XIII point 4(c); recycled ends the passport). null — not visible at this access level (a battery status is for persons with a legitimate interest only)
      • sohnumber | nullbắt buộc
        State of health, 0–100 (SoH, or SOCE / remaining capacity when only that is recorded)
      • sohAtstring (date-time) | nullbắt buộc
      • cyclesnumber | nullbắt buộc
      • incidentsintegerbắt buộc
    • historyobject[]bắt buộc
      Các trường
      • kindstringbắt buộc
      • dataanybắt buộc
      • occurredAtstring (date-time)bắt buộc
      • sourcestring
    • linksobjectbắt buộc
      Các trường
      • predecessorobject | nullbắt buộc
        Passport before remanufacturing or repurposing (Art. 77(7))
        Các trường
        • codestringbắt buộc
        • urlstringbắt buộc
      • successorsobject[]bắt buộc
        New passports created from this battery
        Các trường
        • codestringbắt buộc
        • urlstringbắt buộc
    • custodianobject | nullbắt buộc
      Operator responsible for the passport of a waste battery after a transfer (producer, PRO or waste management operator — Art. 77(7))
      Các trường
      • namestringbắt buộc
      • rolestringbắt buộc
      • sincestring (date-time)bắt buộc
Lỗi
400
  • DATE_INVALID — Invalid date.
  • DATE_IN_FUTURE — The date is in the future — the passport only has states up to now.
401
  • PASSPORT_GRANT_INVALID — The passport access is invalid, expired or revoked.
404
  • unknownCode — Unknown code
  • 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).
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/passport'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Products this component is part of

get/q/{code}/passport/part-of

không cần khóa

Reverse component links: models whose bill of components lists this code and units where it is currently installed. A link is returned only when the reader has its access level AT THE BRAND OF THE PARENT product (a recipient token of that brand, or a market surveillance authority) — the component maker does not learn who uses its parts. Non-public reads are logged in the read log of the parent brand. Only products with a passport have it — the brand added the “Digital product passport” block or the product is under a passport obligation (e.g. EV, LMT and industrial batteries above 2 kWh); other products answer 404 PASSPORT_NONE and publish their data in /q/{code}/data. A closed passport has lifecycle.status = closed and shows the state as of the closing date.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
Authorization
header
stringBearer ipa_… — optional recipient token

Phản hồi 200 · application/json

PartOf

  • codestringbắt buộc
  • partOfobject[]bắt buộc
    Các trường
    • codestringbắt buộc
    • urlstringbắt buộc
    • rolestring | nullbắt buộc
    • level"model" | "unit"bắt buộc
    • sincestring | nullbắt buộc
Lỗi
401
  • PASSPORT_GRANT_INVALID — The passport access is invalid, expired or revoked.
404
  • unknownCode — Unknown code
  • 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).
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/passport/part-of'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport/part-of', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport/part-of');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Brand passport feed (JSON Feed)

get/b/{slug}/passport/feed.json

không cần khóa

Public feed of a brand for dealers, recyclers, marketplaces and authorities, without registering an address: recalls, safety notices and new versions of product and batch passports (names of the changed public fields; values are at the code address). No unit data. JSON Feed 1.1, ETag and 5-minute caching. The same entries as Atom: /b/{slug}/passport/feed.atom.

Tham số

TrườngKiểuMô tả
slug
path · bắt buộc
stringBrand identifier from the brand app address
Ví dụ: acme

Phản hồi 200 · application/feed+json

object

  • version"https://jsonfeed.org/version/1.1"bắt buộc
  • itemsobject[]bắt buộc
    Các trường
    • idstringbắt buộc
    • urlstringbắt buộc
Lỗi
404
  • BRAND_NOT_FOUND — Brand not found
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/b/acme/passport/feed.json'

JavaScript

const res = await fetch('https://itemoo.eu/b/acme/passport/feed.json', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/b/acme/passport/feed.json');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Brand passport feed (Atom)

get/b/{slug}/passport/feed.atom

không cần khóa

The brand passport feed as Atom 1.0 (see the JSON Feed variant).

Tham số

TrườngKiểuMô tả
slug
path · bắt buộc
stringBrand identifier
Ví dụ: acme

Phản hồi 200 · application/atom+xml

string

Lỗi
404
  • BRAND_NOT_FOUND — Brand not found
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/b/acme/passport/feed.atom'

JavaScript

const res = await fetch('https://itemoo.eu/b/acme/passport/feed.atom', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/b/acme/passport/feed.atom');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Passport version history

get/q/{code}/passport/history

không cần khóa

Every change of passport fields (model, variant, batch, unit) is an append-only version chained by SHA-256 hashes. The response lists versions with the changes of fields visible at the reader's level (public without a token) and, for the authority level, the leaf hashes needed to recompute each version hash. Redacted values (personal data removed by the platform) keep their hash and show redacted: true. Only products with a passport have it — the brand added the “Digital product passport” block or the product is under a passport obligation (e.g. EV, LMT and industrial batteries above 2 kWh); other products answer 404 PASSPORT_NONE and publish their data in /q/{code}/data. A closed passport has lifecycle.status = closed and shows the state as of the closing date.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
Authorization
header
stringBearer ipa_… — optional recipient token

Phản hồi 200 · application/json

PassportHistory

  • codestringbắt buộc
  • level"public" | "legit" | "authority"bắt buộc
  • versionPassportVersion | nullbắt buộc
    Các trường · PassportVersion
    • hashstringbắt buộc
      SHA-256 of the canonical (RFC 8785) composition of layer versions and the unit event chain head
    • layersobject[]bắt buộc
      Các trường
      • subject"product" | "variant" | "batch" | "unit"bắt buộc
      • versionintegerbắt buộc
      • hashstringbắt buộc
    • eventsHeadstring | nullbắt buộc
    • atstring (date-time)
      Present for a passport read at a point in time (?at=)
  • versionsobject[]bắt buộc
    Các trường
    • subject"product" | "variant" | "batch" | "unit"bắt buộc
    • versionintegerbắt buộc
    • hashstringbắt buộc
    • prevHashstring | nullbắt buộc
    • atstring (date-time)bắt buộc
    • sourcestringbắt buộc
    • changesobject[]bắt buộc
      Các trường
      • keystringbắt buộc
      • op"add" | "change" | "remove"bắt buộc
      • valueany
      • redactedboolean
    • leavesmap<string, object>
      Leaf hashes (authority level only) to recompute the version hash
      Các trường
      • hstringbắt buộc
      • access"public" | "legit" | "authority"bắt buộc
Lỗi
401
  • PASSPORT_GRANT_INVALID — The passport access is invalid, expired or revoked.
404
  • unknownCode — Unknown code
  • 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).
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/passport/history'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport/history', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport/history');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Proof of existence of the current passport versions

get/q/{code}/passport/anchor

không cần khóa

Every day (UTC) Itemoo builds a Merkle tree (RFC 6962 hashing: leaf = SHA-256(0x00 ‖ hash), node = SHA-256(0x01 ‖ left ‖ right), sorted unique leaves) of all passport version hashes and unit event hashes recorded that day and, when enabled, obtains an RFC 3161 timestamp for SHA-256(root). For each current layer version (and the head of the unit event chain) the response gives the day, the root and the inclusion path; anchor: null until the day is anchored. Verify the token with openssl ts -verify -digest <timestamp.digest> -in <token>. Only products with a passport have it — the brand added the “Digital product passport” block or the product is under a passport obligation (e.g. EV, LMT and industrial batteries above 2 kWh); other products answer 404 PASSPORT_NONE and publish their data in /q/{code}/data. A closed passport has lifecycle.status = closed and shows the state as of the closing date.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4

Phản hồi 200 · application/json

PassportAnchorProofs

  • codestringbắt buộc
  • algorithmstring | nullbắt buộc
  • proofsobject[]bắt buộc
    Các trường
    • subject"product" | "variant" | "batch" | "unit" | "events"bắt buộc
    • versioninteger
    • hashstringbắt buộc
    • anchorobject | nullbắt buộc
      Các trường
      • daystringbắt buộc
      • rootstringbắt buộc
      • algorithmstringbắt buộc
      • leavesintegerbắt buộc
      • pathobject[]bắt buộc
        Các trường
        • side"left" | "right"bắt buộc
        • hashstringbắt buộc
      • timestampobject | nullbắt buộc
        Các trường
        • providerstringbắt buộc
        • atstringbắt buộc
        • digeststringbắt buộc
        • tokenstringbắt buộc
          Base64 RFC 3161 TimeStampResp
Lỗi
404
  • unknownCode — Unknown code
  • 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).
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/passport/anchor'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport/anchor', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport/anchor');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Request access to an archived passport

post/q/{code}/passport/access-request

không cần khóa

After the contract of the brand ends, regulated passports (batteries with the full passport) stay available in the Itemoo Passport Archive, but the brand no longer issues recipient tokens. Authorities and persons with a legitimate interest (Regulation (EU) 2023/1542 Annex XIII) request access here; a platform operator reviews the request and another one approves it (four eyes) and sends the token. Outside the archive the route answers 404 — ask the brand.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4

Nội dung yêu cầu application/json

  • level"legit" | "authority"bắt buộc
  • organizationstringbắt buộc
    Authority, service, recycler…
  • emailstringbắt buộc
    Contact e-mail for the token (deleted 180 days after the decision)
  • justificationstringbắt buộc
    Why the access is needed and on what basis

Phản hồi 200 · application/json

PassportAccessRequestCreated

  • idstringbắt buộc
  • status"new"bắt buộc
Lỗi
400
  • PASSPORT_GRANT_LEVEL — Access: legit (legitimate interest) or authority.
  • PASSPORT_REQUEST_ORGANIZATION — Enter the organisation name (authority, service, recycler).
  • PASSPORT_REQUEST_JUSTIFICATION — Justification: 20–2000 characters (why the access and on what basis).
  • EMAIL_INVALID — E-mail: invalid address
404
  • unknownCode — Unknown code
409
  • PASSPORT_REQUEST_PENDING — A request with this e-mail address for this product is already awaiting a decision.
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.

Ví dụ

cURL

curl -X POST 'https://itemoo.eu/q/A1B2C3D4/passport/access-request' \
  -H 'Content-Type: application/json' \
  -d '{"level":"legit","organization":"Recycling Sp. z o.o.","email":"office@example.com","justification":"Dismantling and recycling of the battery received as waste."}'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport/access-request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "level": "legit",
    "organization": "Recycling Sp. z o.o.",
    "email": "office@example.com",
    "justification": "Dismantling and recycling of the battery received as waste."
  }),
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport/access-request');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => '{"level":"legit","organization":"Recycling Sp. z o.o.","email":"office@example.com","justification":"Dismantling and recycling of the battery received as waste."}',
]);
$data = json_decode(curl_exec($ch), true);

Restricted passport document file

get/q/{code}/passport/documents/{versionId}

không cần khóa

The file of a document outside the public level (e.g. dismantling information, test reports — Annex XIII points 2–3 of Regulation (EU) 2023/1542). Its address comes from documents[].url of GET /q/{code}/passport read with a token; the public file address of such a document returns 404. Requires Authorization: Bearer ipa_… with a level that sees the document; every download is recorded in the producer's access log. Never cached.

Tham số

TrườngKiểuMô tả
code
path · bắt buộc
stringItemoo code from the QR label (unit, batch, variant or product)
Ví dụ: A1B2C3D4
versionId
path · bắt buộc
stringDocument version id from the passport
Ví dụ: clx0doc0version0001
Authorization
header
stringBearer ipa_… — recipient token (required)

Phản hồi 200 · application/pdf, application/octet-stream

Document file

Lỗi
401
  • PASSPORT_GRANT_INVALID — The passport access is invalid, expired or revoked.
404
  • DOCUMENT_NOT_FOUND — Document not found
  • unknownCode — Unknown code
410
  • codeRetired — The {brand} product page is no longer maintained — please contact the manufacturer directly. params: brand
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/q/A1B2C3D4/passport/documents/clx0doc0version0001'

JavaScript

const res = await fetch('https://itemoo.eu/q/A1B2C3D4/passport/documents/clx0doc0version0001', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/q/A1B2C3D4/passport/documents/clx0doc0version0001');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Resolve a GTIN

get/01/{gtin}

không cần khóa

GS1 Digital Link resolver. With linkType=linkset or Accept: application/linkset+json it returns the linkset (RFC 9264) built from the published page: product page, instructions, certificates, passport and recall status. With linkType=gs1:<type> it redirects (307) to the first link of that type. Without either it shows the product page (HTML). One GTIN used by several brands returns a choice of their pages.

Tham số

TrườngKiểuMô tả
gtin
path · bắt buộc
stringGTIN (8–14 digits)
Ví dụ: 05901234123457
linkType
query
string"linkset" = the whole linkset (also with Accept: application/linkset+json); "gs1:pip" etc. = 307 redirect to the first link of that type
lang
query
string
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.
Accept
header
stringapplication/linkset+json returns the linkset without linkType.

Phản hồi 200 · application/linkset+json

Linkset

  • linksetmap<string, string | object[]>[]bắt buộc
    One entry: "anchor" (the GS1 URI) and one key per link type (https://gs1.org/voc/pip, …/instructions, …/certificationInfo, …/sustainabilityInfo, …/recallStatus)
    Các trường
    • hrefstringbắt buộc
    • titlestring
    • typestring
    • hreflangstring[]
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/01/05901234123457?linkType=linkset'

JavaScript

const res = await fetch('https://itemoo.eu/01/05901234123457?linkType=linkset', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/01/05901234123457?linkType=linkset');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Resolve a GTIN with a batch

get/01/{gtin}/10/{lot}

không cần khóa

GS1 Digital Link resolver. With linkType=linkset or Accept: application/linkset+json it returns the linkset (RFC 9264) built from the published page: product page, instructions, certificates, passport and recall status. With linkType=gs1:<type> it redirects (307) to the first link of that type. Without either it shows the product page (HTML). One GTIN used by several brands returns a choice of their pages.

Tham số

TrườngKiểuMô tả
gtin
path · bắt buộc
stringGTIN (8–14 digits)
Ví dụ: 05901234123457
lot
path · bắt buộc
string
linkType
query
string"linkset" = the whole linkset (also with Accept: application/linkset+json); "gs1:pip" etc. = 307 redirect to the first link of that type
lang
query
string
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.
Accept
header
stringapplication/linkset+json returns the linkset without linkType.

Phản hồi 200 · application/linkset+json

Linkset

  • linksetmap<string, string | object[]>[]bắt buộc
    One entry: "anchor" (the GS1 URI) and one key per link type (https://gs1.org/voc/pip, …/instructions, …/certificationInfo, …/sustainabilityInfo, …/recallStatus)
    Các trường
    • hrefstringbắt buộc
    • titlestring
    • typestring
    • hreflangstring[]
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/01/05901234123457/10/L2026-10?linkType=linkset'

JavaScript

const res = await fetch('https://itemoo.eu/01/05901234123457/10/L2026-10?linkType=linkset', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/01/05901234123457/10/L2026-10?linkType=linkset');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Resolve a GTIN with a serial number

get/01/{gtin}/21/{serial}

không cần khóa

GS1 Digital Link resolver. With linkType=linkset or Accept: application/linkset+json it returns the linkset (RFC 9264) built from the published page: product page, instructions, certificates, passport and recall status. With linkType=gs1:<type> it redirects (307) to the first link of that type. Without either it shows the product page (HTML). One GTIN used by several brands returns a choice of their pages.

Tham số

TrườngKiểuMô tả
gtin
path · bắt buộc
stringGTIN (8–14 digits)
Ví dụ: 05901234123457
serial
path · bắt buộc
string
linkType
query
string"linkset" = the whole linkset (also with Accept: application/linkset+json); "gs1:pip" etc. = 307 redirect to the first link of that type
lang
query
string
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.
Accept
header
stringapplication/linkset+json returns the linkset without linkType.

Phản hồi 200 · application/linkset+json

Linkset

  • linksetmap<string, string | object[]>[]bắt buộc
    One entry: "anchor" (the GS1 URI) and one key per link type (https://gs1.org/voc/pip, …/instructions, …/certificationInfo, …/sustainabilityInfo, …/recallStatus)
    Các trường
    • hrefstringbắt buộc
    • titlestring
    • typestring
    • hreflangstring[]
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/01/05901234123457/21/SN-0001?linkType=linkset'

JavaScript

const res = await fetch('https://itemoo.eu/01/05901234123457/21/SN-0001?linkType=linkset', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/01/05901234123457/21/SN-0001?linkType=linkset');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Resolve a GTIN with a batch and a serial number

get/01/{gtin}/10/{lot}/21/{serial}

không cần khóa

GS1 Digital Link resolver. With linkType=linkset or Accept: application/linkset+json it returns the linkset (RFC 9264) built from the published page: product page, instructions, certificates, passport and recall status. With linkType=gs1:<type> it redirects (307) to the first link of that type. Without either it shows the product page (HTML). One GTIN used by several brands returns a choice of their pages.

Tham số

TrườngKiểuMô tả
gtin
path · bắt buộc
stringGTIN (8–14 digits)
Ví dụ: 05901234123457
lot
path · bắt buộc
string
serial
path · bắt buộc
string
linkType
query
string"linkset" = the whole linkset (also with Accept: application/linkset+json); "gs1:pip" etc. = 307 redirect to the first link of that type
lang
query
string
Accept-Language
header
stringPreferred language of the texts (fact names, description) when lang is missing.
Accept
header
stringapplication/linkset+json returns the linkset without linkType.

Phản hồi 200 · application/linkset+json

Linkset

  • linksetmap<string, string | object[]>[]bắt buộc
    One entry: "anchor" (the GS1 URI) and one key per link type (https://gs1.org/voc/pip, …/instructions, …/certificationInfo, …/sustainabilityInfo, …/recallStatus)
    Các trường
    • hrefstringbắt buộc
    • titlestring
    • typestring
    • hreflangstring[]
Lỗi
404
  • unknownCode — Unknown code
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.

Ví dụ

cURL

curl -X GET 'https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001?linkType=linkset'

JavaScript

const res = await fetch('https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001?linkType=linkset', {
  method: 'GET',
});
const data = await res.json();

PHP

$ch = curl_init('https://itemoo.eu/01/05901234123457/10/L2026-10/21/SN-0001?linkType=linkset');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

Resolver description

get/.well-known/gs1resolver

không cần khóa

GS1 resolver description: supported keys and link types, for scanners and passport registries.

Phản hồi 200 · application/json

object

    Lỗi
    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.

    Ví dụ

    cURL

    curl -X GET 'https://itemoo.eu/.well-known/gs1resolver'

    JavaScript

    const res = await fetch('https://itemoo.eu/.well-known/gs1resolver', {
      method: 'GET',
    });
    const data = await res.json();

    PHP

    $ch = curl_init('https://itemoo.eu/.well-known/gs1resolver');
    curl_setopt_array($ch, [
      CURLOPT_CUSTOMREQUEST => 'GET',
      CURLOPT_RETURNTRANSFER => true,
    ]);
    $data = json_decode(curl_exec($ch), true);