Guia de integração de API de eID: padrões, código e segurança

Última revisão: 5 de outubro de 2026 · Não constitui aconselhamento jurídico

Este guia, centrado em código, é para engenheiros que estão adicionando eIDs nacionais ao onboarding.

Como funciona uma API de eID: cinco padrões de interação

O seu sistema é a parte confiante (RP). Ele nunca vê a credencial em si, apenas uma resposta assinada sobre a pessoa.

Alguns esquemas ficam atrás de um gateway público: o TARA da Estônia é um gateway de código de autorização à frente do cartão de identidade, do Smart-ID, do Mobile-ID e das eIDs da UE.^[7] Veja esquemas de eID por país para saber qual padrão cada esquema usa.

O que você constrói e o que um provedor resolve

O acesso vem antes do código. Na Dinamarca, todo prestador de serviços precisa passar por um broker de MitID certificado.^[12] Na Suécia, você adquire o BankID de um banco ou de um revendedor e solicita um certificado de parte confiante.^[15] Na Alemanha, você opera seu próprio servidor de eID, usa um serviço de eID hospedado com seu próprio certificado ou usa um serviço de identificação sem ter nenhum certificado próprio.^[13] Para a EUDI Wallet, uma parte confiante precisa se registrar no Estado-Membro onde está estabelecida.^[1]

Existem brokers certificados para a maioria dos esquemas nórdicos e bálticos. Vá direto para um único esquema com alto volume; use uma API quando os usuários vierem de vários países.

O fluxo de redirecionamento, passo a passo

Este é o fluxo de código de autorização do OIDC. Seu backend redireciona o navegador com um state e um nonce aleatórios, depois troca o código retornado por um token de ID e o verifica.

Um login por redirecionamento. Brokers e gateways acrescentam saltos na etapa 2, não novas etapas para você.

A verificação após a etapa 5 é a mais importante. Segundo a documentação do ID-porten da Digdir, o cliente "DEVE validar que o nível de segurança (acr) é suficientemente alto".^[5] Interprete o acr como o nível de garantia (LoA) que o esquema declara e recuse qualquer valor abaixo da sua política.

O fluxo por notificação no app com código de comparação

Com Smart-ID e Mobile-ID, o usuário nunca sai da sua página. O usuário digita um código de identificação pessoal (o Mobile-ID também pede o número de telefone), sua página mostra um código curto e o mesmo código aparece no app. O usuário aprova com o PIN no celular somente quando os códigos coincidem.^[20] O Smart-ID também pode mostrar três códigos e pedir que o usuário escolha o correto.^[10]

O BankID Sweden segue o mesmo formato, com um QR no lugar de um código digitado. O usuário abre o app no mesmo dispositivo com um token de autostart ou escaneia um QR animado exibido no outro dispositivo. Seu backend consulta /collect até o pedido ser concluído. O pedido concluído traz o número pessoal, o nome, o prenome e o sobrenome, além de campos de dispositivo, de assinatura e campos opcionais de risco.^[8] O Smart-ID+ leva o Smart-ID para esse modelo (QR dinâmico no desktop, app-to-app no celular), e assim os usuários deixam de digitar um código pessoal em um site.^[11]

Um login com Smart-ID ou Mobile-ID, na ordem em que o usuário o vê: código pessoal, código de comparação na sua página, o mesmo código no app e, por fim, o PIN.^[20] Na variante com QR do BankID, a etapa 1 desaparece e a etapa 2 exibe um QR code.

Cartão e NFC, e a carteira europeia de identidade digital (EUDI Wallet) via OpenID4VP

Com a carteira de identidade eletrônica alemã, o usuário aproxima o cartão de um celular com NFC no AusweisApp. Antes de o PIN ser digitado, a lei exige que o app mostre o nome e o endereço do provedor e as categorias de dados solicitadas. Somente essas categorias são enviadas.^[14]

Segundo a OpenID Foundation, o OpenID4VP 1.0 é uma especificação final.^[16] O Architecture and Reference Framework (ARF) lista como formas de apresentação remota o OpenID4VP via redirecionamentos e esquemas de URI personalizados, como openid4vp://, o OpenID4VP via W3C Digital Credentials API ou a ISO/IEC 18013-7 via essa mesma API.^[2][17] Antes de compartilhar qualquer dado, a carteira autentica o seu certificado de acesso, verifica se você não pede mais atributos do que registrou e permite que o usuário aprove cada um deles.^[2] A foto só passa a ser obrigatória nos dados de identificação pessoal (PID) a partir de 11 de agosto de 2028, exceto quando o usuário recusa expressamente.^[18]

1. 23 de julho de 2026ARF v3.0.0Versão atual do framework da carteira.
2. 24 de dezembro de 2026Prazo das carteirasCada Estado-Membro oferece pelo menos uma carteira.
3. 24 de dezembro de 2027AceitaçãoPartes confiantes privadas obrigadas por lei ou contrato a usar autenticação forte do usuário passam a aceitá-la a pedido do usuário. Microempresas e pequenas empresas estão isentas.
4. 11 de agosto de 2028FotoA foto nos PID passa a ser obrigatória, salvo se o usuário recusar.

Datas da EUDI Wallet que definem o roadmap de uma API de eID.^[1][2][18]

O guia da EUDI Wallet trata do registro de partes confiantes e da prontidão por país.

Erros, alternativas e novas tentativas

Um login termina como concluído, cancelado, expirado ou com falha. Trate os três últimos casos da mesma forma e decida, por país, o que acontece em seguida.

Nunca repita automaticamente um login cancelado. Torne o callback idempotente, para que uma atualização da página ou um evento duplicado não abra duas contas. Mantenha uma rota para pessoas sem eID, geralmente um documento de identidade com leitura do chip por NFC, prova de vida (liveness) e correspondência facial. Verificação de eID por NFC e segurança do chip trata dessa rota.

Checklist de segurança para uma integração de API de eID

• Gere um state e um nonce novos a cada login e rejeite um callback que não corresponda a eles.
• Verifique a assinatura de cada token ou resultado antes de ler qualquer atributo.
• Confira o nível de garantia no resultado, não apenas na requisição.^[5]
• Exija nível substancial ou elevado quando a rota de eID do AMLR se aplicar a você.^[3]
• Nunca colete o PIN do eID na sua página; ele pertence ao app do esquema.^[20]
• Prefira QR code ou abertura app-to-app a códigos digitados em logins entre dispositivos.^[11]
• Solicite apenas os atributos que você registrou e de que precisa.^[1]
• Verifique as assinaturas e os carimbos de data/hora dos webhooks antes de confiar em um resultado.

A base legal é o Regulamento Antilavagem de Dinheiro (AMLR), aplicável a partir de 10 de julho de 2027: o Artigo 22(6)(b) admite "meios de identificação eletrônica que cumpram os requisitos do Regulamento (UE) n.º 910/2014 no que diz respeito aos níveis de garantia 'substancial' ou 'elevado'".^[3] Nem todo esquema é notificado: o MitID consta da lista da UE de esquemas notificados, o Smart-ID não.^[4]

Como a Didit ajuda na integração de API de eID

A Didit reúne cinco eIDs em produção em uma única API de sessão (MitID, BankID Sweden, Finnish Trust Network, Smart-ID e Mobile-ID, em sete países), com uma rota por documento no mesmo fluxo. Outros esquemas estão no roadmap da Didit, e a aceitação da carteira europeia de identidade digital (EUDI Wallet) chega em breve. A Didit nunca pede o PIN. Saiba mais na página de carteiras de identidade digital e na documentação de carteiras.^[19]

Ative por país os eIDs em produção

No console: Workflows, a etapa ID Verification, Countries, "Wallets accepted". Pela API, o recurso ID Verification (OCR) recebe um objeto methods indexado pelo código de país ISO 3166-1 alpha-3, enviado com POST /v3/workflows/. O trecho documentado para a Dinamarca:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

E para a Estônia, aceitando os dois eIDs baseados em celular:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers é uma lista de aceitação, não um ranking. on_failure é fallback_to_document ou decline. Uma carteira que não está disponível no seu ambiente faz com que todo o salvamento seja rejeitado, então consulte o catálogo antes.^[21]

Crie uma sessão e leia o resultado

POST /v3/session/ com o seu workflow_id (e, opcionalmente, vendor_data e um callback) retorna session_id, url e session_token. Abra a URL ou use o SDK.^[24] O resultado chega por webhook ou por GET /v3/session/{id}/decision/, com verification_method: "wallet", assurance: "cryptographic" e um objeto wallet_verification.^[19]

Um nível inferior ao solicitado faz o login falhar. Só são cobrados os logins concluídos.^[19] Preços: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks e sandbox

Verifique o X-Signature-V2 com o segredo do seu destino, rejeite um X-Timestamp com mais de 300 segundos e use o event_id como chave de idempotência. Uma entrega com falha é reenviada até duas vezes.^[22] Uma aplicação de sandbox pode ativar todas as carteiras, aprova sem um login real e oferece wallet_cancelled, wallet_timeout e wallet_provider_error para testar o seu fallback.^[23]

Perguntas frequentes

Fontes

1. Regulamento (UE) 2024/1183 (eIDAS 2), EUR-Lex, Jornal Oficial de 30 de abril de 2024, artigos 5a, 5b e 5f.
2. Architecture and Reference Framework v3.0.0, projeto EUDI Wallet da Comissão Europeia, publicado em 23 de julho de 2026, seções 4.4.3, 5.7.1 e 6.6.3.
3. Regulamento (UE) 2024/1624 (AMLR), EUR-Lex, artigo 22(6).
4. Panorama dos esquemas de eID pré-notificados e notificados no âmbito do eIDAS, Comissão Europeia, consultado em 5 de outubro de 2026.
5. ID token do ID-porten, Agência Norueguesa de Digitalização (Digdir).
6. Anbindung mit OpenID Connect, documentação para desenvolvedores do ID Austria.
7. Especificação técnica do TARA, Autoridade do Sistema de Informação da Estônia (RIA).
8. Auth and sign: collect, documentação para desenvolvedores do BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 de julho de 2019 (fonte secundária).
10. Por que às vezes vejo um código de confirmação e às vezes três, Smart-ID.
11. Como o novo Smart-ID me protege contra fraudes, Smart-ID.
12. Brokers do MitID, Agência Dinamarquesa para o Governo Digital.
13. Torne-se um provedor de serviços, AusweisApp, governo federal alemão.
14. Seção 18 da Lei do Passaporte e da Carteira de Identidade (PAuswG), Gesetze im Internet.
15. Conecte sua empresa ao BankID, BankID.
16. Especificação final do OpenID for Verifiable Presentations 1.0 aprovada, OpenID Foundation.
17. Digital Credentials, W3C.
18. Regulamento de Execução (UE) 2026/1731 da Comissão, EUR-Lex, retrato no PID a partir de 11 de agosto de 2028.
19. Carteiras de identidade digital, documentação da Didit.
20. Integração com Smart-ID e Mobile-ID, documentação da Didit.
21. Configurações de recursos do fluxo de trabalho, documentação da Didit.
22. Webhooks, documentação da Didit.
23. Sandbox e dados de teste, documentação da Didit.
24. Início rápido, documentação da Didit.

Veja cada eID nacional, seu nível e seu status na página de verificação por eID.