Usar la API REST de DPP Shield

Dónde está la referencia

La referencia de la API, en /en/developers, lista cada operación, generada a partir del código de la API, y ofrece el archivo OpenAPI 3.1 para descargar (https://dppshield.com/openapi.json) e importarlo en Postman, Insomnia o un generador de código. La URL base es https://api.dppshield.com/api/v1. La referencia técnica se publica en inglés.

Crear una clave

Envíe la clave como X-API-Key: dpk_… o Authorization: Bearer dpk_…. Una clave pertenece a su organización, así que no hace falta cabecera de organización. Actúa en nombre del miembro que la creó, para la trazabilidad, y está limitada por el rol y el rol personalizado de ese miembro; si el miembro se va, la clave deja de funcionar.

1. Abra Settings, API keys (propietarios y administradores).
2. Ponga a la clave el nombre de la integración que la usará, elija sus scopes y, si quiere, una caducidad en días.
3. Copie la clave: empieza por dpk_ y se muestra una sola vez; DPP Shield guarda solo una huella y el prefijo visible.
4. Guárdela en su gestor de secretos, nunca en el código fuente.

Scopes

Una clave nueva recibe dpp:read, dpp:write y compliance:read salvo que elija otra cosa. Dé a cada integración solo lo que usa, y una clave por integración, para que revocar una no rompa las demás.

Scopes disponibles

• dpp:read y dpp:write - pasaportes y sus versiones.
• compliance:read - resultados de validación.
• products:read y products:write - el catálogo.
• product-models:read y product-models:write - modelos y variantes.
• suppliers:write y documents:write - proveedores y documentos de prueba.
• claims:read, claims:write y evidence-graph:read - declaraciones y grafo de pruebas.
• custody:read y custody:write - el registro de cadena de custodia.
• data-mappings:write - ejecuciones del hub de integración.
• identity:read, exports:read y analytics:read - comprobaciones de identidad, exportaciones CSV y estadísticas.

Primeras llamadas

Estas llamadas cubren una primera integración habitual: leer el catálogo, crear un producto y su pasaporte, guardar datos y validarlos.

Operaciones habituales

• GET /products lista el catálogo; GET /products/search?q=…&category=…&page=1&pageSize=50 devuelve una página filtrada.
• POST /products crea un producto (name, sku, category, gtin…).
• POST /dpp con productId y schemaId (eu-<categoría>, por ejemplo eu-battery) crea un pasaporte en borrador.
• PUT /dpp/{id} con data guarda una nueva versión; envíe expectedVersion para que se rechace (409) si alguien guardó entre medias.
• POST /dpp/{id}/validate?markets=EU ejecuta la validación y devuelve los hallazgos.
• GET /dpp/search?status=active devuelve pasaportes por estado; GET /public/dpp/{id} lee un pasaporte publicado sin clave.

Límites de uso

Las solicitudes se cuentan por organización y por hora, con presupuestos distintos para lecturas y escrituras fijados por su plan. Cada respuesta lleva x-ratelimit-limit, x-ratelimit-remaining y x-ratelimit-reset; por encima del límite la API responde 429 con Retry-After. Las rutas públicas, como la lectura de pasaportes y el resolutor GS1, se cuentan por dirección de cliente.

Lo que una clave no puede hacer

Publicar un pasaporte, decidir una excepción de publicación, registrar una versión en el registro de la UE y publicar, retirar o archivar en bloque son actos de responsabilidad. En DPP Shield exigen una persona que haya confirmado un segundo factor en los últimos 15 minutos, así que se rechaza una clave de API. Prepare y valide por la API y deje que un propietario o administrador publique. La lista de direcciones de red permitidas de la organización también se aplica a las claves de API.

Errores

Los errores llegan en JSON con un mensaje que nombra el problema.

Códigos de estado

• 400 - el cuerpo o un valor no pasó la validación; el mensaje nombra el campo.
• 401 - la clave falta, está revocada o ha caducado.
• 403 - el scope de la clave, el rol de su creador o un rol personalizado no permite la operación.
• 404 - el registro no existe en esta organización o está fuera de los espacios de trabajo de un miembro restringido.
• 409 - el pasaporte cambió desde la versión enviada.
• 429 - se alcanzó el límite de uso; espere lo indicado en Retry-After.