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 18222SolicitudRespuesta
CreateDPP (4.6)POST /api/v1/dpps con el pasaporte completo201 y la versión almacenada
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} con las partes que cambiaron200 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, batch o item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived o invalid. Solo se hace copia de seguridad de los pasaportes publicados, por lo que un borrador se rechaza.
  • lastUpdated: ISO 8601 con zona horaria, por ejemplo 2026-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) y contentSpecificationIds (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 18222Solicitud
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:

CampoQué es
vLa versión del formato, actualmente 1
key_idLa clave que lo firmó
receipt_idEl id de la versión almacenada
senderQuién envió la versión
dpp_idEl digitalProductPassportId
version_numberEl número de la versión, a partir de 1
content_sha256El hash SHA-256 del contenido, en hexadecimal
received_atCuá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"
    }
  ]
}
EstadoCuándo (creación y actualización)
400El 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.
401La credencial es incorrecta o falta.
403La conexión ya no está vigente.
404Una actualización de un pasaporte que no se conserva para esta conexión.
405Una eliminación, o un método no permitido en la ruta.
409Una 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).
413El cuerpo, o el pasaporte tras la actualización, supera 1 048 576 bytes.
429Demasiadas llamadas. Espere los segundos indicados en Retry-After.
500No 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": "…"}:

EstadoCuándo (lecturas)
300Más de una marca conserva un pasaporte en esta dirección. La respuesta las enumera.
400Falta el id, el GTIN o la fecha, o no es válido.
404El pasaporte no se conserva en la copia, o el dominio no está abierto a la lectura.
405Un método no permitido en la ruta.
413Más de 1000 identificadores de producto.
429Demasiadas solicitudes. Espere los segundos indicados en Retry-After.
503No 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.