Documentación para plataformas de pasaportes
dpp-backup.com ofrece las llamadas de ciclo de vida de EN 18222. Una plataforma envía pasaportes con CreateDPP y UpdateDPPById, y cuatro llamadas de lectura responden desde la copia. Cada versión almacenada se devuelve con un acuse de recibo firmado con Ed25519.
Lo básico
- Dirección:
https://dpp-backup.com/api/v1 - Credencial:
Authorization: Bearer <credential>. La marca crea la conexión en su portal y le entrega la credencial. Da acceso a la copia de esa marca y a ninguna otra. - Cuerpo: JSON, como máximo 1 048 576 bytes.
- Rutas: como en la tabla 16 de EN 18222. Codifique con porcentajes un id en la ruta.
Envío de pasaportes
| Llamada EN 18222 | Solicitud | Respuesta |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps con el pasaporte completo | 201 y la versión almacenada |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} con las partes que cambiaron | 200 y el pasaporte tal como se almacenó |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Siempre 405. Una copia de seguridad se conserva durante toda la vida del pasaporte. |
Una actualización es un JSON merge patch (RFC 7396), como sugiere EN 18222 8.1. Un null elimina un miembro. El parche se fusiona con la versión almacenada más reciente y el resultado se almacena como la versión siguiente. Si el pasaporte fusionado no es válido, no se almacena nada.
Lo que debe tener un pasaporte
Los atributos de la tabla 1 de EN 18223:
digitalProductPassportId: una cadena de 500 caracteres como máximo. No puede cambiar en una actualización.uniqueProductIdentifier: por ejemplo, una dirección GS1 Digital Link.granularity:model,batchoitem.dppSchemaVersiondppStatus:active,inactive,archivedoinvalid. Solo se hace copia de seguridad de los pasaportes publicados, por lo que un borrador se rechaza.lastUpdated: ISO 8601 con zona horaria, por ejemplo2026-11-16T09:00:00Z. Se conserva, pero la hora de una versión es la hora en que se almacenó.economicOperatorId- Si se indican:
facilityId(una cadena) ycontentSpecificationIds(una lista de cadenas).
Todo lo demás del pasaporte es un elemento de datos y se almacena tal como se envió.
Lo que no es público
EN 18222 no incluye reglas de acceso propias, por lo que usted enumera los elementos de datos que no son públicos en un miembro adicional, x-backup. No es un elemento de datos y nunca se publica.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
EN 18221 4.3 pide que la copia mantenga las restricciones de acceso del pasaporte original, y esta lista es la forma en que la copia las conoce. Sin ella, no mostramos públicamente ningún dato de producto de esa versión en lugar de adivinar. En una actualización, un miembro que usted omita se mantiene como estaba.
Documentos adjuntos (EN 18221 4.4): aquí aún no se describe cómo enviar sus archivos. Próximamente
Volver a enviar una llamada
Una creación o una actualización puede llevar una cabecera Idempotency-Key de 1 a 200 caracteres imprimibles. La misma clave con la misma solicitud devuelve de nuevo la primera respuesta, con Idempotent-Replay: true, y no se almacena nada nuevo. La misma clave con otra solicitud se rechaza.
Un ejemplo
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..."
}
}
Lectura desde la copia
| Llamada EN 18222 | Solicitud |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, un GTIN de 8 a 14 dígitos o una dirección GS1 Digital Link |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds con {"productIds": ["09506000134352"]}, como máximo 1000 GTIN |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Una lectura devuelve la versión más reciente o, para una fecha, la versión vigente en ese momento. Solicite application/json, application/ld+json o text/html en la cabecera Accept (negociación de contenido de EN 18216). Cada respuesta indica que es la copia de seguridad, qué versión es y el hash SHA-256 de su contenido.
La propia dirección del pasaporte también funciona: /01/{gtin} seguida de las claves de GS1 Digital Link.
Las llamadas de lectura responden en un dominio abierto a la lectura. Un dominio se abre cuando una marca redirige a la copia el dominio de sus pasaportes. En cualquier otro caso, una lectura responde 404.
No se ofrecen: ReadDataElement y UpdateDataElement (EN 18222, capítulo 6).
Acuses de recibo
Cada versión almacenada recibe un acuse de recibo. Consta de dos partes unidas por un punto, cada una en base64url sin relleno:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
La firma cubre la primera parte exactamente tal como está escrita, por lo que no hay que ordenar nada antes de comprobarla. El JSON contiene:
| Campo | Qué es |
|---|---|
v | La versión del formato, actualmente 1 |
key_id | La clave que lo firmó |
receipt_id | El id de la versión almacenada |
sender | Quién envió la versión |
dpp_id | El digitalProductPassportId |
version_number | El número de la versión, a partir de 1 |
content_sha256 | El hash SHA-256 del contenido, en hexadecimal |
received_at | Cuándo se almacenó la versión |
La clave 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 son los primeros 16 dígitos hexadecimales del hash SHA-256 de la clave en su forma SPKI. Compruebe un acuse de recibo en la página de verificación o con cualquier biblioteca Ed25519.
Códigos de error
Una creación o una actualización rechazada responde con el objeto de resultado de 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 | Cuándo (creación y actualización) |
|---|---|
| 400 | El cuerpo no es un objeto JSON, falta un atributo obligatorio o es incorrecto, el pasaporte es un borrador, se cambió el id, o la Idempotency-Key no es válida o se usó con otra solicitud. |
| 401 | La credencial es incorrecta o falta. |
| 403 | La conexión ya no está vigente. |
| 404 | Una actualización de un pasaporte que no se conserva para esta conexión. |
| 405 | Una eliminación, o un método no permitido en la ruta. |
| 409 | Una creación de un pasaporte que ya se conserva, una actualización que coincidió con otra actualización, o una llamada cuya Idempotency-Key aún se está procesando (con Retry-After). |
| 413 | El cuerpo, o el pasaporte tras la actualización, supera 1 048 576 bytes. |
| 429 | Demasiadas llamadas. Espere los segundos indicados en Retry-After. |
| 500 | No se pudo almacenar el pasaporte. Vuelva a enviarlo; con la misma Idempotency-Key no se almacena nada dos veces. |
Las llamadas de lectura responden {"error": "…"}:
| Estado | Cuándo (lecturas) |
|---|---|
| 300 | Más de una marca conserva un pasaporte en esta dirección. La respuesta las enumera. |
| 400 | Falta el id, el GTIN o la fecha, o no es válido. |
| 404 | El pasaporte no se conserva en la copia, o el dominio no está abierto a la lectura. |
| 405 | Un método no permitido en la ruta. |
| 413 | Más de 1000 identificadores de producto. |
| 429 | Demasiadas solicitudes. Espere los segundos indicados en Retry-After. |
| 503 | No disponible temporalmente. Vuelva a intentarlo después de Retry-After. |
Conserve una copia de seguridad de sus pasaportes
Cree una organización con el correo electrónico de su empresa. Una vez aprobada, conecte la plataforma que contiene sus pasaportes.
Se necesita una dirección de correo electrónico de empresa. Nuestro equipo revisa las nuevas organizaciones en días laborables. El portal está en inglés.