Programadores
Duas APIs
API de gestão de passaportes
/openapi.jsonPara a empresa que detém os passaportes: listar modelos e artigos (por cursor, com updatedSince para sincronização), criar artigos, intervalos e cópias de modelos, atualizar os dados dos artigos, publicar (um artigo ou em segundo plano) e obter códigos QR. Autenticada com uma chave de API.
Referência: API de gestão de passaportesAPI DPP (EN 18222)
/openapi-dpp.jsonAPI Life Cycle e Fine Granular conforme com a EN 18222: ler passaportes ao seu nível de acesso, pesquisar identificadores de passaportes por identificador de produto, registar eventos (reparação, estado de saúde, estado) com um token de acesso OAuth 2.0. Os dados públicos podem ser lidos sem token.
Referência: API DPP (EN 18222)
Ler um passaporte
Cada endereço de passaporte responde com JSON quando o pede – não é necessária chave para os dados públicos. Os cabeçalhos contêm a versão, o respetivo SHA-256 e a assinatura Ed25519, para poder verificar o que leu em relação às nossas chaves 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", … }, … }Como funcionam as APIs
Autenticação
As chaves de API são criadas pelo proprietário da empresa em Empresa → Chaves de API e mostradas uma só vez. Envie-as como Authorization: Bearer bcp_live_…. Âmbitos: items:read, items:write (também lê), items:publish, qr:read.
Os clientes OAuth 2.0 (client credentials) são criados pelo proprietário da empresa para os seus parceiros, ou pela plataforma para autoridades e terceiros aprovados. Obtenha um token com POST /oauth/token (grant_type=client_credentials); é válido durante 15 minutos. Âmbitos: dpp:read, dpp:search, dpp:write.
Limites e erros
60 pedidos por minuto por chave de API (cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) e 120 por minuto por cliente OAuth ou, sem token, por endereço. Acima do limite: HTTP 429 com Retry-After.
A API de gestão de passaportes responde aos erros com um objeto error com code, message e details; a API DPP responde com statusCode, payload e result com os códigos de estado da EN 18222.
As atualizações da API DPP aceitam um cabeçalho Idempotency-Key: a mesma chave com o mesmo pedido no prazo de 24 horas devolve a primeira resposta e não cria uma segunda versão.
Passaportes públicos
Cada passaporte tem um endereço permanente (GS1 Digital Link /01/{GTIN}/21/{serial} ou /id/{operator}/{model}/{serial}). Com Accept: application/json ou ?format=json devolve o JSON da versão mais recente para o seu nível de acesso; ?version=N uma versão determinada; /versions a lista.
Cada versão é assinada: X-Passport-SHA256 contém o SHA-256 do JSON canónico RFC 8785 da versão completa, X-Passport-Signature a respetiva assinatura Ed25519 sobre essa cadeia hexadecimal e X-Passport-Key-Id a chave que a assinou. As chaves públicas e o esquema constam das descrições legíveis por máquina.
Webhooks
Em vez de consultar repetidamente, adicione um ponto de extremidade em Empresa → Webhooks. Os 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 – são enviados por POST como JSON com os cabeçalhos X-Webhook-Id, X-Webhook-Timestamp e X-Webhook-Signature = v1= + HMAC-SHA256 hexadecimal de timestamp.body com o seu segredo. Responda 2xx no prazo de 10 segundos; as entregas falhadas são repetidas durante 24 horas.
Descrições legíveis por máquina
- Chaves públicas de assinatura (JWKS)/.well-known/batterycompliance-signing-key.json
- Esquema JSON do passaporte/schema/battery-passport/2.0.0
- OpenAPI 3.1 – API de gestão de passaportes/openapi.json
- OpenAPI 3.1 – API DPP/openapi-dpp.json
Obtenha uma chave de API
Registe a sua empresa e depois crie uma chave em Empresa → Chaves de API. As chaves são mostradas uma só vez e guardadas apenas como hash.