API del Registro DPP: cómo registrar pasaportes de baterías en la UE, paso a paso

TL;DR

• El 30 de octubre de 2026 la Comisión Europea publicó las especificaciones técnicas de la API del Registro DPP: una guía de integración, archivos OpenAPI, guías de autenticación para cuentas de servicio y para pasaportes autoalojados, y los modelos de datos semánticos para baterías.
• El registro es asíncrono y de todo o nada: envías hasta 100 pasaportes por solicitud, el Registro recupera y valida cada pasaporte desde su dirección web y, si un elemento falla, no se registra ninguno.
• Las baterías son el único grupo de productos definido hasta ahora. Las baterías de vehículos eléctricos, las LMT y las industriales de más de 2 kWh necesitan un pasaporte registrado a partir del 18 de febrero de 2027, y tu organización tiene que estar verificada con un sello electrónico cualificado antes de que funcione cualquier llamada a la API.

La API del Registro DPP es la vía por la que un fabricante, un importador o la plataforma que trabaja para ellos registra pasaportes digitales de producto ante la UE sin tener que rellenar un formulario web producto a producto. El Registro en sí está operativo desde el 20 de julio de 2026. Lo que llegó el 30 de octubre es el detalle que un desarrollador necesita para construir sobre él: endpoints, autenticación, códigos de error, reglas de consulta periódica y los modelos de datos con los que el Registro valida los pasaportes.

Esta guía es para la persona que tiene que conseguir que los pasaportes de baterías aparezcan en el Registro en febrero. Sigue los documentos en el orden en que te los vas a encontrar y separa lo que está decidido de lo que sigue abierto. Para saber qué es el Registro y por qué existe, consulta nuestra explicación del registro DPP de la UE. Todo lo que sigue se expone según la situación a noviembre de 2026.

¿Qué publicó la Comisión el 30 de octubre?

Seis documentos técnicos aparecieron en la página de recursos sobre el DPP de la Comisión, sin ninguna noticia que los anunciara. Se suman a la User Guide for Economic Operators de septiembre de 2026.

El 19 de octubre la Comisión publicó además la versión 3.2 de su guía sobre el pasaporte de batería, que enumera los datos por categoría de batería. La tratamos más abajo.

La parte vinculante es el Reglamento de Ejecución (UE) 2026/1778, de 16 de julio de 2026. El artículo 3, letra b), prevé una API para el registro, el artículo 8, apartado 6, permite registrar a través de la interfaz de usuario o de la API, y el artículo 8, apartado 7, exige comprobaciones automáticas de la semántica y la granularidad. Las especificaciones son la forma en que la Comisión aplica esos artículos.

¿Qué hace el Registro con tu pasaporte?

El Registro es un índice, no un almacén. Le envías un identificador único de producto (UPI) por cada pasaporte, y la API exige que ese UPI sea una URL HTTPS. En el momento del envío, el Registro acude a esa URL, recupera el pasaporte y lo valida con el modelo de datos del grupo de productos. En palabras de la guía de integración, el Registro «no conserva el contenido del DPP recuperado».

Esa única decisión de diseño explica la mayor parte del trabajo de ingeniería. El pasaporte tiene que estar en línea, completo y ser válido en el momento en que lo envías, no después. Si el Registro no puede acceder a él, el elemento falla con UPI_NOT_RESOLVABLE. Si el contenido no coincide con el esquema, falla como ITEM_NON_COMPLIANT. Un flujo de trabajo que registra primero y publica el pasaporte después no funcionará.

Cuando el registro se completa con éxito, el artículo 9 del Reglamento de Ejecución te da una prueba de registro sellada con el sello electrónico cualificado de la Comisión, disponible durante 90 días. Descárgala y archívala: es tu prueba de que el pasaporte se registró y de cuándo.

¿Qué tiene que estar listo antes de la primera llamada a la API?

Más de lo que la mayoría de los equipos espera, y casi nada de ello es código.

Una organización verificada. Los usuarios inician sesión con EU Login, pero la API rechaza con un 403 las solicitudes de una organización que no esté verificada. Conforme al artículo 4 del Reglamento de Ejecución, una persona jurídica acredita su identidad y su establecimiento con un sello electrónico cualificado (o una declaración electrónica de atributos); un empresario individual puede usar una firma electrónica cualificada o una eID con nivel de seguridad «alto» de eIDAS. En la práctica, el Registro te entrega una declaración sellada por la Comisión, y tú la firmas o la sellas. La condición de verificado dura hasta que caducan tus medios de identificación, y como máximo tres años, tras los cuales tienes que volver a verificarte.

Un sello cualificado lo emite un prestador cualificado de servicios de confianza, con sus propias comprobaciones de identidad. Si tu empresa no tiene uno, empieza por aquí.

Un administrador y una cuenta de servicio. El administrador de tu organización crea las cuentas de servicio en la interfaz del Registro. Una cuenta de servicio es una identidad no humana vinculada a tu organización verificada, y necesita el rol que permite registrar DPP. La organización se toma del token de acceso, así que nunca pasas un identificador de organización en la solicitud.

Clasificación del producto. Cada envío indica un grupo y un subgrupo de productos, que obtienes de GET /api/v1/dpp/product-groups en lugar de fijarlos en el código. Hoy esa llamada devuelve un único grupo, BATTERIES, con los subgrupos de vehículos eléctricos, LMT e industriales.

¿Cómo se autentica una cuenta de servicio?

El Registro usa credenciales de cliente de OAuth 2.0 con private_key_jwt. La guía es tajante: «No se admiten secretos de cliente compartidos». Tu sistema guarda una clave privada, firma una aserción de corta duración y la intercambia por un token de acceso.

Los detalles que van a pillar a más de uno:

• Solo claves de curva elíptica (ES256, ES384 o ES512). No se aceptan claves RSA. Subes la clave pública como JWK o PEM, y la guía recomienda guardar la clave privada en un módulo de seguridad de hardware.
• Aserciones cortas. La aserción del cliente debe caducar en un plazo de 60 a 120 segundos, nunca más de 5 minutos, con un jti nuevo cada vez.
• Un indicador de recurso. La solicitud del token debe nombrar al Registro como recurso, con el valor publicado para cada entorno.
• Tokens cortos. Los tokens de acceso duran como máximo 15 minutos, así que tu cliente tiene que renovarlos durante las ejecuciones por lotes largas.
• Límites. Hasta 5 cuentas de servicio por organización y 2 credenciales activas por cuenta, lo que permite rotar claves sin interrupciones. Se recomienda que las credenciales duren un año, dos como máximo.

Si una plataforma registra los pasaportes por ti, el modelo que describen los documentos de la versión 1.0 es una cuenta de servicio dentro de tu organización verificada. Así funciona la integración hoy, pero no es la única vía que permite la ley. El Reglamento de Ejecución también prevé terceros verificados que actúen en nombre de un agente económico: el artículo 6, apartado 1, permite a los agentes verificados delegar derechos de acceso en terceros cuando el Derecho de la Unión lo prevea, el artículo 8, apartado 2, permite en ese caso que un tercero verificado realice acciones de registro, y el artículo 19, apartado 4, exige que un tercero autorizado por un agente económico pase su propia verificación. El Registro también mantendrá una lista de proveedores de servicios de DPP verificados (artículo 3, letra f)). Cómo funcionará técnicamente esa delegación aún no se describe en las guías de integración. Sea cual sea la vía utilizada, el agente económico sigue siendo plenamente responsable del cumplimiento.

¿Cómo funciona un envío de registro?

El flujo tiene cuatro llamadas. Obtienes los grupos de productos, haces el envío y luego sigues la tarea a través de lo que la Comisión llama la Activity Dashboard API.

POST /api/v1/dpp/submission
Authorization: Bearer <access token>
Idempotency-Key: 7f3c9a2e-batch-2027-02-01-001
Content-Type: application/json

{
  "productGroup": "BATTERIES",
  "productSubGroup": "EV",
  "submissionItems": [
    {
      "uniqueProductIdentifier": "https://example.com/dpp/battery/0001",
      "granularity": "item",
      "batchIdentifier": "xxx-000",
      "modelIdentifier": "yyy-111"
    }
  ]
}

Ese cuerpo sigue el ejemplo oficial. uniqueProductIdentifier y granularity (artículo, lote o modelo) son obligatorios para cada elemento; los identificadores de lote y de modelo son opcionales.

El Registro responde 202 Accepted con un taskId. Un 202 solo significa que la solicitud se ha aceptado para su tratamiento. Después consultas periódicamente GET /api/v1/tasks/{taskId} y, cuando necesitas saber qué elementos han pasado, GET /api/v1/tasks/{taskId}/items, que devuelve JSON o CSV.

Hay dos campos de estado que importan, y significan cosas distintas. El status de la tarea pasa por PENDING, PROCESSING, COMPLETED o ERROR. Una vez completada, outcomeResult indica SUCCEEDED o FAILED. Una tarea puede estar COMPLETED con resultado FAILED: el tratamiento funcionó y tus datos no pasaron la validación. ERROR es un fallo técnico del lado del Registro.

No hay webhooks. La guía recomienda consultar a los 1, 1, 2, 3, 5, 8, 13, 21, 34 y 55 segundos, y después como máximo cada 60 segundos, y una cabecera Retry-After siempre prevalece sobre tu propio calendario.

La regla que debería dar forma a tu diseño de lotes es la atomicidad. Un envío contiene de 1 a 100 pasaportes del mismo grupo y subgrupo de productos y, si cualquiera de ellos no es conforme, no se registra ninguno, tampoco los que pasaron. Un registro defectuoso en un lote de 100 frena a 99 correctos. Nosotros validaríamos cada pasaporte en local con los esquemas publicados antes de enviarlo, mantendríamos lotes más pequeños mientras tus datos aún se están asentando y volveríamos a enviar rápidamente los elementos correctos tras un fallo.

La cabecera Idempotency-Key es obligatoria, con un máximo de 128 caracteres. Reintentar con la misma clave devuelve la tarea original en lugar de crear un duplicado, que es lo que quieres tras un tiempo de espera agotado o un 500. Un envío modificado necesita una clave nueva; reutilizar una clave para un contenido distinto devuelve un 409.

Los códigos de error son los habituales (400, 403, 409, 413, 422, 429, 500), y la guía indica para cada uno si hay que reintentar con la misma clave o con una nueva. Un 403 suele significar que la organización no está verificada o que la cuenta de servicio no tiene el rol de registro.

¿Qué cambia si alojas tú mismo los pasaportes?

Los pasaportes de baterías contienen datos públicos y restringidos, y el Registro lee ambos al validar. Si el pasaporte está en tu propio servidor, ese servidor tiene que reconocer al Registro y mostrarle más de lo que muestra al público.

Tu servidor de pasaportes actúa como servidor de recursos de OAuth 2.0. El Registro solicita primero el UPI sin credenciales y espera el pasaporte público. Después solicita la misma URL con un token de portador emitido por el servicio de autenticación de la Comisión y espera los datos públicos más los restringidos. El token es corto (ES384, como máximo 120 segundos), lleva el ámbito dpp:registry:read y va dirigido al origen HTTPS de tu servidor. Lo validas únicamente con las claves del JWKS publicado por la Comisión, nunca con claves referenciadas desde dentro del token.

Las reglas de respuesta son estrictas. Sin token: devuelve el pasaporte público. Token válido y solicitante autorizado: devuelve los datos públicos más los restringidos. Un token presente pero no válido: devuelve 401, sin recurrir a la vista pública. Token válido con un ámbito o un solicitante incorrectos: 403. Envía Vary: Authorization para que las cachés mantengan separadas las dos versiones, y usa TLS 1.2 o posterior. JSON es el formato de respuesta de base; también se aceptan JSON-LD y XML.

La guía describe un único solicitante, el propio Registro. No explica cómo se autenticarán las autoridades, los recicladores u otras partes con un interés legítimo, así que necesitarás una respuesta aparte para ellos; nuestra guía sobre los derechos de acceso al pasaporte digital de producto explica quién tiene derecho a qué. Los identificadores únicos de operador tampoco se procesan todavía; la guía los prevé para una versión futura.

Dónde encaja GS1 Digital Link

El Registro sigue redirecciones, como máximo tres en toda la resolución, y resuelve el UPI y cada redirección sin credenciales, así que cada paso debe ser accesible públicamente. Eso es compatible con un resolver. Un URI de GS1 Digital Link en tu propio dominio, como https://id.yourbrand.com/01/09520123456788/21/SN0001, es una forma de dar a cada batería un identificador HTTPS persistente que lleva a su pasaporte y que además funciona como el código QR del producto. No es obligatorio; cualquier URL HTTPS estable cumple la regla de formato de la API. Si usas un resolver, cuenta los saltos: una cadena del dominio del QR al resolver, del resolver al proveedor de alojamiento y de ahí a la URL final ya agota los tres. La guía también aconseja evitar redirecciones tras la autenticación, de modo que la solicitud autorizada llegue directamente al pasaporte.

¿Con qué modelos de datos valida el Registro?

El ZIP de Semantic Data Artifacts contiene los modelos que comprueba el Registro. Hoy solo existen dos: un modelo básico (core) y un modelo de baterías, ambos 1.0.0, con esquemas por subgrupo para baterías de vehículos eléctricos, LMT e industriales. Cada uno se entrega como JSON Schema (draft 2020-12), contextos JSON-LD, formas SHACL y vocabularios SKOS, además de un catálogo DCAT-AP. La guía también describe XSD, que no se incluye en esta versión.

Los esquemas se dividen por nivel de acceso: una vista pública (pub) y tres vistas restringidas (res1, res2, res3). Tu pasaporte tiene que presentar los campos adecuados al solicitante adecuado, y el esquema te dice qué campos van en cada sitio. El ZIP incluye también instancias de ejemplo conformes con cada esquema, que son un buen primer conjunto de datos de prueba.

Se describen cuatro serializaciones (JSON, JSON-LD, XML y RDF), pero JSON es la única obligatoria para el registro, en línea con la norma EN 18216:2026. La guía cita además la EN 18223:2026 sobre interoperabilidad. Explicamos ambas normas en la guía de las normas CEN sobre el DPP, y por qué importan los datos estructurados en nuestra guía sobre el pasaporte digital de producto legible por máquina. El artículo 12 del Reglamento de Ejecución añade que el repositorio semántico es de uso gratuito y tiene API públicas.

¿Qué añade la guía de baterías v3.2?

El Guidance Document: Digital Batteries Passport, data points by category, versión 3.2 de 19 de octubre de 2026, enumera 71 datos para las baterías de vehículos eléctricos, LMT e industriales. Es una guía y ella misma dice que no es jurídicamente vinculante; las obligaciones proceden del Reglamento de Baterías, Reglamento (UE) 2023/1542.

Para cada dato y categoría de batería, indica un estado: obligatorio; opcional, a rellenar si se dispone del dato; si procede; solo para determinados tipos de batería; o no debe rellenarse ni mostrarse a febrero de 2027. Ese último estado es el útil para planificar. La declaración y la etiqueta de huella de carbono, por ejemplo, figuran como no a rellenar en febrero de 2027 porque su formato aún está pendiente de un acto de ejecución, y las instrucciones de uso están en suspenso a la espera del Ómnibus. Cada dato lleva también un nivel de acceso: público; restringido a personas con un interés legítimo, organismos notificados, autoridades de los Estados miembros y la Comisión; o niveles restringidos más estrechos. Esos niveles son los que implementan las vistas de esquema pub y res.

Nuestra guía del pasaporte de batería cubre los requisitos legales. Para el trabajo de integración, usa la v3.2 como hoja de correspondencias entre tus datos de producto y los campos del esquema.

¿Qué está decidido y qué sigue abierto?

Decidido: los endpoints, el modelo de autenticación, la regla atómica de los lotes, la consulta periódica, el modelo de datos de baterías y el requisito de que los pasaportes estén en línea en el momento del envío. La verificación mediante sello cualificado figura en el propio Reglamento de Ejecución.

Abierto todavía a noviembre de 2026: cómo funcionará técnicamente el registro por terceros verificados en nombre de un agente económico, los modelos de datos para cualquier cosa que no sean baterías, el formato de la huella de carbono, cómo se autentican otras partes ante los pasaportes autoalojados y los identificadores únicos de operador. El Reglamento de Ejecución también abarca los productos de construcción, los juguetes y los detergentes, que aún no tienen modelo de datos; para los productos distintos de las baterías, las obligaciones empiezan al menos 18 meses después de cada acto delegado. Los Estados miembros deben designar a sus administradores nacionales del registro antes del 18 de febrero de 2027 (artículo 7).

Asperezas de los documentos de la versión 1.0

Una primera versión siempre tiene incoherencias, y conviene conocer estas antes de escribir código:

• La guía de cuentas de servicio da como base de la API reg.product-passport.ec.europa.eu, mientras que los archivos OpenAPI usan registry.product-passport.ec.europa.eu (y registry.acc.product-passport.ec.europa.eu para aceptación). Confirma el valor vigente en el Registro antes de configurar producción.
• El límite de 100 elementos figura en la guía, pero el esquema OpenAPI no lo impone, así que un cliente generado a partir del esquema construirá sin problema una solicitud de 101 elementos.
• La guía de integración dice que los errores devuelven el identificador como traceId, mientras que el esquema de error de OpenAPI lo llama correlationId. Registra ambos.
• La API usa el código de subgrupo EV, mientras que los artefactos semánticos usan evb en sus rutas. Haz la correspondencia de forma explícita.

Nada de esto bloquea la integración, pero vuelve a comprobarlo con cada nueva versión de los documentos.

Qué hacer ahora

1. Consigue un sello electrónico cualificado de un prestador cualificado de servicios de confianza, si tu empresa aún no tiene uno, y verifica tu organización en el Registro. Es lo que más plazo requiere de toda esta lista.
2. Date de alta en el entorno de aceptación y nombra a un administrador que pueda crear cuentas de servicio.
3. Decide dónde residen los pasaportes: en tu propio servidor, que entonces tendrá que implementar las reglas de autenticación para pasaportes autoalojados, o con un proveedor que ya lo haga.
4. Fija tus UPI. Elige un patrón de URL HTTPS estable para cada batería, decide la granularidad (artículo, lote o modelo) y cuenta las redirecciones de la cadena.
5. Haz la correspondencia de tus datos con la v3.2 y los esquemas de baterías, campo a campo, incluidas las vistas pública y restringidas. Marca lo que no se exige en febrero de 2027 para que nadie pierda tiempo en ello.
6. Valida en local antes de enviar, con los JSON Schemas publicados, y diseña los lotes de modo que un registro defectuoso no frene al resto.
7. Construye bien el cliente: claves EC en un HSM, renovación de tokens, claves de idempotencia que puedas reproducir, consulta periódica con la secuencia de Fibonacci y almacenamiento de cada prueba de registro.
8. Haz una prueba completa en aceptación con bastante antelación al 18 de febrero de 2027, incluidos un lote fallido y una rotación de claves.

Digital Link es partner de soluciones de GS1, y nuestra plataforma crea pasaportes de baterías y de producto sobre un identificador GS1 Digital Link persistente por producto, con datos públicos y restringidos servidos desde el mismo registro. Estamos preparando nuestra propia integración con el Registro. Eso implica tres pasos distintos: obtener nuestro sello electrónico cualificado, completar nuestra verificación en el Registro y desarrollar y probar la conexión con la API. Todavía no estamos conectados al Registro. Si quieres planificar tu integración con el Registro, o comprobar si los datos de tus pasaportes superarán la validación, ponte en contacto con nosotros y nuestro equipo revisará tu caso.

Preguntas frecuentes

¿Es obligatoria la API del Registro DPP?

No. El artículo 8, apartado 6, del Reglamento de Ejecución (UE) 2026/1778 permite registrar a través de la interfaz de usuario o de la API. En la práctica, cualquiera que registre más de un puñado de pasaportes querrá usar la API.

¿Almacena el Registro los datos de mi pasaporte?

No. Recupera el pasaporte desde su URL en el momento del envío para validarlo, y la guía de integración establece que no conserva el contenido recuperado. El pasaporte se queda donde lo alojas, y por eso tiene que estar accesible en el momento del envío.

¿Puedo usar una clave RSA o un secreto de cliente para mi cuenta de servicio?

No. Las cuentas de servicio se autentican con private_key_jwt mediante claves de curva elíptica (ES256, ES384 o ES512). No se admiten secretos de cliente compartidos ni claves RSA.

¿Qué ocurre si un pasaporte de un lote no supera la validación?

Falla todo el envío y no se registra ninguno de sus pasaportes. La tarea se completa con resultado FAILED, y los resultados por elemento te dicen qué elementos lo causaron. Corrígelos y vuelve a enviarlos con una nueva clave de idempotencia.

¿Necesito GS1 Digital Link para registrar un pasaporte?

No. El identificador único de producto debe ser una URL HTTPS que resuelva hacia el pasaporte. Un URI de GS1 Digital Link en tu propio dominio es una forma de cumplirlo, y sirve a la vez como código QR del producto, pero se acepta cualquier URL HTTPS estable.

¿Cuándo hay que registrar los pasaportes de baterías?

Para las baterías de vehículos eléctricos, las baterías LMT y las baterías industriales de más de 2 kWh, la obligación del pasaporte de batería conforme al Reglamento (UE) 2023/1542 se aplica a partir del 18 de febrero de 2027. El Registro y su entorno de aceptación ya están abiertos, así que hay tiempo para probar primero.