Saltar al contenido principal
Battery Compliance
Empezar gratis
Menú

Desarrolladores

Conecte su ERP o sus sistemas de producción: cree y publique pasaportes para baterías, léalos y actualícelos mediante una API del PDP conforme a la norma EN 18222 y reciba eventos por webhook. El acceso a la API está incluido en todos los planes, también en Free.

Dos API

  • API de gestión de pasaportes

    /openapi.json

    Para la empresa titular de los pasaportes: enumerar modelos y ejemplares (por cursor, con updatedSince para la sincronización), crear ejemplares, intervalos y copias de modelos, actualizar los datos de un ejemplar, publicar (un ejemplar o en segundo plano) y obtener códigos QR. Se autentica con una clave de API.

    Referencia: API de gestión de pasaportes

  • API del PDP (EN 18222)

    /openapi-dpp.json

    API de ciclo de vida y de granularidad fina conforme a la norma EN 18222: leer pasaportes con su nivel de acceso, buscar identificadores de pasaporte por identificador de producto, registrar eventos (reparación, estado de salud, estado) con un token de acceso OAuth 2.0. Los datos públicos pueden leerse sin token.

    Referencia: API del PDP (EN 18222)

Leer un pasaporte

Cada dirección de pasaporte responde con JSON cuando se lo pide; no hace falta clave para los datos públicos. Los encabezados contienen la versión, su SHA-256 y la firma Ed25519, de modo que puede contrastar lo que lee con nuestras claves públicas.

curl -i -H "Accept: application/json" \https://batterycompliance.eu/id/BG123456789/EBIKE-48V/SN0001 HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8X-Passport-Version: 3X-Passport-Access-Level: publicX-Passport-SHA256: bd4c49c7b04ac463…81146b938X-Passport-Signature: Tw0bRkvf+s3IS1MQ…MPZ7Dg==X-Passport-Key-Id: batterycompliance-2026-09-25Link: </schema/battery-passport/2.0.0>; rel="describedby" { "dppHeader": { "dppStatus": { "dppStatusValue": "active" }, … },  "identifiersAndProductData": { "batterySerialNumber": "SN0001", … }, … }
Los valores largos se abrevian. Con un token de acceso, la misma dirección devuelve los campos de su nivel de acceso y X-Passport-Access-Level lo indica.

Cómo funcionan las API

Autenticación

Las claves de API las crea el titular de la empresa en Empresa → Claves de API y se muestran una sola vez. Envíelas como Authorization: Bearer bcp_live_…. Ámbitos: items:read, items:write (también lee), items:publish, qr:read.

Los clientes OAuth 2.0 (client credentials) los crea el titular de la empresa para sus socios, o la plataforma para autoridades y terceros aprobados. Obtenga un token con POST /oauth/token (grant_type=client_credentials); es válido durante 15 minutos. Ámbitos: dpp:read, dpp:search, dpp:write.

Límites y errores

60 solicitudes por minuto por clave de API (encabezados X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) y 120 por minuto por cliente OAuth o, sin token, por dirección. Al superar el límite: HTTP 429 con Retry-After.

La API de gestión de pasaportes responde a los errores con un objeto error con code, message y details; la API del PDP responde con statusCode, payload y result con los códigos de estado de la norma EN 18222.

Las actualizaciones de la API del PDP aceptan un encabezado Idempotency-Key: la misma clave con la misma solicitud en 24 horas devuelve la primera respuesta y no crea una segunda versión.

Pasaportes públicos

Cada pasaporte tiene una dirección permanente (GS1 Digital Link /01/{GTIN}/21/{serial} o /id/{operator}/{model}/{serial}). Con Accept: application/json o ?format=json devuelve el JSON de la última versión para su nivel de acceso; con ?version=N, una versión determinada; con /versions, la lista.

Cada versión está firmada: X-Passport-SHA256 contiene el SHA-256 del JSON canónico RFC 8785 de la versión completa, X-Passport-Signature su firma Ed25519 sobre esa cadena hexadecimal y X-Passport-Key-Id la clave que la firmó. Las claves públicas y el esquema figuran en Descripciones legibles por máquina.

Webhooks

En lugar de consultar la API periódicamente, añada un punto de conexión en Empresa → Webhooks. Los eventos (passport.published, publish_job.finished, item.lifecycle_recorded, access_request.created, passport.transferred, label_template.issued, dossier.ready, import_batch.assigned, import_batch.confirmed, import_batch.rejected) se envían con POST como JSON con los encabezados X-Webhook-Id, X-Webhook-Timestamp y X-Webhook-Signature = v1= + HMAC-SHA256 hexadecimal de timestamp.body con su secreto. Responda 2xx en 10 segundos; las entregas fallidas se reintentan durante 24 horas.

Descripciones legibles por máquina

Obtenga una clave de API

Registre su empresa y cree una clave en Empresa → Claves de API. Las claves se muestran una sola vez y solo se almacenan como hash.

Empezar gratisHablar con nosotros