Saltar para o conteúdo principal
A Verificação de identidade é uma funcionalidade única com três métodos. Você escolhe quais os métodos que um país pode utilizar; o utilizador final recebe os que se aplicam ao país que selecionar, e a sessão regista qual o método que efetivamente produziu o resultado. A captura do documento não sofreu alterações. Tudo o que já configura através de documents_allowed — tipos aceites, subtipos, regras de captura, limiares, avisos — continua a funcionar exatamente como antes, e um fluxo que não mencione métodos permanece apenas com captura do documento.

​
Como funciona cada método

​
Captura do documento

O que o resto desta secção documenta: o utilizador fotografa o documento, a Didit lê-o, verifica a sua autenticidade e devolve os campos extraídos. Disponível em todos os países suportados pela Didit, a $0.15 por verificação. Comece na Visão geral da Verificação de identidade.

​
Consulta sem documento

O utilizador introduz o seu número de identificação nacional e alguns dados pessoais, e a Didit valida-os junto da fonte fidedigna desse país. Não envolve qualquer fotografia de um documento. Na maioria dos países, essa fonte é um registo governamental, mas não em todos: no Canadá, França, Indonésia, Países Baixos, Noruega, Singapura, Reino Unido e Estados Unidos, trata-se, em vez disso, de um ficheiro de agência de crédito, de serviços financeiros, de serviços públicos essenciais ou de registos de residência. Dado que a proveniência e o regime de consentimento aplicável variam consoante o caso, a fonte exata é indicada por país na tabela abaixo e em Consulta sem documento — nunca de forma generalizada. Quando a fonte devolve um retrato — atualmente África do Sul, Nigéria, Argentina e Panamá, todos os quatro registos governamentais —, é também solicitada uma selfie ao utilizador. A prova de vida passiva é executada nessa selfie e é feita a correspondência facial com o retrato do registo, tudo integrado na consulta e incluído no preço da mesma. Quando a fonte devolve apenas dados, não há nada com que fazer a correspondência facial, pelo que não é recolhida qualquer selfie; execute a Prova de vida e a Correspondência facial como passos autónomos do fluxo, se necessitar deles. Os campos de pedido completos por país, as regras de formato e os regimes de consentimento estão disponíveis em Consulta sem documento.

​
Carteira

O utilizador inicia sessão com uma identidade digital que já possua, como um eID nacional ou uma identidade bancária. A carteira autentica-o e partilha atributos de identidade assinados com a Didit. Consoante a carteira, o utilizador pode introduzir um código de identificação pessoal ou número de telefone; não é necessária qualquer fotografia do documento para a verificação por carteira. A experiência de início de sessão depende da carteira: um encaminhamento para uma aplicação, um código QR ou um código de comparação confirmado no telemóvel do utilizador. Smart-ID e Mobile-ID utilizam um código de comparação. Os atributos por carteira, a disponibilidade em produção e a semântica de falhas estão disponíveis em Carteiras de identificação digital.

​
Níveis de garantia

Cada resultado da Verificação de identidade inclui um nível de garantia derivado do método que o produziu. O nível é uma descrição fidedigna do que foi efetivamente comprovado, não uma classificação:
Os níveis de garantia são uma etiqueta destinada a administradores. Surgem no payload da sessão, na consola e nas exportações. Os utilizadores finais nunca veem o nível, o preço ou o nome da fonte consultada.

​
Configurar métodos por país

Os métodos encontram-se sob a chave methods na configuração da funcionalidade de Verificação de identidade (OCR), indexados pelo código de país ISO 3166-1 alpha-3. Se omitir a chave, omitir um país ou omitir um método dentro de um país, esse país funcionará apenas com captura do documento.
Ambos os países acima estão como available para consulta no catálogo publicado. O exemplo mantém as carteiras desativadas para não depender de uma carteira estar ativada no seu ambiente. Um fluxo que ative uma carteira marcada como Em breve é rejeitado, incluindo a outra configuração desse pedido de gravação. Assim que o catálogo marcar uma carteira como available num país, o bloco de carteira para esse país terá o seguinte aspeto:
Consulte o catálogo antes de enviar. Pré-requisito: a carteira deve constar como Disponível para esse país, listada em Carteiras de identificação digital. Duas regras que a API aplica ao guardar:
  • A disponibilidade é determinada pelo servidor. Um método ou uma carteira que o catálogo de capacidades não marque como available para esse país é rejeitado. Consulte primeiro o catálogo — através do separador Países da consola, ou com a ferramenta MCP didit_workflow_get_id_verification_methods_catalog.
  • As carteiras funcionam como uma lista de permissões, nunca como uma classificação. providers define quais as carteiras que um país pode disponibilizar. A ordem enviada não tem qualquer efeito prático e é normalizada; o utilizador final é quem escolhe.
A referência completa campo a campo, incluindo valores predefinidos e validação, encontra-se em Configurações de funcionalidades do fluxo.

​
Fallback: o que acontece quando um método sem documentos não é concluído

Quatro parâmetros decidem o que acontece a seguir. Cada um é fallback_to_document (encaminhar o utilizador para a captura de documentos) ou decline (terminar a sessão com uma Verificação de identidade recusada); wallet.on_failure também aceita retry, descrito abaixo. Todos os quatro têm por predefinição o valor fallback_to_document. wallet.on_failure também aceita um terceiro valor, retry, para um país que apenas aceite a carteira (captura de documentos desativada): O valor retry é exclusivo para carteiras: as opções da consulta aceitam fallback_to_document ou decline, uma vez que um registo que respondeu «sem correspondência» não tem nada para tentar novamente. É rejeitado em conjunto com document.fallback_only, que necessita de uma falha que resulte na captura de documentos. Uma carteira que iniciou sessão e devolveu dados que falham as verificações do seu fluxo (idade, correspondência de nome, etc.) é um início de sessão verificado: as regras do fluxo decidem, wallet.on_failure não se aplica. Um início de sessão cujo token é genuíno mas inaceitável (nível de garantia incorreto, assinatura inválida, declarações obrigatórias em falta) conta como uma falha e segue wallet.on_failure. id_lookup.max_attempts (1 a 5, predefinição 1) é o número de consultas respondidas a que o utilizador tem direito antes de o parâmetro ser acionado. Um número que falhe a verificação de formato no lado do cliente nunca chega ao registo, pelo que não consome uma tentativa — é simplesmente pedido ao utilizador que o corrija. Uma carteira ou consulta só pode recorrer à captura de documentos quando a captura de documentos estiver ativada para esse país e pelo menos um tipo de documento for aceite aí. Com a captura de documentos desativada, ou sem qualquer tipo de documento aceite para o país, se um início de sessão falhar ou uma consulta não encontrar correspondência, a sessão é recusada, mesmo que o parâmetro indique fallback_to_document. A exceção é wallet.on_failure: retry, que nunca recusa: o utilizador permanece no passo da carteira. Não há para onde recorrer. Que método produziu o resultado: fallback_from verification_method indica sempre o método que produziu o resultado verificado: wallet, id_lookup ou document. fallback_from explica o motivo pelo qual um método sem documentos não concluiu o passo de identificação, em ambos os desfechos:
  • Fallback aplicado. O utilizador é encaminhado para a captura de documentos. A verificação de documentos que se segue tem verification_method: "document" e fallback_from a indicar o método que falhou, por exemplo { "method": "wallet", "reason": "cancelled", "action": "fallback_to_document" }. Uma sessão que tenha sido verificada pela carteira tem verification_method: "wallet" e fallback_from: null.
  • Recusa. O parâmetro é decline, ou não existe nenhum documento disponível como fallback. A Verificação de identidade recusada tem fallback_from com "action": "decline".
method é wallet ou id_lookup, e reason é o desfecho que o terminou (cancelled, timeout, no_match, provider_error, entre outros). Os mesmos campos são enviados na decisão da sessão e no webhook status.updated. Um registo que não responda (um tempo limite esgotado ou uma indisponibilidade) é a exceção: nunca recusa o utilizador por si próprio. A consulta não é faturada e nenhuma tentativa é consumida; é pedido ao utilizador que tente novamente. Após três consultas sem resposta no passo, id_lookup.on_provider_error aplica-se: decline recusa e fallback_to_document encaminha o utilizador para a captura de documentos. Quando esse parâmetro é fallback_to_document, mas o país não tem qualquer documento para o qual recorrer, a consulta permanece aberta e o utilizador pode continuar a tentar; a sessão não é recusada.

​
Disponibilizar a captura de documentos apenas como fallback

Por predefinição, um país que disponibilize uma carteira ou uma consulta de identificação juntamente com a captura de documentos apresenta-os lado a lado no primeiro ecrã. Defina document.fallback_only como true para manter a captura de documentos ativada para o país sem a apresentar logo à partida. Os utilizadores começam com a carteira ou com a consulta de identificação do país. Com uma única carteira, o utilizador entra diretamente nessa carteira. Apenas os utilizadores cujo início de sessão na carteira falhe, seja cancelado ou atinja o tempo limite, ou cuja consulta não corresponda, são encaminhados para a captura de documentos. Quais desses desfechos conduzem à captura de documentos continua a ser decidido pelos parâmetros acima, pelo que pelo menos um deles deve ser fallback_to_document.
fallback_only é opcional e tem por predefinição false. É rejeitado a menos que document.enabled seja true e pelo menos uma carteira ou consulta de identificação nesse país recorra à captura de documentos. Ative os tipos de documento que o fallback deve disponibilizar em documents_allowed, por exemplo passaporte e cartão de identificação para a Finlândia.

​
Quanto custa cada método

Estes são preços de tabela: o desconto do seu plano aplica-se a ambos os métodos. Uma consulta utiliza as tarifas públicas de retalho da Validação de base de dados para os serviços que executa; vários serviços podem contribuir para uma tentativa. A Nigéria seleciona o NIN ou o BVN. A tabela de países apresenta o preço total configurado por tentativa, sendo cada nova tentativa com resposta faturada separadamente.

​
Regras de faturação

  • Uma consulta a um registo que respondeu é faturada. Correspondência, correspondência parcial e ausência de correspondência contam todas — a consulta foi executada e a resposta é o produto.
  • Um registo que nunca respondeu não é faturado. Um erro de fornecedor não tem custos.
  • Um número que falhe a verificação de formato no lado do cliente nunca é faturado e nunca é contabilizado em max_attempts, porque nunca chegou ao registo.
  • A captura de documentos é faturada adicionalmente quando o utilizador recorre à captura de documentos. Uma consulta que obteve resposta e depois recorreu à captura de documentos implica duas cobranças, porque foram executadas duas verificações.

​
Cobertura

A captura de documentos está disponível em todos os países suportados pela Didit e não é repetida abaixo: $0.15 por verificação. Esta tabela lista apenas os países onde existe um método que não recorre a documentos. Um país que não esteja listado, ou uma célula que indique Não planeado, contempla apenas a captura de documentos.
A cobertura é gerada a partir do catálogo de capacidades disponibilizado pelo backend, pelo que esta tabela é a mesma fonte em relação à qual a consola e a API realizam a validação. Em breve significa que a entrada está visível na consola, mas ainda não pode ser ativada; não se trata de uma capacidade ativa e não tem uma data definida.

​
O que chega à sessão

Cada resultado de Verificação de identidade inclui o método que o gerou, o seu nível de garantia e — quando é executado um método sem documentos — um bloco de evidências específico do método. As sessões com documentos são lidas exatamente como anteriormente, com as novas chaves a null. Os tipos campo a campo e os exemplos para os três métodos estão no modelo de dados da verificação de identidade, e as mesmas chaves são incluídas no webhook status.updated.

​
Relacionado

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