API do registro DPP: como registrar passaportes de bateria na UE, passo a passo

TL;DR

• Em 30 de outubro de 2026, a Comissão Europeia publicou as especificações técnicas da API do registro DPP: um guia de integração, arquivos OpenAPI, guias de autenticação para contas de serviço e para passaportes auto-hospedados, e os modelos de dados semânticos para baterias.
• O registro é assíncrono e do tipo tudo ou nada: você envia até 100 passaportes por submissão, o registro busca e valida cada passaporte a partir do seu endereço web e, se um item falhar, nenhum é registrado.
• As baterias são o único grupo de produtos definido até agora. Baterias de veículos elétricos, LMT e industriais acima de 2 kWh precisam de um passaporte registrado a partir de 18 de fevereiro de 2027, e a sua organização precisa ser verificada com um selo eletrônico qualificado antes que qualquer chamada à API funcione.

A API do registro DPP é a forma como um fabricante, um importador ou a plataforma que trabalha para eles registra Passaportes Digitais de Produtos na UE sem preencher um formulário web, um produto de cada vez. O registro em si está em operação desde 20 de julho de 2026. O que chegou em 30 de outubro é o detalhe de que um desenvolvedor precisa para construir sobre ele: endpoints, autenticação, códigos de erro, regras de polling e os modelos de dados contra os quais o registro valida os passaportes.

Este guia é para a pessoa que precisa fazer os passaportes de bateria aparecerem no registro até fevereiro. Ele segue os documentos na ordem em que você vai encontrá-los e separa o que está decidido do que ainda está em aberto. Para saber o que é o registro e por que ele existe, veja nosso guia explicativo sobre o registro de DPP da UE. Tudo o que segue está descrito conforme a situação em novembro de 2026.

O que a Comissão publicou em 30 de outubro?

Seis documentos técnicos apareceram na página de recursos sobre o DPP da Comissão, sem nenhuma notícia para anunciá-los. Eles se somam ao Guia do Usuário para Operadores Econômicos de setembro de 2026.

Em 19 de outubro, a Comissão também publicou a versão 3.2 da sua orientação sobre o passaporte de bateria, que lista os pontos de dados por categoria de bateria. Tratamos dela mais abaixo.

A parte vinculativa é o Regulamento de Execução (UE) 2026/1778, de 16 de julho de 2026. O artigo 3, alínea b, prevê uma API para o registro, o artigo 8, parágrafo 6, permite o registro por meio da interface de usuário ou da API, e o artigo 8, parágrafo 7, exige verificações automáticas de semântica e de granularidade. As especificações são a forma como a Comissão implementa esses artigos.

O que o registro faz com o seu passaporte?

O registro é um índice, não um repositório. Você envia a ele um identificador único do produto (UPI) para cada passaporte, e a API exige que esse UPI seja uma URL HTTPS. No momento da submissão, o registro vai até essa URL, busca o passaporte e o valida contra o modelo de dados do grupo de produtos. Nas palavras do guia de integração, o registro «não persiste o conteúdo do payload do DPP obtido».

Essa única escolha de desenho determina a maior parte do trabalho de engenharia. O passaporte precisa estar online, completo e válido no momento em que você faz a submissão, não depois. Se o registro não conseguir acessá-lo, o item falha com UPI_NOT_RESOLVABLE. Se o conteúdo não corresponder ao schema, ele falha como ITEM_NON_COMPLIANT. Um fluxo que registra primeiro e publica o passaporte depois não vai funcionar.

Quando o registro é bem-sucedido, o artigo 9 do Regulamento de Execução lhe dá um comprovante de registro selado com o selo eletrônico qualificado da Comissão, disponível por 90 dias. Baixe-o e arquive-o; ele é a sua prova de que o passaporte foi registrado e de quando isso ocorreu.

O que precisa estar pronto antes da primeira chamada à API?

Mais do que a maioria das equipes espera, e quase nada disso é código.

Uma organização verificada. Os usuários fazem login com o EU Login, mas a API rejeita com um 403 as requisições de uma organização que não esteja verificada. Nos termos do artigo 4 do Regulamento de Execução, uma pessoa jurídica comprova a sua identidade e o seu estabelecimento com um selo eletrônico qualificado (ou uma declaração eletrônica de atributos); um empresário individual pode usar uma assinatura eletrônica qualificada ou uma eID com nível de garantia eIDAS «elevado». Na prática, o registro lhe fornece uma declaração selada pela Comissão, e você a assina ou a sela. O status de verificado dura até que os seus meios de identificação expirem, e no máximo três anos, depois dos quais você precisa se verificar novamente.

Um selo qualificado é emitido por um prestador qualificado de serviços de confiança, com as suas próprias verificações de identidade. Se a sua empresa não tiver um, comece por aqui.

Um administrador e uma conta de serviço. O administrador da sua organização cria as contas de serviço na interface do registro. Uma conta de serviço é uma identidade não humana vinculada à sua organização verificada, e ela precisa da função que permite registrar DPPs. A organização é obtida a partir do token de acesso, então você nunca envia um ID de organização na requisição.

Classificação do produto. Cada submissão indica um grupo e um subgrupo de produtos, que você obtém de GET /api/v1/dpp/product-groups em vez de fixá-los no código. Hoje essa chamada retorna um único grupo, BATTERIES, com os subgrupos EV, LMT e industrial.

Como uma conta de serviço se autentica?

O registro usa OAuth 2.0 client credentials com private_key_jwt. O guia é direto: «Segredos de cliente compartilhados não são suportados.» O seu sistema guarda uma chave privada, assina uma asserção de curta duração e a troca por um token de acesso.

Os detalhes que vão pegar muita gente de surpresa:

• Somente chaves de curva elíptica (ES256, ES384 ou ES512). Chaves RSA não são aceitas. Você envia a chave pública como JWK ou PEM, e o guia recomenda manter a chave privada em um módulo de segurança de hardware (HSM).
• Asserções curtas. A asserção do cliente deve expirar em 60 a 120 segundos, nunca em mais de 5 minutos, com um jti novo a cada vez.
• Um indicador de recurso. A requisição de token deve indicar o registro como recurso, usando o valor publicado para cada ambiente.
• Tokens curtos. Os tokens de acesso duram no máximo 15 minutos, então o seu cliente precisa renová-los durante execuções longas de lotes.
• Limites. Até 5 contas de serviço por organização e 2 credenciais ativas por conta, o que torna possível a rotação de chaves sem interrupção. A recomendação é que as credenciais durem um ano, no máximo dois.

Se uma plataforma registra passaportes por você, o modelo que os documentos da versão 1.0 descrevem é uma conta de serviço dentro da sua organização verificada. É assim que a integração funciona hoje, mas não é a única via que a lei permite. O Regulamento de Execução também prevê terceiros verificados que atuam em nome de um operador: o artigo 6, parágrafo 1, permite que operadores verificados deleguem direitos de acesso a terceiros quando o direito da União assim o prevê, o artigo 8, parágrafo 2, permite que um terceiro verificado realize ações de registro nesse caso, e o artigo 19, parágrafo 4, exige que um terceiro autorizado por um operador passe pela sua própria verificação. O registro também manterá uma lista de prestadores de serviços de DPP verificados (artigo 3, alínea f). Como essa delegação vai funcionar tecnicamente ainda não está descrito nos guias de integração. Qualquer que seja a via utilizada, o operador econômico continua sendo integralmente responsável pela conformidade.

Como funciona uma submissão de registro?

O fluxo tem quatro chamadas. Você obtém os grupos de produtos, faz a submissão e depois acompanha a tarefa pelo que a Comissão chama de 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"
    }
  ]
}

Esse corpo segue o exemplo oficial. uniqueProductIdentifier e granularity (item, lote ou modelo) são obrigatórios para cada item; os identificadores de lote e de modelo são opcionais.

O registro responde 202 Accepted com um taskId. Um 202 significa apenas que a requisição foi aceita para processamento. Em seguida você faz polling de GET /api/v1/tasks/{taskId} e, quando precisar saber quais itens passaram, de GET /api/v1/tasks/{taskId}/items, que retorna JSON ou CSV.

Dois campos de status importam, e eles significam coisas diferentes. O status da tarefa passa por PENDING, PROCESSING, COMPLETED ou ERROR. Depois de concluída, outcomeResult indica SUCCEEDED ou FAILED. Uma tarefa pode estar COMPLETED com resultado FAILED: o processamento funcionou, e os seus dados não passaram. ERROR é uma falha técnica do lado do registro.

Não há webhooks. O guia recomenda fazer polling aos 1, 1, 2, 3, 5, 8, 13, 21, 34 e 55 segundos e, depois, no máximo a cada 60 segundos, e um cabeçalho Retry-After sempre prevalece sobre o seu próprio cronograma.

A regra que deve moldar o desenho dos seus lotes é a atomicidade. Uma submissão contém de 1 a 100 passaportes do mesmo grupo e subgrupo de produtos e, se qualquer um deles não estiver conforme, nenhum é registrado, incluindo os que passaram. Um único item ruim em um lote de 100 segura 99 bons. Nós validaríamos cada passaporte localmente contra os schemas publicados antes da submissão, manteríamos os lotes menores enquanto os seus dados ainda estão se estabilizando e reenviaríamos rapidamente os itens corretos após uma falha.

O cabeçalho Idempotency-Key é obrigatório, com até 128 caracteres. Repetir a requisição com a mesma chave retorna a tarefa original em vez de criar uma duplicata, que é o que você quer após um timeout ou um 500. Uma submissão alterada precisa de uma chave nova; reutilizar uma chave para um conteúdo diferente retorna um 409.

Os códigos de erro são os convencionais (400, 403, 409, 413, 422, 429, 500), e o guia indica para cada um se você deve repetir com a mesma chave ou com uma nova. Um 403 geralmente significa que a organização não está verificada ou que a conta de serviço não tem a função de registro.

O que muda se você hospedar os passaportes por conta própria?

Os passaportes de bateria contêm dados públicos e restritos, e o registro lê ambos quando faz a validação. Se o passaporte estiver no seu próprio servidor, esse servidor precisa reconhecer o registro e mostrar a ele mais do que mostra ao público.

O seu host de passaportes atua como um resource server OAuth 2.0. O registro primeiro solicita o UPI sem credenciais e espera receber o passaporte público. Em seguida, solicita a mesma URL com um bearer token emitido pelo serviço de autenticação da Comissão e espera receber os dados públicos mais os restritos. O token é curto (ES384, no máximo 120 segundos), traz o scope dpp:registry:read e é endereçado à origem HTTPS do seu host. Você o valida apenas contra as chaves do JWKS publicado pela Comissão, nunca contra chaves referenciadas de dentro do próprio token.

As regras de resposta são rígidas. Sem token: retorne o passaporte público. Token válido e solicitante autorizado: retorne os dados públicos mais os restritos. Um token presente, mas inválido: retorne 401, sem recorrer à visão pública. Token válido com scope ou solicitante errado: 403. Envie Vary: Authorization para que os caches mantenham as duas versões separadas, e use TLS 1.2 ou superior. JSON é o formato de resposta básico; JSON-LD e XML também são aceitos.

O guia descreve apenas um chamador, o próprio registro. Ele não aborda como as autoridades, os recicladores ou outras partes com interesse legítimo vão se autenticar, então você precisará de uma resposta separada para eles; nosso guia sobre direitos de acesso ao Passaporte Digital de Produto explica quem tem direito a quê. Os identificadores únicos de operador também ainda não são processados; o guia os prevê para uma versão futura.

Onde o GS1 Digital Link se encaixa

O registro segue redirecionamentos, no máximo três em toda a resolução, e resolve o UPI e cada redirecionamento sem credenciais, então cada etapa precisa ser acessível publicamente. Isso é compatível com um resolvedor. Uma URI GS1 Digital Link no seu próprio domínio, como https://id.yourbrand.com/01/09520123456788/21/SN0001, é uma forma de dar a cada bateria um identificador HTTPS persistente que leva ao seu passaporte e que também funciona como o QR code no produto. Não é obrigatório; qualquer URL HTTPS estável atende à regra de formato da API. Se você usa um resolvedor, conte os saltos: uma cadeia do domínio do QR ao resolvedor, ao provedor de hospedagem e à URL final já usa os três. O guia também recomenda evitar redirecionamentos após a autenticação, para que a requisição autorizada chegue diretamente ao passaporte.

Contra quais modelos de dados o registro valida?

O ZIP de Semantic Data Artifacts contém os modelos que o registro verifica. Hoje existem apenas dois: um modelo core e um modelo de baterias, ambos 1.0.0, com schemas de subgrupo para baterias EV, LMT e industriais. Cada um vem como JSON Schema (draft 2020-12), contextos JSON-LD, shapes SHACL e vocabulários SKOS, além de um catálogo DCAT-AP. O guia também descreve XSD, que não está incluído nesta versão.

Os schemas são divididos por nível de acesso: uma visão pública (pub) e três visões restritas (res1, res2, res3). O seu passaporte precisa apresentar os campos certos ao solicitante certo, e o schema indica onde fica cada campo. O ZIP também inclui instâncias de exemplo conformes a cada schema, que servem como um bom primeiro conjunto de dados de teste.

São descritas quatro serializações (JSON, JSON-LD, XML e RDF), mas JSON é a única obrigatória para o registro, em linha com a EN 18216:2026. O guia também cita a EN 18223:2026 sobre interoperabilidade. Explicamos as duas normas no guia sobre as normas CEN para o DPP, e por que os dados estruturados importam no nosso guia sobre o Passaporte Digital de Produto legível por máquina. O artigo 12 do Regulamento de Execução acrescenta que o repositório semântico é de uso gratuito e tem APIs públicas.

O que a orientação sobre baterias v3.2 acrescenta?

O Guidance Document: Digital Batteries Passport, data points by category, versão 3.2 de 19 de outubro de 2026, lista 71 pontos de dados para baterias EV, LMT e industriais. É uma orientação e afirma ela mesma que não é juridicamente vinculativa; as obrigações vêm do Regulamento das Baterias (UE) 2023/1542.

Para cada ponto de dados e categoria de bateria, ela indica um status: obrigatório; opcional, a preencher se o dado estiver disponível; se aplicável; apenas para certos tipos de bateria; ou a não preencher nem exibir em fevereiro de 2027. Esse último status é o mais útil para o planejamento. A declaração e o rótulo de pegada de carbono, por exemplo, estão marcados como a não preencher em fevereiro de 2027 porque o seu formato ainda aguarda um ato de execução, e as instruções de uso estão suspensas à espera do Omnibus. Cada ponto de dados também tem um nível de acesso: público, restrito a pessoas com interesse legítimo, organismos notificados, autoridades dos Estados-Membros e a Comissão, ou níveis restritos mais limitados. Esses níveis são o que as visões pub e res dos schemas implementam.

Nosso guia sobre o passaporte de bateria cobre os requisitos legais. Para o trabalho de integração, use a v3.2 como planilha de mapeamento entre os seus dados de produto e os campos do schema.

O que está decidido e o que ainda está em aberto?

Decidido: os endpoints, o modelo de autenticação, a regra de lote atômico, o polling, o modelo de dados de baterias e a exigência de que os passaportes estejam online no momento da submissão. A verificação por selo qualificado consta do próprio Regulamento de Execução.

Ainda em aberto em novembro de 2026: como vai funcionar tecnicamente o registro por terceiros verificados em nome de um operador, os modelos de dados para qualquer coisa que não sejam baterias, o formato da pegada de carbono, como outras partes se autenticam em passaportes auto-hospedados e os identificadores únicos de operador. O Regulamento de Execução também abrange produtos de construção, brinquedos e detergentes, que ainda não têm modelo de dados; para produtos que não sejam baterias, as obrigações começam pelo menos 18 meses após cada ato delegado. Os Estados-Membros devem designar os seus administradores nacionais do registro até 18 de fevereiro de 2027 (artigo 7).

Arestas da versão 1.0 dos documentos

Uma primeira versão sempre tem inconsistências, e vale conhecer estas antes de escrever código:

• O guia de Service Account indica a base da API como reg.product-passport.ec.europa.eu, enquanto os arquivos OpenAPI usam registry.product-passport.ec.europa.eu (e registry.acc.product-passport.ec.europa.eu para o ambiente de aceitação). Confirme o valor atual no registro antes de configurar a produção.
• O limite de 100 itens consta do guia, mas não é imposto no schema OpenAPI, então um cliente gerado a partir do schema vai montar sem problemas uma requisição de 101 itens.
• O guia de integração diz que os erros retornam o identificador como traceId, enquanto o schema de erro do OpenAPI o chama de correlationId. Registre ambos nos logs.
• A API usa o código de subgrupo EV, enquanto os artefatos semânticos usam evb nos seus caminhos. Mapeie-os explicitamente.

Nada disso impede a integração, mas verifique esses pontos de novo a cada nova versão dos documentos.

O que fazer agora

1. Obtenha um selo eletrônico qualificado junto a um prestador qualificado de serviços de confiança, se a sua empresa ainda não tiver um, e verifique a sua organização no registro. Este é o item com o prazo de obtenção mais longo de toda a lista.
2. Inscreva-se no ambiente de aceitação e designe um administrador que possa criar contas de serviço.
3. Decida onde os passaportes vão ficar: no seu próprio servidor, que então terá de implementar as regras de autenticação para passaportes auto-hospedados, ou com um provedor que já faça isso.
4. Defina os seus UPIs. Escolha um padrão de URL HTTPS estável para cada bateria, decida a granularidade por item, lote ou modelo e conte os redirecionamentos na cadeia.
5. Mapeie os seus dados para a v3.2 e para os schemas de baterias, campo a campo, incluindo as visões pública e restritas. Marque o que não é exigido em fevereiro de 2027 para que ninguém perca tempo com isso.
6. Valide localmente antes da submissão, contra os JSON Schemas publicados, e desenhe os lotes de modo que um item ruim não segure os demais.
7. Construa o cliente da forma certa: chaves EC em um HSM, renovação de tokens, chaves de idempotência que você consiga reproduzir, polling em sequência de Fibonacci e armazenamento de cada comprovante de registro.
8. Faça um teste completo no ambiente de aceitação bem antes de 18 de fevereiro de 2027, incluindo um lote com falha e uma rotação de chaves.

A Digital Link é parceira de soluções da GS1, e a nossa plataforma constrói passaportes de bateria e de produto sobre um identificador GS1 Digital Link persistente por produto, com os dados públicos e restritos servidos a partir do mesmo cadastro. Estamos preparando nossa própria integração com o registro. Isso envolve três etapas distintas: obter nosso selo eletrônico qualificado, concluir nossa verificação no registro e desenvolver e testar a conexão via API. Ainda não estamos conectados ao registro. Se você quer planejar a sua integração com o registro, ou verificar se os dados dos seus passaportes vão passar na validação, entre em contato e a nossa equipe vai analisar o seu caso.

Perguntas frequentes

A API do registro DPP é obrigatória?

Não. O artigo 8, parágrafo 6, do Regulamento de Execução (UE) 2026/1778 permite o registro por meio da interface de usuário ou da API. Na prática, quem registra mais do que um punhado de passaportes vai preferir a API.

O registro armazena os dados do meu passaporte?

Não. Ele busca o passaporte a partir da sua URL no momento da submissão para validá-lo, e o guia de integração afirma que não persiste o conteúdo obtido. O passaporte permanece onde você o hospeda, e é por isso que ele precisa estar acessível no momento da submissão.

Posso usar uma chave RSA ou um client secret na minha conta de serviço?

Não. As contas de serviço se autenticam com private_key_jwt usando chaves de curva elíptica (ES256, ES384 ou ES512). Segredos de cliente compartilhados e chaves RSA não são suportados.

O que acontece se um passaporte de um lote falhar na validação?

A submissão inteira falha e nenhum dos seus passaportes é registrado. A tarefa é concluída com o resultado FAILED, e os resultados por item mostram quais itens causaram a falha. Corrija-os e reenvie com uma nova chave de idempotência.

Preciso do GS1 Digital Link para registrar um passaporte?

Não. O identificador único do produto deve ser uma URL HTTPS que resolva para o passaporte. Uma URI GS1 Digital Link no seu próprio domínio é uma forma de atender a isso e serve também como o QR code do produto, mas qualquer URL HTTPS estável é aceita.

Quando os passaportes de bateria precisam ser registrados?

Para baterias de veículos elétricos, baterias LMT e baterias industriais acima de 2 kWh, a obrigação do passaporte de bateria nos termos do Regulamento (UE) 2023/1542 se aplica a partir de 18 de fevereiro de 2027. O registro e o seu ambiente de aceitação já estão abertos, então há tempo para testar antes.