Guia: como integrar uma API de KYC em 1 dia (passo a passo técnico)

Key takeaways (TL; DR)
 

Com a Didit, é possível integrar verificação completa de identidade em poucas horas e lançar hoje mesmo.

Comece rápido com um fluxo No-Code e, à medida que o projeto cresce, amplie com a API para ter mais flexibilidade.

O plano principal de KYC é gratuito e ilimitado, permitindo escalar sem custos adicionais desde o primeiro dia.

A plataforma foi pensada para não quebrar a experiência do usuário e, ao mesmo tempo, atender às exigências de conformidade.

Integrar uma KYC API costuma ser bem mais complicado do que deveria. Muitas vezes, a documentação técnica deixa lacunas em pontos críticos, os ambientes sandbox não se comportam como produção ou os webhooks falham sem explicação. Se você já passou por isso, este guia é para você.

Com a KYC API da Didit, você vai do zero à verificação completa de documentos e biometria em poucas horas. Estamos falando de Face Match 1:1 e Passive Liveness, além de tudo o que precisa para acompanhar, em tempo real, o status das verificações com webhooks assinados e um sandbox que se comporta como produção. Se quiser lançar ainda mais rápido, é possível orquestrar tudo com um fluxo de verificação No-Code e ir para produção em minutos.

E o melhor da KYC API da Didit? Ela é totalmente gratuita. Você poderá verificar identidades de forma gratuita e ilimitada, começando a escalar sua plataforma imediatamente.

Este guia é escrito por e para desenvolvedores: o objetivo é que seu fluxo de verificação funcione bem, com sessões aprovadas em poucos segundos e estados claros. Se você procurava “como integrar uma KYC API em um dia”, está no lugar certo.

O que é uma integração de KYC e por que ela é essencial para as empresas?

Integrar uma solução de KYC permite às empresas cumprir os requisitos de verificação de identidade por meio de um provedor de verificação de identidade. Essas integrações automatizam a validação de usuários, algo crucial para atender às normas de prevenção à lavagem de dinheiro (AML).

Normalmente, integrações de KYC são feitas via API (mais flexibilidade) ou com uma URL de verificação hospedada (mais rapidez). A escolha depende das necessidades do seu produto.

Por que o KYC é importante para as empresas?

1. Automatiza um processo que era manual. Equipes de conformidade gastavam horas conferindo dados de onboarding; agora isso pode ser feito, com segurança, em segundos.
2. Garante conformidade com normas de KYC. As regulações evoluem para combater fraudes cada vez mais sofisticadas. Uma KYC API ajuda a manter tudo atualizado e em conformidade.
3. Melhor proteção contra fraude. Uma API reduz passos manuais e erros humanos. Uma camada antifraude bloqueia identidades sintéticas, deepfakes e documentos alterados ou gerados por IA.
4. Otimização de processos. Ao reduzir trabalho manual, as equipes focam no que importa: revisar risco em tempo real e identificar padrões suspeitos.
5. Escalabilidade sem limites. Processos manuais criavam gargalos. O onboarding automatizado remove esse problema, permitindo acesso em segundos sem abrir mão de segurança e precisão.
6. Economia significativa. Integrar KYC reduz tempo, recursos e custos. Com a Didit, as economias podem chegar a 70% em relação a fornecedores legados.

Como integrar a KYC API da Didit (e ir para produção hoje)

A integração padrão com a Didit se baseia em um workflow hospedado pela Didit, uma sessão de verificação por usuário, uma URL de verificação para executar o fluxo e webhooks assinados para sincronizar estados em tempo real. O circuito mínimo é: criar a sessão com seu workflow_id, enviar o usuário para a url de verificação, receber o webhook com a decisão e, se necessário, consultar o resultado por API. Graças à modularidade da Didit, você pode adicionar camadas como AML Screening, Proof of Address ou Age Estimation sem reescrever a base.

Consulte a documentação completa (API Full Flow) se precisar de mais detalhes.

Antes de começar: API Key, Webhook Secret e configuração do Webhook

Acesse o Business Console (cadastro gratuito) e vá em API & Webhooks (na coluna à esquerda). Lá você obtém sua API Key (para se autenticar usando o cabeçalho X-Api-Key) e a Webhook Secret Key (para verificar a assinatura dos webhooks).

No mesmo painel, configure a Webhook URL que a Didit usará para notificar alterações de status.

Guarde esses valores em variáveis de ambiente (.env); devem ter este formato:

API_KEY=<YourApiKey>
WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>
WEBHOOK_URL=https://seuapp.com.br/api/webhooks/didit

Crie a sessão de verificação

O próximo passo é chamar o serviço de verificação. Este é um exemplo — substitua workflow_id, callback e API_KEY pelos seus valores reais.

POST /v2/session/
Host: verification.didit.me
Content-Type: application/json
X-Api-Key: {YourApiKey}

{
  "workflow_id": "11111111-2222-3333-4444-555555555555",  // Replace with your chosen workflow
  "callback": "<https://example.com/verification/callback>",
  "vendor_data": "usuario-123",  // Seu identificador de usuário
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "contact_details": {
    "email": "joao.souza@example.com",
    "email_lang": "pt",
    "phone": "+5511998765432"
  }
}

A resposta inclui, entre outros campos, o session_id, o status inicial e a url para direcionar os usuários ao fluxo hospedado pela Didit:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "usuario-123",
  "metadata": { "user_type": "premium", "account_id": "ABC123" },
  "status": "Not Started",
  "workflow_id": "example_workflow_id",
  "callback": "<https://example.com/verification/callback>",
  "url": "<https://verify.didit.me/session/abcdef123456>"
}

Você encontra mais detalhes e exemplos de código na seção Create Session da documentação técnica.

Execute a UI de verificação (redirecione ou incorpore)

Com a url de verificação, você pode redirecionar o usuário (opção mais simples) ou incorporar o fluxo em um <iframe> para manter seu layout. A Didit orquestra a captura de documento, selfie e liveness de acordo com seu workflow.

Ao finalizar cada etapa, a sessão avança de status e um webhook é enviado.

Resultados da sessão de verificação

Os resultados chegam de duas formas: Webhooks (recomendado) ou consulta por API sob demanda. Com webhooks, seu backend recebe notificações em tempo real sempre que o status da sessão muda — sem polling e com uma fonte única de verdade.

Para garantir a legitimidade do webhook, valide sempre a assinatura enviada no cabeçalho X-Signature usando sua WEBHOOK_SECRET_KEY. Além disso, verifique o cabeçalho X-Timestamp e rejeite requisições fora de uma janela curta (por exemplo, 5 minutos) para prevenir replay e fraude.

Na seção de Webhooks da documentação você encontra todos os detalhes e mais exemplos.

Se em algum momento precisar reconciliar estados (por exemplo, se um webhook não chegou), você pode consultar a decisão sob demanda:

GET <https://verification.didit.me/v2/session/{sessionId}/decision/>
X-Api-Key: <YourApiKey>

Mapeie os status de forma consistente no seu sistema (por exemplo: Not Started → In Progress → In Review → Approved / Declined / Abandoned) e reflita cada transição na UI e nas métricas. Isso evita ambiguidades entre produto, suporte e analytics.

Para mais controle e flexibilidade: APIs independentes de verificação

Quer mais controle sobre seu fluxo? As APIs independentes da Didit ajudam nisso. Além da KYC API — que permite verificar a identidade de forma integral (ID Verification, Face Match 1:1 e Passive Liveness) — você pode construir processos sob medida ou abordagens bem específicas, adicionando apenas as funcionalidades de que precisa.

O que você pode fazer com as APIs independentes da Didit?

• ID Verification: verificar um documento de identidade e extrair as informações essenciais.
• Face Match 1:1: comparar a foto do documento com uma selfie em tempo real.
• Age Estimation: estimar idade para um onboarding sem fricção em produtos com restrição etária.
• Proof of Address: verificar o endereço do usuário com base em documentos oficiais e contas de serviços.
• AML Screening: checar identidades em listas de vigilância, sanções, PEPs e mídia adversa.
• Face Search 1:N: buscar um rosto em uma base para impedir duplicidades.
• Passive Liveness: garantir presença real do usuário durante a verificação.
• Database Validation: validar identidade em bases nacionais e globais (verificação 1x1 e 2x2).
• Phone Verification: verificar números de telefone via códigos OTP.
• Email Verification: verificar e-mails via códigos OTP.

Quanto custa usar uma KYC API?

A Didit oferece o único plano gratuito e ilimitado de verificação de identidade. Isso significa que o custo de usar a KYC API é zero, quer você a utilize uma vez ou centenas de vezes.

Sem letras miúdas, contratos ou pacotes fechados. A Didit é uma alternativa simples, aberta, flexível e econômica, com economias de até 70% em relação a fornecedores consolidados. O modelo baseia-se em funcionalidades opcionais (AML Screening, Proof of Address, Phone/Email Verification etc.) e no uso das APIs independentes.

Confira os preços das APIs independentes.