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 de identidade completa em poucas horas e lançar hoje mesmo.

Começa com um fluxo rápido sem código e, quando o projeto crescer, expande com a API para ganhar 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 utilizador e, ao mesmo tempo, cumprir as exigências de conformidade.

Integrar uma API de KYC 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 sabes do que falamos, este guia é para ti.

Com a KYC API da Didit vais passar de zero a verificação completa de documentos e biometria em poucas horas. Falamos de Face Match 1:1 e Passive Liveness, além de tudo o necessário para controlares em tempo real o estado das verificações com webhooks assinados e um sandbox que se comporta como produção. Se preferires lançar ainda mais rápido, podes orquestrar tudo com um fluxo de verificação sem código (No-Code) e ir para produção em minutos.

Mas, sabes o que é melhor na KYC API da Didit? É totalmente gratuita. Poderás verificar identidades de forma gratuita e ilimitada, para começares a escalar a tua plataforma.

Tem em conta que este guia é escrito por e para developers: o objetivo é que o teu fluxo de verificação funcione bem, com sessões aprovadas em poucos segundos e estados claros. Se procuravas “como integrar uma API de KYC num dia”, estás no sítio certo.

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

Integrar uma solução de KYC permite às empresas cumprir os requisitos de verificação de identidade através de um fornecedor de verificação de identidade. Estas integrações automatizam a validação de utilizadores, essencial para as normas de combate ao branqueamento de capitais (AML).

Habitualmente, as integrações de KYC são feitas via API (mais flexibilidade) ou com uma URL de verificação alojada (mais rapidez). A escolha depende das necessidades do teu negócio.

Porque é importante o KYC para as empresas?

1. Automatiza um processo que era manual. As equipas de compliance podiam passar horas a verificar os dados fornecidos no onboarding; agora tudo pode ser feito, com segurança, em segundos.
2. Cumpre as normas de KYC. A regulação evolui para combater fraudes cada vez mais sofisticadas. Uma KYC API ajuda a garantir a conformidade, mantendo todas as verificações atualizadas e em regra.
3. Melhor proteção contra fraude. Usar uma KYC API elimina 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 equipas focam-se no que importa: rever perfis de risco em tempo real e detetar padrões suspeitos.
5. Escalabilidade sem limites. Processos manuais criavam estrangulamentos. O onboarding automatizado remove esse problema, permitindo acesso em segundos sem abdicar de segurança nem precisão.
6. Poupanças significativas. Integrar KYC reduz tempo, recursos e custos. Com a Didit, as poupanças podem chegar a 70% face a fornecedores legacy.

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

A integração padrão com a Didit assenta num workflow alojado pela Didit, uma sessão de verificação por utilizador, 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 o teu workflow_id, enviar o utilizador 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, podes adicionar camadas como AML Screening, Comprovativo de Morada (Proof of Address) ou Estimativa de Idade sem reescrever a base.

Consulta a documentação completa (API Full Flow) se precisares de mais detalhe.

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

Acede à Business Console (registo gratuito) e vai a API & Webhooks (na coluna da esquerda). Aí obterás a tua API Key (para autenticação no cabeçalho X-Api-Key) e a Webhook Secret Key (para validares a assinatura dos webhooks).

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

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

API_KEY=<YourApiKey>
WEBHOOK_SECRET_KEY=<YourWebhookSecretKey>
WEBHOOK_URL=https://a-tua-app.com/api/webhooks/didit

Cria a sessão de verificação

O passo seguinte é chamar o serviço de verificação. Este é um exemplo — substitui workflow_id, callback e API_KEY pelos teus dados 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": "utilizador-123",  // O teu identificador interno
  "metadata": {
    "user_type": "premium",
    "account_id": "ABC123"
  },
  "contact_details": {
    "email": "joao.silva@example.com",
    "email_lang": "pt",
    "phone": "+351912345678"
  }
}

A resposta inclui, entre outros campos, o session_id, o status inicial e a url para direcionares os utilizadores para o fluxo alojado pela Didit:

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "session_token": "abcdef123456",
  "vendor_data": "utilizador-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>"
}

Encontras mais informação e exemplos de código na secção Create Session da documentação técnica.

Executa a UI de verificação (redirige ou incorpora)

Com a url de verificação, podes redirigir o utilizador (opção mais simples) ou incorporar o fluxo num <iframe> para manteres o teu layout. A Didit orquestra a captura do documento, selfie e liveness conforme o teu workflow.

Ao concluir cada passo, a sessão avança de estado e é enviado um webhook.

Resultados da sessão de verificação

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

Para garantir a legitimidade do webhook, valida sempre a assinatura enviada no cabeçalho X-Signature usando a tua WEBHOOK_SECRET_KEY. Além disso, verifica o cabeçalho X-Timestamp e rejeita pedidos fora de uma janela curta (por exemplo, 5 minutos) para prevenir replay e fraude.

Na secção de Webhooks da documentação encontras todos os detalhes e mais exemplos.

Se em algum momento precisares de reconciliar estados (por exemplo, se um webhook não chegou), podes consultar a decisão sob demanda:

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

Mapeia os estados de forma consistente no teu sistema (por exemplo: Not Started → In Progress → In Review → Approved / Declined / Abandoned) e reflete cada transição na UI e nas métricas. Evita ambiguidades entre produto, suporte e analítica.

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

Procuras mais controlo sobre o teu fluxo? As APIs independentes da Didit ajudam-te a consegui-lo. Além da KYC API — que permite verificar a identidade de forma integral (ID Verification, Face Match 1:1 e Passive Liveness) — podes construir processos à medida ou abordagens muito específicas, adicionando apenas as funcionalidades de que precisas.

O que podes fazer com as APIs independentes da Didit?

• ID Verification: verifica um documento de identidade e extrai a informação essencial.
• Face Match 1:1: coteja a imagem do documento com uma selfie em tempo real.
• Age Estimation: estima a idade para um onboarding sem fricção em produtos com limites etários.
• Proof of Address: verifica a morada com base em documentação oficial e faturas de serviços.
• AML Screening: confronta identidades com listas de vigilância, sanções, PEPs e média adversa.
• Face Search 1:N: pesquisa um rosto numa base de dados para impedir duplicados.
• Passive Liveness: garante a presença real do utilizador durante a verificação.
• Database Validation: valida uma identidade contra bases nacionais e globais (verificação 1x1 e 2x2).
• Phone Verification: verifica números de telefone com códigos OTP.
• Email Verification: verifica e-mails com códigos OTP.

Quanto custa utilizar uma KYC API?

A Didit oferece o único plano gratuito e ilimitado de verificação de identidade. Isto significa que o custo de usar a KYC API é zero, independentemente de a utilizares uma única vez ou centenas de vezes.

Sem letras pequenas, contratos ou pacotes fixos. A Didit é uma alternativa simples, aberta, flexível e económica, com poupanças de até 70% face a alternativas consolidadas. O modelo baseia-se em funcionalidades opcionais (AML Screening, Proof of Address, Phone/Email Verification, etc.) e no uso das APIs independentes.

Consulta os preços das APIs independentes.