API de Verificação de Identidade: Guia de Integração e Avaliação (PT-PT)

Uma API de verificação de ID permite que uma aplicação recolha ou submeta evidências de identidade e receba resultados estruturados sobre uma pessoa alegada. Dependendo do fluxo de trabalho, pode validar um documento de identidade, extrair atributos, comparar um candidato em tempo real com um retrato de referência, verificar vivacidade, corroborar dados ou orquestrar várias verificações numa única sessão.

A resposta da API é uma evidência, não uma decisão comercial completa. Uma integração de produção deve também definir a captura fidedigna, a propriedade do estado do cliente, as transições de estado, as repetições, a revisão, a privacidade, a manutenção de registos e a política que transforma os resultados técnicos em aprovar, repetir, intensificar, rever ou recusar.

Principais pontos

• Uma API de verificação de ID é mais do que um endpoint. O contrato real inclui captura, estados assíncronos, evidências, eventos, reconciliação, revisão e eliminação.
• O backend é o responsável pela decisão. Um redirecionamento do cliente ou um ecrã visual de sucesso não é autoritário; o estado final deve ser confirmado no lado do servidor.
• Os resultados precisam de âmbito e razões. A autenticidade do documento, a ligação do titular, a vivacidade, a qualidade e o risco contextual devem permanecer separáveis, em vez de se agruparem num booleano inexplicável.
• A fiabilidade aparece em caminhos de falha. Idempotência, verificação de webhook, repetição de eventos, tempos limite, repetições, versionamento e paridade de sandbox importam tanto quanto o caminho feliz.
• A avaliação deve usar populações semelhantes às de produção. Cobertura, resistência à fraude, conclusão, resultados falsos, carga de revisão e privacidade devem ser medidos por documento, dispositivo, geografia e segmento de utilizador relevante.

O que faz uma API de verificação de ID?

Uma API de verificação de ID fornece uma interface legível por máquina para capacidades de prova de identidade. Uma integração típica cria uma tentativa de verificação, direciona o candidato através de uma experiência de captura segura, recebe eventos de progresso ou conclusão, recupera a evidência final e aplica a política da organização dependente.

O modelo de prova de identidade NIST SP 800-63A-4 separa três funções importantes:

• Resolução: distinguir a pessoa alegada dentro da população relevante.
• Validação: determinar se as evidências e atributos de identidade são autênticos, precisos e aceitáveis.
• Verificação: estabelecer que o candidato é o sujeito associado a essa evidência.

Uma API pode realizar uma, duas ou todas as três. Os nomes dos produtos não garantem o âmbito, pelo que os requisitos devem indicar a conclusão exata esperada de cada resultado.

API de verificação de ID, API de documentos, API de KYC e OCR comparados

Interface	Finalidade principal	Saída útil	O que não prova por si só
API de OCR	Converter pixels do documento em texto ou campos	Nome, data, número, morada extraídos	Autenticidade, posse ou risco do cliente
API de verificação de documentos	Validar um documento e as suas evidências capturadas	Verificações de autenticidade, validade, consistência de campos, indicadores de adulteração	Que o atual candidato é o seu proprietário
API de correspondência facial	Comparar um rosto submetido com uma referência	Decisão de semelhança ou correspondência num limiar	Vivacidade, autenticidade do documento ou identidade legal
API de vivacidade	Estimar a presença em tempo real na captura biométrica	Evidência de boa-fé, ataque, repetição ou pontuação	A identidade da pessoa
API de verificação de ID	Combinar validação de evidências e ligação do candidato	Resultados ao nível da evidência e resultado do fluxo de trabalho	KYC completo ou elegibilidade comercial
API de KYC	Suportar um fluxo mais amplo de diligência devida do cliente	Identidade, triagem, risco, fluxo de trabalho e registos	Conformidade automática sem política organizacional

Esta distinção evita erros arquitetónicos. Por exemplo, adicionar OCR a um formulário de upload acelera a entrada de dados, mas não autentica o documento. Adicionar correspondência facial conecta duas imagens, mas não consegue estabelecer se alguma das imagens veio de uma captura confiável e em tempo real.

Para o contexto mais amplo de política, triagem, risco e revisão contínua em torno destas interfaces, consulte o guia do ciclo de vida de KYC. Este artigo permanece no limite de confiança do programador: captura, estado da API, evidências, eventos, reconciliação e decisões de backend.

Modelos de integração comuns

Sessão de verificação alojada

O backend da aplicação cria uma sessão e recebe um URL ou token de curta duração. O utilizador completa a captura numa jornada alojada pelo fornecedor, depois retorna à aplicação. Este modelo pode reduzir a complexidade do frontend e do dispositivo, preservando o controlo do lado do servidor.

As questões-chave incluem branding, transferência de domínio, acessibilidade, localização, suporte a navegadores móveis, expiração de sessão, comportamento de retorno e como a aplicação retoma quando o utilizador muda de dispositivo.

SDK web ou móvel incorporado

Um SDK executa a experiência de captura dentro da aplicação. Pode fornecer um controlo de interface mais apertado e acesso às capacidades do dispositivo, mas a qualidade da integração afeta a segurança. O suporte de versão, a integridade da aplicação, as permissões da câmara, o manuseamento da câmara virtual, a política de atualização e a telemetria tornam-se parte da revisão.

Verificação autónoma servidor-a-servidor

O sistema do cliente envia dados ou mídia estruturados diretamente para um endpoint. Isso é útil para capturas já confiáveis, operações em lote ou módulos individuais. Também transfere a responsabilidade pela integridade da captura, consentimento, qualidade, segurança da carga útil e prevenção de repetições para o integrador.

Fluxo de trabalho orquestrado

Uma sessão pode ramificar-se em validação de documentos, verificações de base de dados, vivacidade, correspondência facial, triagem, sinais de dispositivo e revisão manual. A API deve expor o fluxo de trabalho e a versão da política para que o mesmo estado possa ser interpretado posteriormente.

Uma sequência de integração segura

1. Criar a tentativa a partir do backend

O backend fiável gera uma referência interna do cliente e chama o fornecedor com o fluxo de trabalho, localidade e contexto de política necessários. Não exponha credenciais de API permanentes no código do navegador ou móvel.

Use uma estratégia de idempotência para operações de criação. Um tempo limite do cliente não deve criar uma segunda tentativa faturável ou desvincular o resultado do cliente original.

2. Emitir uma entrega de captura de curta duração

Forneça ao frontend apenas o token ou URL com âmbito necessário para essa tentativa. Vincule-o à aplicação esperada, referência do cliente, fluxo de trabalho e expiração. Evite colocar dados pessoais desnecessários em URLs, eventos de análise ou registos do cliente.

3. Capturar e validar evidências

Guie o utilizador através das evidências suportadas e dos requisitos de qualidade. Separe problemas de qualidade recuperáveis de ataques suspeitos. "Aproximar", "documento expirado" e "a integridade da captura falhou" não devem tornar-se um erro genérico.

4. Receber um evento autenticado

Trate os webhooks como entrada não confiável até serem verificados. Valide a assinatura do evento ou a autenticação da mensagem, carimbo de data/hora ou controlo de frescura, destino esperado, tipo de conteúdo e identificador do evento. RFC 9421 define um mecanismo geral para Assinaturas de Mensagens HTTP, embora um fornecedor possa usar um esquema de assinatura documentado diferente.

Armazene identificadores de eventos e processe-os idempotentemente. Os sistemas de entrega tentam novamente; eventos duplicados são normais. Não assuma a ordem de chegada e não deixe um evento mais antigo fazer com que um cliente retroceda de um estado terminal.

5. Recuperar o resultado canónico

Após um evento de conclusão, obtenha a tentativa final da API do fornecedor. Este passo de reconciliação reduz a dependência do conteúdo de um único webhook e recupera de entregas perdidas ou atrasadas.

6. Aplicar a política da organização

Mapeie evidências estruturadas para os próprios estados de decisão da organização. O fornecedor pode recomendar um resultado, mas a organização dependente conhece o produto, o histórico do cliente, a base legal, o apetite pelo risco e os caminhos de recuperação disponíveis.

7. Registar a transição

Persista a referência interna do cliente, o identificador da tentativa do fornecedor, o fluxo de trabalho e a versão, as evidências ou referências relevantes, os códigos de razão, o histórico de eventos, a versão da política, a ação do revisor e a justificação final. Minimize os dados sensíveis copiados quando uma referência durável é suficiente.

O modelo de estado que uma API deve expor

Um campo booleano verificado é demasiado pequeno para uma jornada real do cliente. Os estados úteis incluem frequentemente:

Estado	Significado	Ação típica da aplicação
Criado	A tentativa existe, mas a captura não começou	Apresentar ou reenviar a entrega segura
Em curso	O utilizador ou as verificações assíncronas estão ativas	Aguardar; não conceder acesso final
A aguardar entrada	São necessárias mais evidências ou ação do utilizador	Mostrar orientação de recuperação precisa
Repetição permitida	A captura ou a qualidade falhou de forma recuperável	Iniciar uma nova tentativa limitada
Em revisão	Um revisor treinado é responsável pelo caso	Manter o acesso pendente e expor o próximo passo esperado
Aprovado	As evidências necessárias cumpriram o fluxo de trabalho configurado	Aplicar a política da organização e a transição de estado
Recusado	As evidências falharam num controlo definido	Aplicar recurso, restrição ou caminho alternativo
Expirado ou abandonado	A tentativa terminou sem uma decisão	Permitir reinício controlado
Erro técnico	O sistema não conseguiu produzir evidências	Repetir ou reconciliar sem tratar como fraude

Cada estado terminal deve ter razões estruturadas. Códigos de máquina estáveis permitem política e análise; mensagens humanas localizadas ajudam utilizadores e revisores. RFC 9457 fornece um formato padrão para detalhes de problemas HTTP legíveis por máquina ao nível da interface.

Que evidências deve conter o resultado?

Evidências ao nível do documento

Inclua o tipo de evidência, país emissor, classe de documento, validade, consistência de campos, qualidade e indicadores de validação relevantes para o método. Deixe claro se o resultado veio de inspeção ótica, dados de chip, corroboração do emissor ou da base de dados, ou outra fonte.

Evidências de ligação do candidato

Mantenha a comparação facial, a vivacidade, a integridade da captura e a ligação de atributos de identidade separadas. Registre a referência utilizada e o limiar de decisão ou versão necessária para interpretação posterior, sem expor material biométrico desnecessário a todos os consumidores.

Evidências de risco e operacionais

Sinais de dispositivo, IP, velocidade, tentativa repetida ou fluxo de trabalho podem guiar a intensificação e a revisão. Não devem alterar silenciosamente os atributos de identidade. Preserve qual subsistema produziu cada razão.

Proveniência e versão

Os resultados podem mudar quando modelos, modelos de documentos, listas de observação ou políticas mudam. Armazene a versão do fornecedor, a versão do fluxo de trabalho, a hora da decisão, as referências de origem e se um humano reviu o caso.

Requisitos de segurança da API

As APIs de identidade processam dados pessoais e biométricos valiosos e expõem fluxos de negócios que os atacantes podem automatizar. O OWASP API Security Top 10 destaca riscos diretamente relevantes aqui: autorização de objeto quebrada, autenticação quebrada, exposição excessiva de propriedades, consumo irrestrito de recursos, automação de fluxo sensível, inventário de API deficiente e confiança insegura em APIs de terceiros.

Autenticação e autorização

Use credenciais e aplicações separadas para teste e produção. Aplique o princípio do menor privilégio, rotação, revogação, isolamento de ambiente e autorização ao nível do objeto. Uma organização autenticada não deve conseguir obter a tentativa de outra organização alterando um identificador.

Controlos de upload e recursos

Valide o tipo de mídia, tamanho, dimensões, estrutura e fonte esperada. Defina tempos limite, limites de concorrência, controlos de taxa e limites de tentativa. As chamadas de verificação consomem computação e podem ter um custo por verificação, tornando os endpoints ilimitados um risco de negação de serviço e de custo.

Exposição de dados

Retorne apenas os campos de que um consumidor precisa. Separe as funções operacionais para que o suporte, analistas, programadores e administradores não recebam todos os dados de identidade completos por padrão. Redija cargas úteis sensíveis de registos e ferramentas de observabilidade.

Webhooks e controlos de repetição

Autentique eventos, preserve o corpo bruto necessário para a verificação de assinatura, rejeite entregas obsoletas ou malformadas, deduplique identificadores de eventos e obtenha o estado canónico. Rode os segredos do webhook sem interromper a entrega em curso.

Inventário e versionamento

Documente cada endpoint ativo, versão, host, credencial, callback, SDK e data de descontinuação. Um endpoint de teste sombra com dados de produção ou um SDK antigo e sem manutenção pode minar o caminho revisto.

Como testar uma API de verificação de ID

Testes de contrato e estado

Exercite cada estado documentado, razão, repetição, tempo limite e transição terminal. Verifique a paginação, filtragem, corpos de erro, compatibilidade retroativa e comportamento de campos desconhecidos. Simule webhooks duplicados e fora de ordem.

Testes de evidências

Use amostras permitidas e representativas em todos os tipos de documentos, países, scripts, condições de expiração, dispositivos, câmaras e redes na população esperada. Acompanhe separadamente evidências não suportadas, ilegíveis, incompatíveis, manipuladas e genuínas.

Testes de fraude

Crie um conjunto de ataques autorizado para repetições, evidências impressas, documentos alterados, câmaras virtuais, emuladores, mídia injetada, identidades repetidas e tentativas automatizadas. Os requisitos de prova remota do NIST distinguem a confiança do sensor de captura, a análise de mídia forjada, os canais protegidos e a comparação biométrica porque nenhum mecanismo cobre o caminho completo.

Testes operacionais

Meça a conclusão, repetições, abandono, taxa de revisão manual, tempo para resolução, contactos de suporte, atraso do webhook, reconciliação e disponibilidade. Divida os resultados por documento, dispositivo, rede, idioma e grupo de clientes relevante.

Testes de qualidade de decisão

Não compare fornecedores com um único número de "precisão". Revise falsos aceites e falsos rejeites no limiar pretendido, resultados específicos de ataques, contagens de amostras, confiança, casos sem resposta e resultados confirmados a jusante.

Testes de privacidade e eliminação

Verifique a configuração de retenção, exportação, eliminação, registos de acesso, tratamento regional, controlos de subprocessadores e comportamento quando um pedido de eliminação chega durante uma revisão aberta ou retenção legalmente exigida.

Como avaliar fornecedores

Âmbito e garantia

Quais funções de prova estão incluídas? Quais modelos de garantia e testes independentes se aplicam? Quais componentes e versões foram testados? O fornecedor pode explicar o que um "passa" significa e o que não significa?

Cobertura

Peça uma matriz de país e documento, não apenas um total. Teste as evidências que os seus clientes apresentam, incluindo dispositivos mais antigos, múltiplos scripts, câmaras de menor qualidade e documentos incomuns, mas legítimos.

Experiência do programador

Revise a consistência da API, a qualidade da OpenAPI, a manutenção do SDK, exemplos, cenários de sandbox, ferramentas de webhook, disciplina de registo de alterações, política de migração, página de status e escalonamento de suporte. Uma amostra de cinco linhas "happy-path" não é um guia de integração de produção.

Operações e explicabilidade

Inspecione filas de revisão, visualizações de evidências, permissões de função, registos de auditoria, códigos de razão, recursos e exportações. Confirme que os humanos podem distinguir falha técnica, repetição de qualidade, provável ataque e incompatibilidade de identidade.

Comercial e portabilidade

Compreenda a faturação baseada no sucesso versus baseada na tentativa, taxas de revisão, mínimos, limites, armazenamento, opções regionais e termos de saída. Mantenha a sua referência interna do cliente e o limite da política portáteis para que uma mudança de fornecedor não exija a reescrita do estado da conta.

Erros comuns de integração

Conceder acesso a partir do URL de retorno

O utilizador controla o caminho do navegador. Um redirecionamento de sucesso é um estado de interface, não uma prova. Confirme o estado final a partir do backend fiável.

Tratar cada falha como fraude

Negação de permissão, tempo limite, evidência não suportada, desfocagem e manipulação suspeita são diferentes. Misturá-los cria falsas recusas e análises inutilizáveis.

Processar webhooks exatamente uma vez

As redes não podem prometer uma entrega "exatamente uma vez". Projete para eventos "pelo menos uma vez" com deduplicação, transições monotónicas e recuperação canónica.

Registrar cargas úteis completas

O registo de debug conveniente pode copiar documentos e dados biométricos para sistemas com acesso mais amplo e retenção mais longa. Use identificadores, razões estruturadas e acesso controlado a evidências.

Testar apenas o caso de sucesso do sandbox

As falhas de produção ocorrem em repetições, dispositivos antigos, documentos de borda, atraso de eventos, alterações de versão e revisão. Torne os cenários de falha parte do conjunto de aceitação.

Terceirizar a decisão da política

Um resultado de fornecedor não pode conhecer todas as jurisdições, tipos de clientes, riscos de produtos ou restrições comerciais. Preserve a lógica de decisão e a responsabilidade da organização.

Uma lista de verificação de implementação

Antes da produção, confirme que:

• As credenciais da API permanecem no lado do servidor e têm âmbito por ambiente e função;
• As chamadas de criação são idempotentes e mapeadas para referências de cliente internas estáveis;
• Os tokens de captura são de curta duração e vinculados à tentativa esperada;
• Cada estado e razão tem uma ação explícita do cliente e do backend;
• As assinaturas de webhook, frescura, duplicados e ordenação são testadas;
• A recuperação canónica reconcilia eventos perdidos ou atrasados;
• As saídas ao nível da evidência permanecem separadas da decisão final do cliente;
• Os controlos de taxa, upload, concorrência e tentativa resistem ao abuso automatizado;
• Os testes de documento, dispositivo, fraude, privacidade, acessibilidade e revisão usam amostras semelhantes às de produção;
• Retenção, eliminação, resposta a incidentes, versionamento e migração têm responsáveis.

Usar o Didit para verificação de ID

O Didit fornece Verificação de ID como um módulo componível e permite que as equipas adicionem Deteção de Vivacidade, Análise de Dispositivo e IP, e caminhos condicionais através do Workflow Orchestrator. O preço publicado da Verificação de ID autónoma é de $0.15, enquanto o pacote KYC publicado de $0.33 combina Verificação de ID, Vivacidade Passiva, Correspondência Facial e Análise de IP.

A página de preços lista as taxas atuais dos módulos, e o nível gratuito é de 500 verificações gratuitas por mês. Esses resultados do produto devem alimentar uma política e um estado do cliente controlados pelo backend, em vez de os substituir.

Perguntas frequentes

O que é uma API de verificação de ID?

É uma interface programática para recolher ou submeter evidências de identidade e receber resultados estruturados sobre a validade das evidências e a ligação do candidato a uma identidade reivindicada.

Uma API de verificação de ID é o mesmo que uma API de KYC?

Não necessariamente. A verificação de ID foca-se nas evidências de identidade e na ligação do titular. Uma API de KYC pode também incluir triagem, risco do cliente, fluxos de trabalho, revisão, registos e atualização contínua.

A verificação de identidade deve ser executada a partir do frontend?

A interface de captura pode ser executada no frontend, mas as credenciais permanentes, a criação de sessão, a recuperação do resultado final, as decisões de política e as mudanças de estado do cliente pertencem a um backend fiável.

Por que são necessários webhooks?

Muitas verificações e revisões são assíncronas. Os webhooks notificam a aplicação sobre as alterações, enquanto um endpoint de recuperação fornece o estado canónico para reconciliação.

Como devem ser tratados os webhooks duplicados?

Verifique cada evento, armazene o seu identificador, processe-o idempotentemente, evite que estados mais antigos substituam estados terminais mais recentes e recupere a tentativa canónica quando necessário.

O que deve incluir um sandbox?

Deve reproduzir o contrato de produção e fornecer casos determinísticos para sucesso, repetição, recusa, revisão, expiração, erro técnico, eventos duplicados, eventos atrasados e códigos de razão relevantes.

Uma API pode tornar uma empresa conforme?

Não. Uma API pode fornecer evidências e resultados de fluxo de trabalho. A organização continua responsável pela análise legal, política, decisões do cliente, exceções, registos, privacidade e controlos contínuos.

Referências primárias

• NIST SP 800-63A-4: Prova de Identidade e Registo
• OWASP API Security Top 10 — 2023
• RFC 9110: Semântica HTTP
• RFC 9421: Assinaturas de Mensagens HTTP
• RFC 9457: Detalhes do Problema para APIs HTTP

Uma forte integração de verificação de ID torna cada limite de confiança explícito: quem cria a tentativa, como as evidências são capturadas, qual resultado é canónico, como os eventos são autenticados, o que cada razão significa e qual sistema é o responsável pela decisão final do cliente.