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

Uma API de verificação de identidade permite que um aplicativo colete ou envie evidências de identidade e receba resultados estruturados sobre uma pessoa declarada. Dependendo do fluxo de trabalho, ela pode validar um documento de identidade, extrair atributos, comparar um solicitante ao vivo com um retrato de referência, verificar vivacidade, corroborar dados ou orquestrar várias verificações em uma única sessão.

A resposta da API é uma evidência, não uma decisão de negócio completa. Uma integração de produção também deve definir captura confiável, propriedade do estado do cliente, transições de status, novas tentativas, revisão, privacidade, manutenção de registros e a política que transforma resultados técnicos em aprovar, tentar novamente, elevar, revisar ou recusar.

Principais pontos

• Uma API de verificação de identidade é mais do que um endpoint. O contrato real inclui captura, estados assíncronos, evidências, eventos, reconciliação, revisão e exclusão.
• O backend é o responsável pela decisão. Um redirecionamento de cliente ou uma tela de sucesso visual não é autoritário; o estado final deve ser confirmado no lado do servidor.
• Os resultados precisam de escopo e motivos. Autenticidade do documento, vínculo com o titular, vivacidade, qualidade e risco contextual devem permanecer separáveis em vez de se unirem em um booleano inexplicável.
• A confiabilidade aparece nos caminhos de falha. Idempotência, verificação de webhook, repetição de eventos, tempos limite, novas tentativas, versionamento e paridade de sandbox importam tanto quanto o caminho feliz.
• A avaliação deve usar populações semelhantes à 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 usuário relevante.

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

Uma API de verificação de identidade 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 solicitante 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 declarada 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 solicitante é o sujeito associado a essa evidência.

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

API de verificação de identidade, API de documento, API de KYC e OCR comparados

Interface	Propósito principal	Saída útil	O que não prova por si só
API de OCR	Converter pixels de documento em texto ou campos	Nome, data, número, endereço extraídos	Autenticidade, posse ou risco do cliente
API de verificação de documento	Validar um documento e suas evidências capturadas	Verificações de autenticidade, validade, consistência de campos, indicadores de adulteração	Que o solicitante atual o possui
API de comparação facial	Comparar um rosto enviado com uma referência	Similaridade ou decisão de correspondência em um limite	Vivacidade, autenticidade do documento ou identidade legal
API de vivacidade	Estimar a presença ao vivo na captura biométrica	Evidência de boa-fé, ataque, nova tentativa ou pontuação	A identidade da pessoa
API de verificação de identidade	Combinar validação de evidências e vínculo do solicitante	Resultados em nível de 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 registros	Conformidade automática sem política organizacional

Essa 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 a correspondência facial conecta duas imagens, mas não pode estabelecer se qualquer uma das imagens veio de uma captura confiável e ao vivo.

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

Modelos de integração comuns

Sessão de verificação hospedada

O backend do aplicativo cria uma sessão e recebe uma URL ou token de curta duração. O usuário completa a captura em uma jornada hospedada pelo provedor e, em seguida, retorna ao aplicativo. Este modelo pode reduzir a complexidade do frontend e do dispositivo, mantendo o controle do lado do servidor.

As principais questões incluem marca, transferência de domínio, acessibilidade, localização, suporte a navegadores móveis, expiração da sessão, comportamento de retorno e como o aplicativo é retomado quando o usuário troca de dispositivo.

SDK web ou móvel incorporado

Um SDK executa a experiência de captura dentro do aplicativo. Ele pode fornecer um controle de interface mais rigoroso e acesso aos recursos do dispositivo, mas a qualidade da integração afeta a segurança. O suporte à versão, a integridade do aplicativo, as permissões da câmera, o tratamento da câmera virtual, a política de atualização e a telemetria tornam-se parte da revisão.

Verificação autônoma servidor-para-servidor

O sistema do cliente envia dados estruturados ou mídia 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ção para o integrador.

Fluxo de trabalho orquestrado

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

Uma sequência de integração segura

1. Crie a tentativa a partir do backend

O backend confiável gera uma referência interna do cliente e chama o provedor com o fluxo de trabalho, localidade e contexto de política necessários. Não exponha credenciais de API permanentes em código de 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. Emita uma entrega de captura de curta duração

Forneça ao frontend apenas o token ou URL com escopo necessário para aquela tentativa. Vincule-o ao aplicativo esperado, referência do cliente, fluxo de trabalho e expiração. Evite colocar dados pessoais desnecessários em URLs, eventos de análise ou logs de cliente.

3. Capture e valide evidências

Guie o usuário através das evidências suportadas e requisitos de qualidade. Separe problemas de qualidade recuperáveis de ataques suspeitos. “Aproxime-se”, “documento expirado” e “falha na integridade da captura” não devem se tornar um erro genérico.

4. Receba um evento autenticado

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

Armazene identificadores de eventos e processe-os de forma idempotente. Os sistemas de entrega tentam novamente; eventos duplicados são normais. Não presuma a ordem de chegada e não deixe que um evento mais antigo mova um cliente para trás de um estado terminal.

5. Recupere o resultado canônico

Após um evento de conclusão, busque a tentativa final da API do provedor. Esta etapa de reconciliação reduz a dependência do conteúdo de um único webhook e se recupera de entregas perdidas ou atrasadas.

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

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

7. Registre a transição

Persista a referência interna do cliente, o identificador de tentativa do provedor, 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 justificativa final. Minimize os dados sensíveis copiados quando uma referência durável for suficiente.

O modelo de estado que uma API deve expor

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

Estado	Significado	Ação típica do aplicativo
Criado	Tentativa existe, mas a captura não começou	Apresentar ou reenviar a entrega segura
Em progresso	O usuário ou as verificações assíncronas estão ativas	Aguardar; não conceder acesso final
Aguardando entrada	Mais evidências ou ação do usuário são necessárias	Mostrar orientação precisa de recuperação
Nova tentativa permitida	A captura ou a qualidade falhou de forma recuperável	Iniciar uma nova tentativa limitada
Em revisão	Um revisor treinado é o responsável pelo caso	Manter o acesso pendente e expor o próximo passo esperado
Aprovado	A evidência necessária atendeu ao fluxo de trabalho configurado	Aplicar política organizacional e transição de estado
Recusado	A evidência falhou em um controle 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 pôde produzir evidências	Tentar novamente ou reconciliar sem tratá-lo como fraude

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

Que evidências o resultado deve conter?

Evidências em nível de documento

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

Evidências de vínculo do solicitante

Mantenha a comparação facial, vivacidade, integridade da captura e vínculo de atributo de identidade separados. Registre a referência usada e o limite de decisão ou versão necessário 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 elevação e a revisão. Eles 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ítica mudam. Armazene a versão do provedor, a versão do fluxo de trabalho, o tempo da decisão, as referências da fonte e se um humano revisou 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 invasores 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 aplicativos separados para teste e produção. Aplique o princípio do menor privilégio, rotação, revogação, isolamento de ambiente e autorização em nível de objeto. Uma organização autenticada não deve ser capaz de recuperar a tentativa de outra organização alterando um identificador.

Controles de upload e recursos

Valide o tipo de mídia, tamanho, dimensões, estrutura e fonte esperada. Defina tempos limite, limites de concorrência, controles 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 que um consumidor precisa. Separe as funções operacionais para que suporte, analistas, desenvolvedores e administradores não recebam todas as evidências de identidade por padrão. Redija cargas sensíveis de logs e ferramentas de observabilidade.

Controles de webhook e 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 busque o estado canônico. Rotacione segredos de webhook sem interromper a entrega em andamento.

Inventário e versionamento

Documente cada endpoint ativo, versão, host, credencial, callback, SDK e data de desativação. Um endpoint de teste sombra com dados de produção ou um SDK antigo não mantido pode minar o caminho revisado.

Como testar uma API de verificação de identidade

Testes de contrato e estado

Exercite cada estado, razão, nova tentativa, tempo limite e transição terminal documentados. Verifique paginação, filtragem, corpos de erro, compatibilidade com versões anteriores e comportamento de campos desconhecidos. Simule webhooks duplicados e fora de ordem.

Testes de evidência

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

Testes de fraude

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

Testes operacionais

Meça a conclusão, novas tentativas, abandono, taxa de revisão manual, tempo para resolução, contatos de suporte, atraso de 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 provedores com um único número de “precisão”. Revise falsos aceites e falsos rejeites no limite pretendido, resultados específicos de ataque, contagens de amostras, confiança, casos sem resposta e resultados confirmados a jusante.

Testes de privacidade e exclusão

Verifique a configuração de retenção, exportação, exclusão, logs de acesso, tratamento regional, controles de subprocessadores e comportamento quando uma solicitação de exclusão chega durante uma revisão aberta ou retenção legalmente exigida.

Como avaliar provedores

Escopo 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 provedor pode explicar o que um "passou" 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 seus clientes apresentam, incluindo dispositivos mais antigos, vários scripts, câmeras de menor qualidade e documentos incomuns, mas legítimos.

Experiência do desenvolvedor

Revise a consistência da API, a qualidade do OpenAPI, a manutenção do SDK, exemplos, cenários de sandbox, ferramentas de webhook, disciplina de changelog, política de migração, página de status e escalonamento de suporte. Uma amostra de “caminho feliz” de cinco linhas 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, logs de auditoria, códigos de razão, recursos e exportações. Confirme se os humanos podem distinguir falha técnica, nova tentativa de qualidade, ataque provável e incompatibilidade de identidade.

Comercial e portabilidade

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

Erros comuns de integração

Conceder acesso a partir da URL de retorno

O usuário 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 confiável.

Tratar toda falha como fraude

Negação de permissão, tempo limite, evidência não suportada, desfoque 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 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 registro de depuração 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 novas tentativas, dispositivos antigos, documentos de borda, atraso de eventos, mudanças de versão e revisão. Torne os cenários de falha parte do pacote de aceitação.

Terceirizar a decisão 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.

Um checklist de implementação

Antes da produção, confirme que:

• As credenciais da API permanecem no lado do servidor e têm escopo 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 têm curta duração e estão vinculados à tentativa esperada;
• Cada estado e razão tem uma ação explícita do cliente e do backend;
• As assinaturas de webhook, frescor, duplicatas e ordem são testadas;
• A recuperação canônica reconcilia eventos perdidos ou atrasados;
• As saídas em nível de evidência permanecem separadas da decisão final do cliente;
n
• Os controles 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 à produção;
• Retenção, exclusão, resposta a incidentes, versionamento e migração têm responsáveis.

Usando Didit para verificação de identidade

A Didit oferece Verificação de Identidade como um módulo combinável e permite que as equipes adicionem Detecção de Vivacidade, Análise de Dispositivo e IP e caminhos condicionais através do Orquestrador de Fluxo de Trabalho. O preço publicado da Verificação de Identidade autônoma é de $0.15, enquanto o pacote KYC publicado de $0.33 combina Verificação de Identidade, Vivacidade Passiva, Comparação Facial e Análise de IP.

A página de preços lista as taxas atuais dos módulos, e a camada gratuita é de 500 verificações gratuitas por mês. Esses resultados de produto devem alimentar uma política e um estado de cliente de propriedade do backend, em vez de substituí-los.

Perguntas frequentes

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

É uma interface programática para coletar ou enviar evidências de identidade e receber resultados estruturados sobre a validade da evidência e o vínculo do solicitante a uma identidade declarada.

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

Não necessariamente. A verificação de identidade foca em evidências de identidade e vínculo com o titular. Uma API de KYC também pode incluir triagem, risco do cliente, fluxos de trabalho, revisão, registros e atualização contínua.

A verificação de identidade deve ser executada no frontend?

A interface de captura pode ser executada no frontend, mas as credenciais permanentes, a criação da 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 confiável.

Por que os webhooks são necessários?

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

Como os webhooks duplicados devem ser tratados?

Verifique cada evento, armazene seu identificador, processe-o de forma idempotente, impeça que estados mais antigos substituam estados terminais mais recentes e recupere a tentativa canônica quando necessário.

O que um sandbox deve incluir?

Ele deve reproduzir o contrato de produção e fornecer casos determinísticos para sucesso, nova tentativa, 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 compatível?

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

Referências primárias

• NIST SP 800-63A-4: Prova de Identidade e Registro
• 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 identidade torna explícita cada fronteira de confiança: quem cria a tentativa, como a evidência é capturada, 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.