API del pasaporte digital de producto: documentación para desarrolladores

Resumen

La API de cliente es una interfaz REST que utiliza JSON. Trabaja sobre los datos de su mandante, es decir, los mismos productos y pasaportes que ve en la aplicación web. Usos típicos son la conexión de un sistema ERP o PLM, una sincronización nocturna de datos maestros o un script que obtiene códigos QR para imprimir.

La URL base es https://dpp.com2u.selfhost.eu/api/v1/integration. Todas las respuestas son JSON, excepto las descargas de códigos QR y PDF.

Descargar la especificación

La referencia legible por máquina de todos los endpoints, campos, ejemplos y respuestas de error es una especificación OpenAPI 3.1 con el esquema de seguridad ApiKeyAuth:

• Descargar openapi.json
• Descargar openapi.yaml

La propia API ofrece el mismo archivo en GET /api/v1/integration/openapi.json, sin clave. Impórtelo en Swagger UI, Postman o en el generador de código que prefiera. Las descripciones dentro del archivo están redactadas en alemán.

Inicio rápido

1. Regístrese o inicie sesión. La API forma parte de las tarifas de pago, consulte Precios.
2. Abra el área Mandante en la plataforma y genere la clave de API. Cópiela de inmediato, porque se muestra una sola vez.
3. Pruebe la conexión:

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

La respuesta indica su mandante, los scopes de la clave, su tarifa y su consumo de llamadas a la API.

Autenticación

Envíe la clave en cada llamada en la cabecera X-API-Key. Authorization: Bearer dpp_key_… funciona igual. El mandante se deduce siempre de la clave; un ID de mandante pasado como parámetro se ignora. La API no acepta tokens de sesión de la aplicación web.

La clave pertenece a la persona que la generó. Las acciones se ejecutan con los derechos de esa persona como propietaria o administradora. Si la persona pierde ese rol, la API responde con 403 hasta que se genere una clave nueva. Generar una clave nueva revoca la anterior de inmediato. La plataforma solo almacena un hash SHA-256 de la clave.

Endpoints

Todas las rutas están bajo /api/v1/integration. Cada endpoint requiere un scope; una clave nueva incluye los cuatro.

Crear un producto

name es obligatorio. Sin schema_key se aplica el esquema predeterminado de su mandante; GET /schemas devuelve las claves disponibles. Puede pasar los campos de datos directamente. field_status define el estado de los valores, y solo los valores approved pasan a un pasaporte.

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Battery module X1","category":"Industrial batteries",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

La respuesta con estado 201 contiene el id del producto. Es también el identificador único de producto codificado en el código QR. Se aplica la cuota de productos de su tarifa, igual que en la aplicación web.

Publicar un pasaporte, descargar el código QR y el PDF

Un pasaporte congela los campos de datos aprobados como una nueva versión. Si faltan campos obligatorios, la API responde con 422 y los enumera en missing_fields.

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

Para un código QR vectorial utilice format=svg. El PDF existe solo después de la publicación; antes, la API responde con 404. El código QR apunta a la página pública del pasaporte; para más información, consulte Crear un pasaporte digital de producto desde Excel.

Códigos de error

En 401 y 403, detail contiene un objeto con code y message, por ejemplo insufficient_scope o api_not_in_plan. En 402, detail indica el recurso, el límite y el consumo hasta el momento.

Límites

A través de la API se definen campos de datos a nivel de producto. Los campos de lotes o de unidades individuales se mantienen en la aplicación web. No hay un límite de frecuencia, pero sí una cuota de llamadas por tarifa; cada llamada autenticada cuenta. Obtener la especificación no cuenta. Las tarifas y cuotas actuales están en la página de Precios. Para la importación masiva sin la API, utilice la plantilla de datos.