Como integrar uma API de eID: normas, código e boas práticas de segurança

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

Este guia centrado em código destina-se a engenheiros que estão a integrar eID nacionais no processo de onboarding.

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

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

Alguns sistemas estão por trás de um gateway público: o TARA da Estónia é um gateway de código de autorização à frente do cartão de identificação, do Smart-ID, do Mobile-ID e das eID da UE.^[7] Consulte sistemas de eID por país para saber que padrão cada sistema utiliza.

O que desenvolve e o que um fornecedor assegura

O acesso vem antes do código. Na Dinamarca, todos os prestadores de serviços têm de passar por um intermediário MitID certificado.^[12] Na Suécia, compra o BankID a um banco ou a um revendedor e encomenda um certificado de parte utilizadora.^[15] Na Alemanha, opera o seu próprio servidor eID, utiliza um serviço eID alojado com o seu próprio certificado ou utiliza um serviço de identificação e não detém qualquer certificado.^[13] Para a EUDI Wallet, uma parte utilizadora tem de se registar no Estado-Membro onde está estabelecida.^[1]

Existem intermediários certificados para a maioria dos sistemas nórdicos e bálticos. Opte pela ligação direta para um único sistema com volume elevado; utilize uma única API quando os utilizadores vêm de vários países.

O fluxo de redirecionamento, passo a passo

Este é o fluxo de código de autorização OIDC. O seu backend reencaminha o navegador com um state e um nonce aleatórios. Depois, troca o código devolvido por um token de ID e verifica-o.

Um início de sessão por redirecionamento. Intermediários e gateways acrescentam saltos no passo 2, não passos novos para si.

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

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

O Smart-ID e o Mobile-ID nunca saem da sua página. O utilizador introduz um código de identificação pessoal (o Mobile-ID pede também o número de telefone). A sua página mostra um código curto e o mesmo código aparece na app. O utilizador aprova com o PIN no telemóvel apenas quando os códigos coincidem.^[20] O Smart-ID pode também mostrar três códigos e pedir ao utilizador que escolha o correto.^[10]

O BankID Sweden segue o mesmo modelo, com um QR em vez de um código digitado: o utilizador abre a aplicação no mesmo dispositivo com um token de arranque automático, ou lê um QR animado apresentado no outro dispositivo, e o seu backend consulta /collect até a ordem ficar concluída. A ordem concluída contém o número pessoal, o nome, o nome próprio e o apelido, bem como campos de dispositivo e de assinatura e campos de risco opcionais.^[8] O Smart-ID+ passa o Smart-ID para este modelo (QR dinâmico no computador, app-to-app no telemóvel), pelo que os utilizadores deixam de digitar um código pessoal num site.^[11]

Um início de sessão com Smart-ID ou Mobile-ID, pela ordem em que o utilizador o vê: código pessoal, código de comparação na sua página, o mesmo código na aplicação e, por fim, o PIN.^[20] Na variante QR do BankID, o passo 1 desaparece e o passo 2 mostra um código QR.

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

Com o cartão eID alemão, o utilizador aproxima o cartão de um telemóvel com NFC na AusweisApp. Antes de o PIN ser introduzido, a lei exige que a aplicação mostre o nome e a morada do prestador e as categorias de dados pedidas, e só 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) enumera como formas de apresentação remota o OpenID4VP através de redirecionamentos e de esquemas de URI personalizados, como openid4vp://, o OpenID4VP através da W3C Digital Credentials API, ou a ISO/IEC 18013-7 através dessa API.^[2][17] Antes de partilhar o que quer que seja, a carteira autentica o seu certificado de acesso, verifica que não pede mais atributos do que os que registou e permite ao utilizador aprovar cada um deles.^[2] O retrato só passa a ser obrigatório nos dados de identificação pessoal (PID) a partir de 11 de agosto de 2028, exceto quando o utilizador opte expressamente por não o incluir.^[18]

1. 23 de julho de 2026ARF v3.0.0Versão atual do quadro da carteira.
2. 24 de dezembro de 2026Prazo das carteirasCada Estado-Membro disponibiliza pelo menos uma carteira.
3. 24 de dezembro de 2027AceitaçãoAs partes utilizadoras privadas obrigadas por lei ou por contrato a utilizar autenticação forte do utilizador aceitam-na a pedido do utilizador. As micro e pequenas empresas estão isentas.
4. 11 de agosto de 2028RetratoO retrato do PID passa a ser obrigatório, salvo se o utilizador optar por não o incluir.

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

O guia da EUDI Wallet aborda o registo das partes utilizadoras e o grau de preparação por país.

Erros, alternativas e novas tentativas

Um início de sessão termina como concluído, cancelado, expirado ou falhado. Trate os três últimos da mesma forma e decida, por país, o que acontece a seguir.

Nunca repita automaticamente um início de sessão cancelado. Torne o callback idempotente, para que uma atualização da página ou um evento duplicado não possa abrir duas contas. Mantenha uma via para pessoas sem eID, normalmente um documento de identificação com leitura do chip por NFC, deteção de vivacidade e correspondência facial. O artigo verificação de eID por NFC e segurança do chip trata dessa via.

Lista de verificação de segurança para uma integração de API de eID

• Gere um state e um nonce novos em cada início de sessão e rejeite um callback que não lhes corresponda.
• Verifique a assinatura de cada token ou resultado antes de ler qualquer atributo.
• Verifique o nível de garantia no resultado, e não apenas no pedido.^[5]
• Exija nível substancial ou elevado quando a via de eID do AMLR se aplicar a si.^[3]
• Nunca recolha o PIN do eID na sua página. Esse PIN pertence à aplicação do esquema.^[20]
• Prefira o código QR ou a abertura de aplicação para aplicação em vez de códigos digitados nos inícios de sessão entre dispositivos.^[11]
• Peça apenas os atributos que registou e de que precisa.^[1]
• Verifique as assinaturas e os carimbos temporais dos webhooks antes de confiar num resultado.

A base jurídica é o Regulamento Antibranqueamento de Capitais (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 respeita aos níveis de garantia "substancial" ou "elevado"».^[3] Nem todos os esquemas estão notificados: 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 disponíveis numa única API de sessões (MitID, BankID Sweden, Finnish Trust Network, Smart-ID e Mobile-ID, em sete países), com uma via por documento no mesmo fluxo de trabalho. Há mais esquemas no roteiro da Didit, e a aceitação da carteira europeia de identidade digital (EUDI Wallet) chega brevemente. A Didit nunca pede o PIN. Mais informação na página de carteiras de identidade digital e na documentação das carteiras.^[19]

Ativar eIDs disponíveis por país

Na consola: Workflows, o passo ID Verification, Countries, «Wallets accepted». Através da API, a funcionalidade 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 fragmento 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 no telemóvel:^[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 uma ordem de prioridade. on_failure assume o valor fallback_to_document ou decline. Uma carteira que não esteja disponível no seu ambiente faz rejeitar toda a gravação, por isso consulte primeiro o catálogo.^[21]

Criar uma sessão e ler o resultado

POST /v3/session/ com o seu workflow_id (e, opcionalmente, vendor_data e um callback) devolve session_id, url e session_token. Abra o URL ou utilize 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 pedido faz falhar o início de sessão. Só são faturados os inícios de sessão concluídos.^[19] Preços: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhooks e sandbox

Verifique X-Signature-V2 com o segredo do seu destino, rejeite um X-Timestamp com mais de 300 segundos e baseie a idempotência em event_id. Uma entrega falhada é repetida até duas vezes.^[22] Uma aplicação sandbox pode ativar todas as carteiras, aprova sem uma autenticação real e disponibiliza wallet_cancelled, wallet_timeout e wallet_provider_error para testar a sua alternativa.^[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, secções 4.4.3, 5.7.1 e 6.6.3.
3. Regulamento (UE) 2024/1624 (AMLR), EUR-Lex, Artigo 22(6).
4. Overview of pre-notified and notified eID schemes under eIDAS, Comissão Europeia, consultado em 5 de outubro de 2026.
5. ID-porten ID token, Agência Norueguesa de Digitalização (Digdir).
6. Anbindung mit OpenID Connect, documentação para programadores do ID Austria.
7. TARA technical specification, Autoridade dos Sistemas de Informação da Estónia (RIA).
8. Auth and sign: collect, documentação para programadores 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. Why do I sometimes see one confirmation code and sometimes three, Smart-ID.
11. How does the new Smart-ID protect me from fraud, Smart-ID.
12. MitID brokers, Agência Dinamarquesa para o Governo Digital.
13. Become a service provider, AusweisApp, Governo federal alemão.
14. Secção 18 da Lei dos Passaportes e Bilhetes de Identidade (PAuswG), Gesetze im Internet.
15. Connect your business to BankID, BankID.
16. OpenID for Verifiable Presentations 1.0 final specification approved, OpenID Foundation.
17. Digital Credentials, W3C.
18. Regulamento de Execução (UE) 2026/1731 da Comissão, EUR-Lex, retrato nos PID a partir de 11 de agosto de 2028.
19. Carteiras de identidade digital, documentação da Didit.
20. Integração de Smart-ID e Mobile-ID, documentação da Didit.
21. Configurações de funcionalidades 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.

Consulte cada eID nacional, o seu nível e o seu estado na página de verificação de eID.