APIs de verificação com carteira de identidade digital

Use um endpoint de carteira dedicado para verificar uma pessoa a partir da sua própria aplicação. Não precisa de criar nem publicar um fluxo de verificação, nem de indicar um workflow_id. O seu backend inicia a verificação e obtém o respetivo resultado; a sua interface orienta a pessoa ao longo da autenticação exigida pela carteira.

Uma integração por API continua a exigir que a pessoa se autentique e aprove a partilha da sua identidade. Não é possível verificar alguém submetendo o seu identificador pessoal sem essa interação.

Como funciona a verificação

O seu backend consulta o catálogo de carteiras e, depois, chama o endpoint de início de uma carteira disponível, usando a chave de API da sua aplicação.
A Didit devolve uma referência de verificação e a ação que a pessoa precisa de realizar.
A sua aplicação abre a página de autenticação ou apresenta as instruções de aprovação da carteira.
A pessoa autentica-se com a sua carteira.
O seu backend obtém o resultado verificado e trata as notificações de conclusão.

A autenticação por carteira é assíncrona. Um pedido de início bem-sucedido significa que a autenticação foi iniciada; não significa que a identidade tenha sido verificada. Confirme sempre o resultado final antes de considerar a pessoa verificada.

Integração no backend

Use Listar carteiras de identidade digital para obter os endpoints atuais, os campos obrigatórios e a disponibilidade para a sua aplicação. Mantenha o seu x-api-key no backend. Não o coloque num pacote do navegador nem numa aplicação móvel. Use um Idempotency-Key distinto para cada nova tentativa de verificação e reutilize essa chave ao repetir o mesmo pedido de início. Alterar o pedido e reutilizar a sua chave é um conflito, não uma nova tentativa de verificação. Cada carteira tem o seu próprio URL de início, como /v3/id-verification/wallets/ftn/ para a Finnish Trust Network. O request_id identifica a verificação autónoma para as operações seguintes. Use vendor_data como referência própria, até 2.000 bytes UTF-8, e metadata para um objeto JSON opcional. Ambos são devolvidos com o resultado e com o webhook de conclusão.

Operação	Endpoint
Consultar estado e resultado	`GET /v3/id-verification/wallets/verifications/{request_id}/`
Consultar uma aprovação por telefone	`POST /v3/id-verification/wallets/verifications/{request_id}/poll/`
Enviar a resposta de uma Carteira de Credenciais Digitais	`POST /v3/id-verification/wallets/verifications/{request_id}/response/`
Cancelar uma verificação pendente	`POST /v3/id-verification/wallets/verifications/{request_id}/cancel/`

Estas operações usam a chave de API da aplicação que iniciou a verificação. A consulta e a disponibilidade da autenticação dependem da carteira selecionada. Um cancelamento recusa uma verificação pendente sem a cobrar, e devolve uma verificação concluída sem alterações. Para a Smart-ID e a Mobile-ID, um cancelamento que chegue enquanto uma consulta está a verificar a aprovação aguarda alguns segundos por essa consulta. Depois, recusa a verificação ou devolve-a como verified, caso a pessoa já tenha aprovado. Uma verificação que a pessoa esteja a concluir nesse momento não pode ser cancelada: a resposta é 409 com error: "verification_in_progress" e um cabeçalho Retry-After. Aguarde esse número de segundos e volte a tentar para ler o resultado concluído.

Registe o seu destino de retorno

As carteiras com redirecionamento enviam a pessoa de volta para a sua aplicação depois da autenticação. Registe o hostname exato antes de iniciar uma verificação:

curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'

Em seguida, envie um return_url HTTPS, como https://app.example.com/identity/complete, no pedido de início. Use hostnames simples em allowed_return_hosts, sem esquema, caminho ou wildcard. Registe separadamente cada subdomínio que utilizar, até 20 hostnames. Atualizar allowed_return_hosts substitui a lista registada, por isso inclua todos os hostnames que quer manter. GET /v3/webhook/ devolve a lista atual; veja Configuração de webhooks. Não precisa de um fluxo de verificação nem de um domínio de marca branca para registar um destino de retorno. O destino é uma página de retorno no navegador; configure os webhooks de conclusão em separado para o seu backend.

Exemplo: Finnish Trust Network

Depois de registar o seu hostname de retorno, inicie uma verificação na Finnish Trust Network:

curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'

Guarde o request_id devolvido e envie o navegador da pessoa para wallet_verification.next_action.url quando o type for redirect. Depois de a pessoa regressar, obtenha o resultado a partir do seu backend:

curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'

Verifique wallet_verification.outcome:

Resultado	Significado
`pending`	A autenticação ainda está em curso.
`verified`	A autenticação foi concluída e a identidade devolvida foi verificada.
`cancelled`	A pessoa ou a sua aplicação cancelou a tentativa.
`timeout`	A janela de autenticação expirou.
`failed`	A autenticação ou a validação da identidade falhou.

Use a identidade apenas quando o resultado for verified e simulated for false numa verificação de identidade real. Uma resposta pendente pode conter uma próxima ação; as respostas finais não têm próxima ação.

Experiências de autenticação

Carteiras de redirecionamento devolvem um URL de autenticação. Abra esse URL no navegador da pessoa, deixe-a concluir o processo de autenticação da carteira e reencaminhe-a para o destino de retorno que registou. Leia o resultado a partir do seu backend, em vez de confiar num parâmetro do URL de retorno como prova de identidade. Smart-ID e Mobile-ID usam um pedido de aprovação no telemóvel da pessoa. A sua interface recolhe o identificador pessoal necessário; o Mobile-ID exige também o número de telefone associado. Mostre o código de comparação e indique à pessoa que aprove apenas se corresponder ao código apresentado no telemóvel dela. O PIN dela deve ser introduzido no pedido da carteira ou do telemóvel, nunca no seu formulário nem num pedido à API. Faça consultas periódicas a partir do seu backend no intervalo devolvido em poll_interval_seconds para obter rapidamente informações sobre o pedido de aprovação. A Didit também verifica em segundo plano as aprovações telefónicas pendentes, pelo que a conclusão pode chegar ao seu webhook depois de a pessoa fechar a sua página. Google Wallet é solicitada a partir da sua própria página ou aplicação através da Digital Credentials API, sem redirecionamento; veja Carteiras de credenciais digitais (Google Wallet). A interação disponível depende da carteira selecionada. Não assuma que todas as carteiras suportam um formulário incorporado, um código QR ou autenticação sem navegador.

Carteiras de credenciais digitais (Google Wallet)

A Google Wallet é solicitada diretamente pela sua página web ou aplicação Android, através da W3C Digital Credentials API. Não há redirecionamento, nem página alojada pela Didit, nem código QR da Didit. Está disponível em produção e em sandbox. As aplicações em sandbox não precisam de registo; cada aplicação de produção se regista uma vez na consola (passo de verificação de identidade, linha Google Wallet, Registar na Google) antes de poder usar a Google Wallet. Consulte Listar carteiras de identidade digital para ver o que a sua aplicação pode iniciar já.

Comece com a sua origem

O seu backend chama POST /v3/id-verification/wallets/google-wallet/ com o country da pessoa (USA, GBR, BRA, SGP ou TWN) e a origin que vai pedir a carteira. A origin é a origem HTTPS da sua página, como https://app.example.com, cujo anfitrião tem de ser um dos nomes de anfitrião de retorno registados ou o seu domínio de marca branca. Numa aplicação Android é android:apk-key-hash: seguido do SHA-256 em base64 do certificado de assinatura da sua aplicação, sem preenchimento. A carteira recusa qualquer pedido feito a partir de outra origem. Não existe return_url.

curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'

Solicite a carteira durante uma ação do utilizador

A resposta tem wallet_verification.interaction = "digital_credentials" e next_action.type = "request_digital_credential". Passe next_action.digital_credentials.request ao navegador ou ao Android Credential Manager, a partir de um toque ou clique na origin com que iniciou. No computador, o navegador mostra o seu próprio código QR quando a carteira está noutro dispositivo.

Envie o que a carteira devolveu

Envie o {protocol, data} devolvido ao seu backend e, a partir daí, para POST /v3/id-verification/wallets/verifications/{request_id}/response/ como {"response": {...}}. O pedido só pode ser submetido uma vez; uma segunda submissão devolve a verificação já decidida.

Leia o resultado

A resposta à submissão é a verificação decidida. Também pode lê-la com GET /v3/id-verification/wallets/verifications/{request_id}/ ou recebê-la no webhook de conclusão.

No navegador, peça a carteira a partir de um manipulador de cliques:

// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});

Ofereça o método apenas onde o navegador o suporta, por exemplo quando "DigitalCredential" in window é verdadeiro. navigator.credentials.get tem de ser executado num gesto do utilizador, por isso chame-o a partir do manipulador de cliques e não depois de um passo assíncrono. No Android, use o Jetpack Credential Manager (androidx.credentials 1.5.0 ou posterior) com o mesmo pedido:

val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.

Erros a tratar:

Erro	Onde	Significado
`origin_invalid`	Início, `400`	`origin` não é uma origem HTTPS nem uma origem de aplicação Android.
`origin_not_allowed`	Início, `400`	O anfitrião da origem não está registado para a sua aplicação. Registe-o em `allowed_return_hosts`.
`not_a_digital_credentials_wallet`	Submissão, `409`	Esta verificação não aceita uma resposta da carteira.

Uma credencial que falha a verificação é uma verificação decidida com um resultado failed, não uma resposta de erro. Só saem da carteira os campos que a verificação pede, e o resultado contém os atributos de identidade que a carteira devolveu. Um passe de identificação da Google Wallet ou uma carta de condução móvel emitida por um estado dos EUA não devolve um retrato. Numa aplicação em sandbox, o fluxo é simulado com os mesmos passos e devolve simulated: true. Qualquer resposta submetida decide a verificação de acordo com o sandbox_scenario, para que possa construir o percurso completo no navegador ou na aplicação sem uma credencial real.

Webhooks de conclusão

Configure um destino de webhook da aplicação para status.updated, seguindo o guia de integração de webhooks. Use webhook_version: "v3" para a estrutura de decisão descrita aqui. Valide a assinatura do webhook no seu backend antes de o processar. O session_id do webhook corresponde ao request_id devolvido pela API da carteira. Uma identidade verificada através da carteira, quando concluída, aparece no array decision.id_verifications do webhook com verification_method: "wallet". Também pode usar o identificador para obter o resultado dedicado da API da carteira. Trate as notificações de aprovação e de recusa, incluindo as verificações canceladas e expiradas. Torne o handler do seu webhook idempotente, porque as entregas falhadas são tentadas novamente. O regresso ao navegador não é um webhook de conclusão, e os seus parâmetros de consulta não são prova de identidade.

Identidade devolvida

Use os campos de identidade normalizados para nomes e datas de nascimento quando esses campos forem devolvidos. Os atributos específicos da carteira descrevem as informações de identidade partilhadas pela carteira selecionada. Os atributos disponíveis variam consoante a carteira e o país. Uma identidade autenticada não implica que um retrato, a morada ou qualquer outro atributo pedido esteja disponível.

Testar no sandbox

Uma aplicação em modo sandbox da Didit simula a verificação por carteira sem contactar um fornecedor de carteiras nem debitar créditos. A resposta identifica estes pedidos com wallet_verification.simulated: true. Uma aprovação simulada corresponde a dados de exemplo, não a uma identidade real verificada. Para uma carteira de redirecionamento, siga o URL devolvido para testar a chamada de retorno e regressar à sua aplicação. Para Smart-ID ou Mobile-ID, use o endpoint de consulta para concluir a aprovação simulada; não é enviada nenhuma notificação para um telemóvel. Para testar o tratamento de falhas, defina sandbox_scenario como wallet_cancelled, wallet_timeout ou wallet_provider_error ao iniciar um pedido. As aplicações em produção rejeitam sandbox_scenario. A simulação do sandbox da Didit é separada dos testes num ambiente de teste do próprio fornecedor. Uma simulação bem-sucedida não estabelece acesso ao fornecedor em produção nem disponibilidade em produção.

Sandbox do fornecedor ConnectID

O sandbox do fornecedor ConnectID usa bancos de teste e é separado da simulação do sandbox da Didit. Quando o acesso ao sandbox do fornecedor estiver configurado para a sua integração, transmita o authorisation_server_id do banco selecionado no endpoint de início do ConnectID. Use o ID devolvido pelo seletor de bancos do ConnectID; não envie um URL de banco nem um emissor arbitrário. Se omitir o campo, é selecionado o banco de teste predefinido. O campo é específico do ConnectID e não altera os atributos de identidade pedidos. O pacote inicial pede o nome próprio, o apelido e a data de nascimento. Siga o next_action devolvido para se autenticar e, em seguida, obtenha ou consulte o resultado da verificação. Só um resultado concluído com estado aprovado confirma que a verificação foi bem-sucedida; o regresso à sua aplicação não o confirma. O ConnectID continua Em breve em produção enquanto o onboarding e a certificação são concluídos.

Disponibilidade e preços

A cobertura dos endpoints e a ativação de carteiras em produção são coisas separadas. Uma carteira pode ter uma página de referência da API e continuar indisponível para autenticação em produção. Verifique a cobertura por país e o estado de produção da carteira antes de implementar um percurso em produção. Consulte preços de carteiras de ID digital para as tarifas e a disponibilidade publicadas. A verificação por carteira é faturada separadamente da captura de documentos.

Escolher uma integração

Use estas APIs quando quiser controlar a interface circundante e a lógica da aplicação. Use a API de Sessions quando quiser o percurso de verificação alojado pela Didit, as regras do fluxo e os passos alternativos configurados. As duas abordagens exigem, ainda assim, o processo de autenticação e consentimento da carteira.

Última modificação em 7 de novembro de 2026

​Como funciona a verificação

​Integração no backend

​Registe o seu destino de retorno

​Exemplo: Finnish Trust Network

​Experiências de autenticação

​Carteiras de credenciais digitais (Google Wallet)

​Webhooks de conclusão

​Identidade devolvida

​Testar no sandbox

​Sandbox do fornecedor ConnectID

​Disponibilidade e preços

​Escolher uma integração

Como funciona a verificação

Integração no backend

Registe o seu destino de retorno

Exemplo: Finnish Trust Network

Experiências de autenticação

Carteiras de credenciais digitais (Google Wallet)

Webhooks de conclusão

Identidade devolvida

Testar no sandbox

Sandbox do fornecedor ConnectID

Disponibilidade e preços

Escolher uma integração