Documentação para plataformas de passaportes
O dpp-backup.com oferece as chamadas de ciclo de vida da EN 18222. Uma plataforma envia passaportes com CreateDPP e UpdateDPPById, e quatro chamadas de leitura respondem a partir da cópia. Cada versão armazenada é devolvida com um recibo assinado com Ed25519.
O essencial
- Endereço:
https://dpp-backup.com/api/v1 - Credencial:
Authorization: Bearer <credential>. A marca cria a ligação no seu portal e entrega-lhe a credencial. Esta dá acesso à cópia dessa marca e a mais nenhuma. - Corpo: JSON, no máximo 1 048 576 bytes.
- Caminhos: como no quadro 16 da EN 18222. Codifique um id no caminho com codificação percentual.
Enviar passaportes
| Chamada EN 18222 | Pedido | Resposta |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps com o passaporte completo | 201 e a versão armazenada |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} com as partes que mudaram | 200 e o passaporte tal como foi armazenado |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Sempre 405. Uma cópia de segurança é conservada durante toda a vida do passaporte. |
Uma atualização é um JSON merge patch (RFC 7396), como sugere a EN 18222, 8.1. Um null remove um membro. O patch é fundido na versão armazenada mais recente, e o resultado é armazenado como a versão seguinte. Se o passaporte resultante não for válido, nada é armazenado.
O que um passaporte tem de ter
Os atributos do quadro 1 da EN 18223:
digitalProductPassportId: uma cadeia de, no máximo, 500 caracteres. Não pode mudar numa atualização.uniqueProductIdentifier: por exemplo, um endereço GS1 Digital Link.granularity:model,batchouitem.dppSchemaVersiondppStatus:active,inactive,archivedouinvalid. Só são guardadas cópias de segurança de passaportes publicados, pelo que um rascunho é recusado.lastUpdated: ISO 8601 com fuso horário, por exemplo2026-11-16T09:00:00Z. É conservado, mas o momento de uma versão é o momento em que foi armazenada.economicOperatorId- Quando indicados:
facilityId(uma cadeia) econtentSpecificationIds(uma lista de cadeias).
Tudo o resto no passaporte é um elemento de dados e é armazenado tal como foi enviado.
O que não é público
A EN 18222 não tem regras de acesso próprias, por isso indica os elementos de dados que não são públicos num membro adicional, x-backup. Não é um elemento de dados e nunca é publicado.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
A EN 18221, 4.3, pede que a cópia mantenha as restrições de acesso do passaporte original, e é por esta lista que a cópia as conhece. Sem ela, não mostramos publicamente nenhum dado de produto dessa versão, em vez de adivinhar. Numa atualização, um membro que omita fica como estava.
Documentos anexos (EN 18221, 4.4): a forma de enviar os respetivos ficheiros ainda não está descrita aqui. Em breve
Enviar uma chamada novamente
Uma criação ou uma atualização pode levar um cabeçalho Idempotency-Key de 1 a 200 caracteres imprimíveis. A mesma chave com o mesmo pedido recebe de novo a primeira resposta, com Idempotent-Replay: true, e nada de novo é armazenado. A mesma chave com outro pedido é recusada.
Um exemplo
POST /api/v1/dpps HTTP/1.1
Host: dpp-backup.com
Authorization: Bearer <credential>
Content-Type: application/json
Idempotency-Key: 2f1f3c9b-create-1
{
"digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
"uniqueProductIdentifier": "https://id.example.com/01/09506000134352/21/ABC123",
"granularity": "item",
"dppSchemaVersion": "1.0",
"dppStatus": "active",
"lastUpdated": "2026-11-16T09:00:00Z",
"economicOperatorId": "urn:example:operator:4012345000009",
"x-backup": { "withheldFromPublic": ["supplierPrice"] },
"productName": "Wool jumper",
"supplierPrice": "internal"
}
HTTP/1.1 201 Created
Backup-Receipt: eyJ2IjoxLCJrZXlfaWQiOi...
{
"digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
"x-backup": {
"versionNumber": 1,
"receivedAt": "2026-11-16T09:00:01.482Z",
"versionId": "0d6e7a52-5b0c-4f7e-9d0e-8a3c1f9b2c44",
"contentSha256": "3b5d…64 hex digits…9f1c",
"receipt": "eyJ2IjoxLCJrZXlfaWQiOi..."
}
}
Ler a partir da cópia
| Chamada EN 18222 | Pedido |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, um GTIN de 8 a 14 dígitos ou um endereço GS1 Digital Link |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds com {"productIds": ["09506000134352"]}, no máximo 1000 GTIN |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Uma leitura devolve a versão mais recente ou, para uma data, a versão que estava em vigor nesse momento. Peça application/json, application/ld+json ou text/html no cabeçalho Accept (negociação de conteúdo da EN 18216). Cada resposta indica que se trata da cópia de segurança, que versão é e o hash SHA-256 do seu conteúdo.
O próprio endereço do passaporte também funciona: /01/{gtin} seguido das chaves GS1 Digital Link.
As chamadas de leitura respondem num domínio aberto para leitura. Um domínio é aberto quando uma marca aponta o seu domínio de passaportes para a cópia. Em qualquer outro caso, uma leitura responde 404.
Não oferecidas: ReadDataElement e UpdateDataElement (EN 18222, secção 6).
Recibos
Cada versão armazenada recebe um recibo. É composto por duas partes unidas por um ponto, cada uma em base64url sem preenchimento:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
A assinatura abrange a primeira parte exatamente como está escrita, pelo que nada tem de ser ordenado antes da verificação. O JSON contém:
| Campo | O que é |
|---|---|
v | A versão do formato, atualmente 1 |
key_id | A chave que o assinou |
receipt_id | O id da versão armazenada |
sender | Quem enviou a versão |
dpp_id | O digitalProductPassportId |
version_number | O número da versão, a partir de 1 |
content_sha256 | O hash SHA-256 do conteúdo, em hexadecimal |
received_at | Quando a versão foi armazenada |
A chave pública
GET /.well-known/backup-receipt-key responde:
{
"algorithm": "Ed25519",
"key_id": "…16 hex digits…",
"public_key_spki_base64": "MCowBQYDK2VwAyEA…",
"receipt_format": "base64url(JSON) \".\" base64url(signature over the first part as written)"
}
key_id são os primeiros 16 dígitos hexadecimais do hash SHA-256 da chave na sua forma SPKI. Verifique um recibo na página de verificação ou com qualquer biblioteca Ed25519.
Códigos de erro
Uma criação ou atualização recusada responde com o objeto de resultado da EN 18222, 7.2:
{
"message": [
{
"messageType": "Error",
"text": "dppStatus is \"draft\". Drafts are not backed up: send the passport when it is published",
"code": "400",
"timestamp": "2026-11-16T09:00:01.482Z"
}
]
}
| Estado | Quando (criação e atualização) |
|---|---|
| 400 | O corpo não é um objeto JSON, falta um atributo obrigatório ou está errado, o passaporte é um rascunho, o id foi alterado, ou a Idempotency-Key não é válida ou foi usada com outro pedido. |
| 401 | A credencial está errada ou em falta. |
| 403 | A ligação já não está em vigor. |
| 404 | Uma atualização de um passaporte que não está guardado para esta ligação. |
| 405 | Uma eliminação, ou um método que não é permitido no caminho. |
| 409 | Uma criação de um passaporte que já está guardado, uma atualização que coincidiu com outra atualização, ou uma chamada cuja Idempotency-Key ainda está em curso (com Retry-After). |
| 413 | O corpo, ou o passaporte após a atualização, tem mais de 1 048 576 bytes. |
| 429 | Demasiadas chamadas. Aguarde os segundos indicados em Retry-After. |
| 500 | Não foi possível armazenar o passaporte. Envie-o novamente; com a mesma Idempotency-Key, nada é armazenado duas vezes. |
As chamadas de leitura respondem {"error": "…"}:
| Estado | Quando (leituras) |
|---|---|
| 300 | Mais do que uma marca tem um passaporte neste endereço. A resposta enumera-as. |
| 400 | O id, o GTIN ou a data estão em falta ou não são válidos. |
| 404 | O passaporte não está guardado na cópia, ou o domínio não está aberto para leitura. |
| 405 | Um método que não é permitido no caminho. |
| 413 | Mais de 1000 identificadores de produto. |
| 429 | Demasiados pedidos. Aguarde os segundos indicados em Retry-After. |
| 503 | Temporariamente indisponível. Tente novamente após Retry-After. |
Guarde uma cópia de segurança dos seus passaportes
Crie uma organização com o email da sua empresa. Depois de aprovada, ligue a plataforma que contém os seus passaportes.
É necessário um endereço de email da empresa. A nossa equipa analisa as novas organizações nos dias úteis. O portal está em inglês.