API Smart-ID: guia para programadores da RP API v3

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

Este é o guia técnico, centrado no código, da Smart-ID API: endpoints, sessões, verificações da resposta, testes em ambiente de demonstração e enquadramento jurídico. Para contratos e regras de prevenção do branqueamento de capitais por país, leia o nosso guia de integração do Smart-ID.

Smart-ID em resumo

O Smart-ID é uma aplicação móvel da SK ID Solutions AS. Através da Relying Party API da SK, um serviço utiliza-a para autenticar um utilizador ou recolher uma assinatura.^[13] Parte de cada chave fica no servidor da SK, que a Autoridade do Sistema de Informação da Estónia (RIA) designa por "serviço de servidor de gestão de chaves Smart-ID".^[4]

Adoção: utilizadores e transações

A Lituânia é o maior mercado do Smart-ID, com 1,857,471 utilizadores, seguida da Letónia, com 1,198,463, e da Estónia, com 797,395, segundo o contador em tempo real de smart-id.com em 5 de outubro de 2026.^[1] A SK indica "quase 100 milhões de transações por mês".^[2]

Na Estónia, o Smart-ID tem "uma quota de mercado de quase 60 por cento" das autenticações, segundo a ERR News. O contador apresenta apenas totais; nenhuma fonte primária indica a quota do Smart-ID entre os adultos de cada país (5 de outubro de 2026).

O que o utilizador vê

A RP API v3 chega à aplicação de três formas: um código QR dinâmico entre dispositivos, uma ligação Web2App ou App2App no mesmo telemóvel, ou uma notificação push.^[12] A SK comercializa a experiência por QR e de aplicação para aplicação como Smart-ID+, que "já não depende da introdução do seu código pessoal de identificação num sítio web".^[8]

Como funciona a API v3 do Smart-ID

A API é REST sobre HTTPS com JSON em UTF-8.^[19] Quatro famílias de endpoints POST abrem uma sessão e devolvem um sessionID. Um GET devolve o resultado.^[13]

As famílias de endpoints da RP API v3, segundo a visão geral da SK.^[13]

Início de sessão entre dispositivos, simplificado, com uma ligação de dispositivo.^[12][18]

Erros comuns:

• Cada pedido inicial v3 inclui um rpChallenge aleatório gerado por si. Substituiu o nonce da v2 contra ataques de repetição.^[20]
• O sessionSecret nunca pode chegar ao seu frontend, e cada fluxo tem um único pedido de sessão, mesmo quando mostra o QR e o link em conjunto.^[18]
• Nos fluxos de notificação, calcula o código de quatro dígitos a partir do SHA-256 do rpChallenge.^[17]
• A SK autentica-o pelo IP de origem e pelo relyingPartyUUID, e exige a fixação de chaves (key pinning) HTTPS.^[19]
• A documentação da SK indica que um utilizador sem conta recebe HTTP 404 e pede que mostre uma única mensagem para todos os casos de erro, para evitar a enumeração.^[19]

O que uma empresa recebe da API Smart-ID

Uma sessão concluída devolve state, result.endResult, o certificado do utilizador em cert e um objeto signature. O serialNumber do titular contém o código de identificação, por exemplo PNOEE-30001010004, em que o prefixo indica o país.^[15]

A verificação da resposta definida pela SK obriga a:^[15]

• Confirmar que state é COMPLETE, que endResult é OK e que o protocolo é ACSP_V2 (autenticação) ou RAW_DIGEST_SIGNATURE.
• Validar a cadeia apenas contra as AC da SK, com OCSP ou CRL.
• Exigir todos os identificadores de política Smart-ID, para que outros certificados da SK falhem.
• Comparar certificateLevel com o nível exigido.
• Reconstruir o conteúdo assinado e verificar a assinatura.
• Verificar os valores do URL de callback nos fluxos no mesmo dispositivo.

Nível de garantia e valor jurídico

O Smart-ID não consta da lista da UE de sistemas de identificação eletrónica notificados; o sistema notificado da Estónia (elevado, 7 de novembro de 2018) abrange o cartão de identificação e o Mobile-ID.^[6]

Ressalva: os e-residentes "não se distinguem dos residentes".^[5]

Diligência quanto à clientela em matéria de prevenção do branqueamento de capitais na Estónia

A Lei de Prevenção do Branqueamento de Capitais e do Financiamento do Terrorismo da Estónia (RahaPTS) define as vias remotas no § 31(3).^[23]

§ 31(3)RahaPTS (Estónia)

"1) e-identimise süsteemi, millest on teatatud ... (EL) nr 910/2014 ... artikli 9 kohaselt ja mis vastab ... artikli 8 lõike 2 punktis b või c sätestatud usaldusväärsuse tasemele" ou "2) kvalifitseeritud usaldusteenust"

Fonte: Riigi Teataja, RahaPTS^[23]

Em português: um regime de identificação eletrónica notificado com nível substancial ou elevado, ou um serviço de confiança qualificado. A via 1 não se aplica. À data de 5 de outubro de 2026, não existe declaração oficial sobre se os certificados qualificados do Smart-ID cabem na via 2, pelo que deve consultar a Finantsinspektsioon ou um advogado. A lei de prevenção do branqueamento de capitais da Lituânia (artigo 11) e o Regulamento do Conselho de Ministros n.º 392 da Letónia (ponto 7.1) incluem uma assinatura eletrónica qualificada ou segura entre várias vias remotas.^[28][29]

A partir de 2027: artigo 22(6) do AMLR

O Regulamento Antibranqueamento de Capitais (AMLR) aplica-se a partir de 10 de julho de 2027. O artigo 22(6)(b) aceita "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' e serviços de confiança qualificados pertinentes".^[30] Os projetos finais de normas da Autoridade para o Combate ao Branqueamento de Capitais (AMLA), de 30 de setembro de 2026, ainda sem força de lei, aceitam a identificação eletrónica com nível substancial ou elevado "independentemente de terem sido notificados nos termos do artigo 9".^[31] A nossa página sobre a carteira europeia de identidade digital (EUDI Wallet) aborda o calendário do eIDAS 2.

Como uma empresa se liga: contrato de RP direto ou intermediário

O processo da SK: testar gratuitamente sem acordo, escolher as medidas de segurança, enviar os seus endereços IP e o nome do serviço, assinar, receber o seu RP UUID e entrar em produção "poucos dias após o seu primeiro contacto".^[21] Os intermediários certificados também revendem o Smart-ID, e os organismos públicos estónios podem usar o gateway TARA da RIA.^[5]

Três formas de aceder ao Smart-ID.^[21][5]

A tabela de preços da SK (a partir de 1 de junho de 2026) fatura cada "pedido de autenticação ou assinatura Smart-ID": €0.109 com um mínimo mensal de €60, descendo até €0.0106 no plano de 3 milhões, e um acordo individual acima de 5 milhões.^[11] A SK afirma que o Smart-ID+ "não tem custo adicional" para as RP existentes.^[7]

Testes no ambiente de demonstração

Demonstração: https://sid.demo.sk.ee/smart-id-rp/v3/, relyingPartyUUID 00000000-0000-4000-8000-000000000000, nome DEMO. Produção: https://rp-api.smart-id.com/v3/.^[14] Contas de teste por resultado:^[16]

Casos de utilização e regras setoriais

• Onboarding KYC e AML. Nome assinado e código pessoal; a adequação para efeitos de AML varia consoante o país.^[23][28][29]
• Jogo e idade. A Lei do Jogo da Estónia proíbe o acesso de menores de 21 anos a jogos de fortuna ou azar (§ 34(2)). Exige ainda que os operadores remotos verifiquem cada jogador e registem o código pessoal (§ 53(1)).^[24] Não encontrámos na API qualquer atributo apenas de idade.
• Assinatura. As contas qualificadas assinam através de v3/signature; "4 em cada 10 lituanos utilizaram uma assinatura eletrónica qualificada em 2025".^[13][33]
• Telecomunicações. Nenhuma regra báltica menciona o Smart-ID para o registo de cartões SIM (5 de outubro de 2026).

Limitações e alternativas

"Na Estónia e na Letónia, o Smart-ID está atualmente limitado a pessoas com número de identificação nacional estónio ou letão"; os não residentes na Lituânia podem obter o Smart-ID Basic em dois bancos.^[22] O Smart-ID não tem limite de idade, mas as vias de registo têm (cartão de identidade letão a partir dos 14 anos). As contas de menores de 18 anos precisam de autorização parental.^[32]

À data de 5 de outubro de 2026, não encontrámos nenhuma interrupção de serviço documentada; o risco é o phishing. Segundo a ERR News, burlas de PIN roubaram quase €23 milhões de contas bancárias estónias em 2025. Desde 29 de abril de 2026, o registo na Estónia lê o cartão de cidadão por NFC, em vez de um leitor de cartões.^[34]

Primeiro a eID, depois o documento como alternativa; registe o motivo de cada recurso à alternativa.^[31]

Lista de verificação para implementar a API do Smart-ID

Desenvolva primeiro sobre a demo gratuita da SK, para que o contrato só avance quando o seu código funcionar.^[21] A verificação das respostas é o núcleo do trabalho.^[15]

• Desenvolva com o URL de demonstração e as contas de teste publicadas.^[14][16]
• Prefira os fluxos de ligação de dispositivo; permita notificações apenas em dispositivos conhecidos.^[13]
• Gere um rpChallenge aleatório novo em cada login.^[20]
• Fixe a chave HTTPS da SK e mantenha o sessionSecret no servidor.^[19][18]
• Execute todos os passos da verificação de respostas da SK.^[15]
• Envie à SK os seus IP e o nome do serviço e, depois, assine.^[21]
• Documente a sua base jurídica para a utilização em AML em cada país.^[23]
• Acrescente uma via documental para utilizadores sem Smart-ID.

Como a Didit ajuda com o Smart-ID

O Smart-ID está ativo na Didit para verificação de eID na Estónia, Letónia, Lituânia e Bélgica. A ligação à SK é da Didit. Assim, dispensa o contrato de RP, a lista de IP autorizados e o código de certificados.

Na consola, aceda a Workflows, ao passo ID Verification e a Countries. Escolha o país e assinale Smart-ID em "Wallets accepted". Por API, defina methods.EST.wallet e crie uma sessão. Depois, leia GET /v3/session/{id}/decision/ ou o webhook: verification_method é "wallet", com um objeto wallet_verification, conforme a documentação sobre carteiras de identidade digital.^[35] O utilizador aprova um código de comparação na aplicação Smart-ID. A Didit nunca pede o PIN.

Obtém o nome completo, a data de nascimento, o código pessoal báltico, o nível de garantia (com a indicação High) e uma verificação de assinatura; não inclui morada nem retrato. Os utilizadores sem Smart-ID recorrem à verificação de documentos com leitura do chip NFC ($0.15), prova de vida e correspondência facial; o KYC completo custa $0.33 e a triagem AML $0.20. Só são faturados os inícios de sessão eID concluídos; uma verificação Smart-ID concluída custa $0.20 (página de preços), e todos os eID constam da página de carteiras de identidade digital.

Perguntas frequentes

Fontes

1. Página inicial do Smart-ID, contador de utilizadores em tempo real, SK ID Solutions, consultado em 5 de outubro de 2026.
2. 2025: promover a confiança digital além-fronteiras, SK ID Solutions, 19 de janeiro de 2026.
3. Confiança e concorrência na identidade digital na Europa, e-Estonia, 2026.
4. Identidade eletrónica (eID), Autoridade dos Sistemas de Informação (RIA).
5. Especificação técnica do TARA, RIA.
6. Panorâmica dos sistemas de identificação eletrónica pré-notificados e notificados ao abrigo do eIDAS, Comissão Europeia, consultado em 5 de outubro de 2026.
7. Smart-ID+, SK ID Solutions.
8. Como é que o novo Smart-ID me protege contra a fraude, FAQ do Smart-ID.
9. O governo da Estónia adota o Smart-ID+ para reforçar a segurança, SK ID Solutions, 28 de janeiro de 2026.
10. Porque é que às vezes vejo um código de confirmação e outras vezes três, FAQ do Smart-ID.
11. Tabela de preços, SK ID Solutions, válida a partir de 1 de junho de 2026.
12. Relying Party API: introdução, SK ID Solutions, versão 3.2.3.
13. Relying Party API: visão geral dos endpoints da API, SK ID Solutions.
14. Parâmetros técnicos dos ambientes, SK ID Solutions.
15. Relying Party API: verificação de respostas, SK ID Solutions.
16. Contas de teste para testes automatizados, SK ID Solutions.
17. Relying Party API: fluxos baseados em notificações, SK ID Solutions.
18. Relying Party API: fluxos de ligação de dispositivo, SK ID Solutions.
19. Relying Party API: descrição técnica da API, SK ID Solutions.
20. Relying Party API: registo de alterações, SK ID Solutions.
21. Processo de integração para prestadores de serviços eletrónicos, Smart-ID.
22. Os estrangeiros e os não residentes podem utilizar o Smart-ID, FAQ do Smart-ID.
23. Rahapesu ja terrorismi rahastamise tõkestamise seadus (RahaPTS), § 31, Riigi Teataja.
24. Hasartmänguseadus (Lei do Jogo), Riigi Teataja.
25. Elektroniskā identifikācija, Ministério da Defesa da Letónia.
26. O Smart-ID obteve o estatuto qualificado local para autenticação na Letónia, SK ID Solutions, 29 de maio de 2023.
27. Smart-ID e Mobile-ID reconhecidos como ferramentas aprovadas pelo Estado na Lituânia, SK ID Solutions, 19 de dezembro de 2024.
28. Lei relativa à Prevenção do Branqueamento de Capitais e do Financiamento do Terrorismo, art. 11, Lituânia, texto consolidado INFOLEX.
29. Regulamento do Conselho de Ministros n.º 392, Letónia, likumi.lv.
30. Regulamento (UE) 2024/1624 (AMLR), EUR-Lex, Jornal Oficial de 19 de junho de 2024.
31. Relatório final, projeto de RTS ao abrigo do artigo 28(1) do AMLR, AMLA, 30 de setembro de 2026.
32. Limites de idade para utilizar o Smart-ID, FAQ do Smart-ID.
33. A SK ID Solutions emitiu quase três milhões de certificados na Lituânia em 2025, SK ID Solutions, 7 de maio de 2026.
34. Registo no Smart-ID com o cartão de identidade estónio já disponível via NFC, Smart-ID, 29 de abril de 2026.
35. Carteiras de identidade digital, documentação da Didit.
36. Relying Party API: interações, SK ID Solutions.

O Smart-ID é um dos cinco eID ativos na verificação de eID da Didit. Consulte também o que é a verificação de eID e o guia da API do BankID da Suécia.