> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Fluxo completo da API: guia de integração KYC > Integre a API REST da Didit de ponta a ponta: crie a sessão, compartilhe o link, receba webhooks e obtenha decisões KYC em minutos. Este guia mostra o fluxo completo para integrar a verificação de identidade da Didit pela API REST: obter as credenciais, criar uma sessão, apresentá-la ao usuário e receber os resultados. *** ## Etapa 1: Obtenha suas credenciais Há duas formas de obter uma `api_key`: ### Opção A: Registro programático (sem navegador) Ideal para CI/CD e agentes de IA. Duas chamadas de API, `POST /programmatic/register/` e depois `POST /programmatic/verify-email/`, retornam a `api_key` inline. → Consulte [Registro programático](https://docs.didit.me/pt-br/integration/programmatic-registration.md) para ver o fluxo completo, as regras de senha, a validade do JWT e a política de bloqueio. ### Opção B: Pelo Didit Console 1. Acesse o [Didit Console](https://business.didit.me). 2. Crie ou selecione sua organização. 3. Navegue até **Settings** → **API & Webhooks**. 4. Copie: * **API Key**: usada como cabeçalho `x-api-key` em todas as chamadas de verificação. * **Webhook Secret Key**: usada para verificar as assinaturas HMAC dos webhooks. ### Variáveis de ambiente ```bash theme={null} # Required DIDIT_API_KEY=your_api_key_here DIDIT_WEBHOOK_SECRET=your_webhook_secret_here # Your workflow ID (from the Console) DIDIT_WORKFLOW_ID=your_workflow_id_here ``` *** ## Etapa 2: Crie um fluxo de verificação Antes de criar sessões, você precisa de um fluxo de verificação (workflow). Os fluxos definem as etapas de verificação pelas quais os usuários passam. ### Criar no Console 1. Acesse o [Didit Console](https://business.didit.me) → **Workflows** 2. Clique em **Create Workflow** 3. Escolha um modelo base: | Modelo | Ideal para | | - | - | | **KYC** | Verificação de identidade completa com documento de identidade | | **Adaptive Age Verification** | Verificação de idade com documento de identidade opcional como recurso alternativo | | **Biometric Authentication** | Reverificação de usuários recorrentes | | **Address Verification** | Verificação de comprovante de endereço | 4. Adicione recursos opcionais: | Recurso | Descrição | | - | - | | Verificação NFC | Lê os dados do chip do passaporte ou documento de identidade | | Prova de vida | Evita spoofing com vídeo de selfie | | Correspondência facial | Compara a selfie com a foto do documento | | Verificação de telefone | Verifica o número de telefone por SMS | | Verificação de e-mail | Verifica o endereço de e-mail | | Análise AML | Verifica em listas de sanções e de PEP | | Validação de banco de dados | Verifica em bancos de dados governamentais | | Análise de dispositivo e IP | Detecta VPNs, proxies e geolocalização | 5. Copie o seu **Workflow ID** > [!NOTE] > > Consulte a [documentação de fluxos](https://docs.didit.me/pt-br/console/workflows.md) para ver as > opções de configuração em detalhes. *** ## Etapa 3: Criar uma sessão de verificação Chame a API para criar uma sessão para o seu usuário. ### Requisição ```bash theme={null} curl -X POST https://verification.didit.me/v3/session/ \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "workflow_id": "your-workflow-id", "callback": "https://yourapp.com/verification-complete", "vendor_data": "user-123" }' ``` ### Parâmetros da requisição | Parâmetro | Obrigatório | Descrição | | - | - | - | | `workflow_id` | Sim | O UUID do seu fluxo, obtido no Console. | | `callback` | Não | URL para a qual o usuário é enviado após a verificação. A Didit acrescenta `verificationSessionId` e `status` como parâmetros de consulta. Aceita esquemas personalizados (por exemplo, `myapp://`). Quando omitido, usa a URL de retorno configurada no fluxo. | | `callback_method` | Não | Qual dispositivo trata o redirecionamento: `initiator`, `completer` ou `both`. Padrão: `initiator`. | | `vendor_data` | Não | O identificador interno do seu usuário, devolvido nos webhooks para correlação. | | `metadata` | Não | Objeto JSON arbitrário armazenado com a sessão e devolvido nos webhooks. | | `language` | Não | Indicação do idioma da interface (ISO 639-1, por exemplo, `en`, `es`). Quando omitido, o idioma do navegador é detectado automaticamente. | | `contact_details` | Não | E-mail/telefone do usuário para pré-preenchimento e notificações por e-mail. | | `expected_details` | Não | Dados esperados do usuário para validação cruzada com os dados verificados. | | `portrait_image` | Condicional | Imagem do rosto codificada em Base64 (máx. 2MB; JPEG, PNG, WebP ou TIFF). Imagem facial de referência para fluxos de autenticação biométrica ou Face-Match-first. Opcional quando o usuário de `vendor_data` já tem um rosto armazenado (rosto aprovado na prova de vida, foto do passaporte eletrônico, retrato do documento de identidade ou rosto de perfil cadastrado): a Didit o reutiliza automaticamente; retorna `400` se nenhum dos dois estiver disponível. | | `sandbox_scenario` | Não | Slug de cenário exclusivo do sandbox (por exemplo, `approve`, `decline_aml_hit`) que preenche automaticamente a sessão com valores mágicos. | ### Exemplo completo com todas as opções ```bash theme={null} curl -X POST https://verification.didit.me/v3/session/ \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "workflow_id": "11111111-2222-3333-4444-555555555555", "callback": "https://yourapp.com/verification-complete", "vendor_data": "user-123", "metadata": { "plan": "premium", "signup_source": "mobile-app" }, "contact_details": { "email": "alex.sample@example.com", "email_lang": "en", "send_notification_emails": true, "phone": "+15550101000" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-01-01", "expected_document_types": ["P", "ID"] } }' ``` > [!NOTE] > > `expected_details.expected_document_types` restringe a etapa de verificação > de identidade a tipos de documento específicos: a tela de seleção de documento > mostra apenas os tipos solicitados. Valores permitidos: `P` (passaporte), `ID` > (documento nacional de identidade), `DL` (carteira de motorista), `RP` > (autorização de residência), `HIC` (cartão de plano de saúde), `TC` (cartão > fiscal), `SSC` (cartão de seguridade social). Os valores não diferenciam > maiúsculas de minúsculas e duplicatas são removidas; valores desconhecidos > retornam `400`. Consulte a > [referência de Create Session](https://docs.didit.me/pt-br/sessions-api/create-session.md) para ver o esquema completo. ### Resposta `201 Created`: ```json theme={null} { "session_id": "11111111-2222-3333-4444-555555555555", "session_number": 43762, "session_token": "3FaJ9wLqX2Mz", "url": "https://verify.didit.me/session/3FaJ9wLqX2Mz", "vendor_data": "user-123", "metadata": { "plan": "premium", "signup_source": "mobile-app" }, "status": "Not Started", "workflow_id": "11111111-2222-3333-4444-555555555555", "workflow_version": 3, "callback": "https://yourapp.com/verification-complete" } ``` ### Principais campos da resposta | Campo | Descrição | | - | - | | `session_id` | UUID exclusivo desta sessão. Use-o em `GET /v3/session/{sessionId}/decision/` e nos webhooks. | | `session_number` | Número sequencial legível exibido no console da Didit. | | `session_token` | Token de 12 caracteres compatível com URLs que autoriza o usuário final a abrir o fluxo hospedado e inicializa os SDKs nativos (o SDK web recebe `url` em vez dele). Trate-o como um segredo. | | `url` | URL de verificação hospedada para onde redirecionar o usuário ou para incorporar em um iframe. (O nome do campo é `url`, não `verification_url`.) Quando a requisição inclui `language`, a URL contém um segmento de caminho com o idioma, por exemplo, `https://verify.didit.me/en/session/3FaJ9wLqX2Mz`. | | `status` | Status atual: `"Not Started"` para uma sessão recém-criada. | | `workflow_id` | Identificador estável do fluxo em que a sessão é executada. | | `workflow_version` | Versão publicada do fluxo à qual a sessão foi vinculada na criação. | > [!NOTE] > > **Idempotência.** Quando `vendor_data` é informado e já existe uma sessão não > concluída (`Not Started`, `In Progress`, `Resubmitted` ou `Awaiting User`) com > o mesmo `vendor_data` na versão publicada mais recente do fluxo, essa sessão > existente é retornada (ainda com `201`) em vez de ser criada uma duplicata, > com `callback` e `metadata` atualizados para os novos valores e `status` > refletindo a sessão existente. > [!NOTE] > > **A ausência de `x-api-key` retorna `403`** com > `{"detail": "You do not have permission to perform this action."}`, o > mesmo corpo de uma chave válida sem permissão. Uma chave incorreta, revogada > ou expirada retorna `401`. Créditos insuficientes retornam > `400`. Consulte a [referência da API Create Session](https://docs.didit.me/pt-br/sessions-api/create-session.md) para ver a > documentação completa. *** ## Etapa 4: Apresentar a verificação ao usuário Escolha como apresentar o fluxo de verificação ao seu usuário: ### Opção A: SDK nativo (recomendado para dispositivos móveis) Use o `session_token` com os SDKs nativos para integração com câmera, NFC e biometria. → [SDK para iOS](https://docs.didit.me/pt-br/integration/native-sdks/ios-sdk.md) · [SDK para Android](https://docs.didit.me/pt-br/integration/native-sdks/android-sdk.md) · [React Native](https://docs.didit.me/pt-br/integration/native-sdks/react-native-sdk.md) · [Flutter](https://docs.didit.me/pt-br/integration/native-sdks/flutter-sdk.md) ### Opção B: iframe InContext (recomendado para web) Incorpore a verificação na sua página usando a `url` retornada na Etapa 3. ```html theme={null} ``` → [iframe InContext](https://docs.didit.me/pt-br/integration/web-sdks/incontext-iframe.md) ### Opção C: Redirecionamento Redirecione o usuário para a URL de verificação. ```javascript theme={null} window.location.href = session.url; ``` → [Redirecionamento web](https://docs.didit.me/pt-br/integration/web-sdks/web-redirect.md) ### Opção D: WebView em dispositivos móveis Para aplicativos móveis sem SDK nativo. ```jsx theme={null} // React Native ``` → [WebView no iOS/Android](https://docs.didit.me/pt-br/integration/web-sdks/webview-in-ios-android.md) *** ## Etapa 5: receber os resultados ### Via webhook (recomendado) Os webhooks notificam seu servidor em tempo real quando o status da verificação muda. **Configuração:** 1. Crie um destino do webhook no [Console](https://business.didit.me) (**API & Webhooks**) ou via [`POST /v3/webhook/destinations/`](https://docs.didit.me/pt-br/management-api/webhook/create-destination) com `webhook_version: "v3"` e um array `subscribed_events` (por exemplo, `["status.updated"]`) 2. Guarde o `secret_shared_key` retornado na criação: ele é o segredo HMAC de todas as variantes de assinatura 3. Implemente um endpoint de webhook no seu servidor **Exemplo de payload de webhook:** Dentro de `decision`, cada resultado por recurso é entregue como um **array no plural** (`id_verifications[]`, `nfc_verifications[]`, `liveness_checks[]`, `face_matches[]`, …), com uma entrada por nó do fluxo. Esse é o contrato da V3 e é inviolável: nunca escreva código que dependa de uma chave no singular como `nfc` / `id_verification` / `liveness`. ```json theme={null} { "event_id": "9c0c8b8a-1111-4222-9333-444444444444", "webhook_type": "status.updated", "timestamp": 1774970000, "created_at": 1774969994, "application_id": "11111111-2222-3333-4444-555555555555", "environment": "live", "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "Approved", "workflow_id": "22222222-3333-4444-5555-666666666666", "workflow_version": 4, "vendor_data": "user-123", "metadata": { "plan": "premium" }, "decision": { "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "Approved", "id_verifications": [ { "node_id": "id_verification_1", "status": "Approved", "document_type": "Passport", "warnings": [] } ], "liveness_checks": [ { "node_id": "liveness_1", "status": "Approved", "method": "PASSIVE", "score": 95.4, "warnings": [] } ], "face_matches": [ { "node_id": "face_match_1", "status": "Approved", "score": 96.1, "warnings": [] } ], "reviews": [] } } ``` O objeto `decision` só está presente quando `status` é `Approved`, `Declined`, `In Review` ou `Abandoned` (um evento `Resubmitted` traz `resubmit_info` no lugar dele). A Didit reutiliza o mesmo `event_id` entre novas tentativas e entre destinos de fan-out, então baseie sua idempotência nele. Consulte [Modelos de dados](https://docs.didit.me/pt-br/reference/data-models.md) para ver todos os arrays no plural e todos os campos. **Verifique a assinatura (X-Signature-V2, recomendado):** `X-Signature-V2` é um HMAC-SHA256 calculado sobre uma recodificação canônica do corpo JSON: floats com valor inteiro reduzidos a ints, chaves ordenadas recursivamente, separadores compactos e Unicode preservado. ```javascript theme={null} const crypto = require("crypto"); // Match Didit's float normalisation: whole-valued floats serialise as ints. function shortenFloats(data) { if (Array.isArray(data)) return data.map(shortenFloats); if (data !== null && typeof data === "object") { return Object.fromEntries( Object.entries(data).map(([key, value]) => [key, shortenFloats(value)]) ); } return data; } // Sort object keys recursively before re-stringifying. function sortKeys(obj) { if (Array.isArray(obj)) return obj.map(sortKeys); if (obj !== null && typeof obj === "object") { return Object.keys(obj).sort().reduce((acc, key) => { acc[key] = sortKeys(obj[key]); return acc; }, {}); } return obj; } function verifyWebhook(rawBody, signatureV2, timestamp, secret) { // 1. Reject anything older than 5 minutes const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false; // 2. Recompute HMAC-SHA256 against the canonical JSON Didit signs const canonical = JSON.stringify(sortKeys(shortenFloats(JSON.parse(rawBody)))); const expected = crypto.createHmac("sha256", secret).update(canonical, "utf8").digest("hex"); // 3. Constant-time compare const a = Buffer.from(expected, "utf8"); const b = Buffer.from(signatureV2, "utf8"); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` → [Documentação completa de webhooks](https://docs.didit.me/pt-br/integration/webhooks.md), incluindo o `X-Signature` sobre os bytes brutos, o `X-Signature-Simple` obsoleto que cobre apenas o envelope e como escolher entre eles. A Didit tenta novamente as entregas que falham (`5xx`, `404`, timeout) até 2 vezes (após \~1 min e depois \~4 min) e encerra a espera após **5 segundos**, então retorne `2xx` rapidamente. ### Via API (opcional) Busque o mesmo payload de decisão a qualquer momento: ```bash theme={null} curl https://verification.didit.me/v3/session/{session_id}/decision/ \ -H "x-api-key: YOUR_API_KEY" ``` O formato da resposta (arrays no plural) é idêntico ao do objeto `decision` dentro do payload do webhook, e o endpoint pode ser chamado em qualquer ponto do ciclo de vida da sessão. Use webhooks para atualizações em tempo real e reserve as chamadas à API para preenchimento retroativo, auditoria e reconstruções. O endpoint `/decision/` tem limite de requisições de 600 requisições GET/min por chave de API (consulte [Limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md)). Semântica de erros: um `session_id` desconhecido retorna `404` com `{"detail": "Not found."}`, e falhas de autenticação aparecem como `403`. Este endpoint nunca retorna `401`. As URLs de mídia na resposta são links pré-assinados de curta duração: baixe o conteúdo logo, em vez de armazenar os links. → [Referência da API de consulta de sessão](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md) *** ## Exemplos de código completos ### Node.js / Express ```javascript theme={null} const express = require("express"); const crypto = require("crypto"); const app = express(); // Create verification session app.post("/api/verify", async (req, res) => { const { userId } = req.body; const response = await fetch("https://verification.didit.me/v3/session/", { method: "POST", headers: { "x-api-key": process.env.DIDIT_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ workflow_id: process.env.DIDIT_WORKFLOW_ID, callback: `${process.env.APP_URL}/verification-complete`, vendor_data: userId, }), }); const session = await response.json(); // Store session_id associated with user await db.users.update({ where: { id: userId }, data: { verificationSessionId: session.session_id }, }); res.json({ verificationUrl: session.url, // hosted verification URL sessionToken: session.session_token, // for native/web SDKs }); }); // Handle webhook — uses verifyWebhook / shortenFloats / sortKeys from Step 5 app.post( "/api/webhook", express.raw({ type: "application/json" }), (req, res) => { const signature = req.get("X-Signature-V2"); const timestamp = req.get("X-Timestamp"); if ( !verifyWebhook( req.body.toString("utf8"), signature, timestamp, process.env.DIDIT_WEBHOOK_SECRET, ) ) { return res.status(401).json({ error: "Invalid signature" }); } const payload = JSON.parse(req.body); const { event_id, session_id, status, vendor_data } = payload; // Idempotency: the same event_id is reused on retries and fan-out. // Skip events you have already processed (e.g. a processed_events table). // Update user's verification status (status values are case-sensitive strings) if (status === "Approved") { db.users.update({ where: { id: vendor_data }, data: { isVerified: true, verifiedAt: new Date() }, }); } // Return 2xx quickly (Didit's delivery timeout is 5s); do heavy work asynchronously res.json({ received: true }); }, ); app.listen(3000); ``` ### Python / FastAPI ```python theme={null} from fastapi import FastAPI, Request, HTTPException import httpx import hashlib import hmac import json import os import time app = FastAPI() @app.post("/api/verify") async def create_verification(user_id: str): async with httpx.AsyncClient() as client: response = await client.post( "https://verification.didit.me/v3/session/", headers={ "x-api-key": os.environ["DIDIT_API_KEY"], "Content-Type": "application/json" }, json={ "workflow_id": os.environ["DIDIT_WORKFLOW_ID"], "callback": f"{os.environ['APP_URL']}/verification-complete", "vendor_data": user_id } ) session = response.json() return { "verification_url": session["url"], # hosted verification URL "session_token": session["session_token"], # for native/web SDKs } def shorten_floats(data): """Match Didit: whole-valued floats serialise as ints.""" if isinstance(data, dict): return {k: shorten_floats(v) for k, v in data.items()} if isinstance(data, list): return [shorten_floats(x) for x in data] if isinstance(data, float) and data.is_integer(): return int(data) return data @app.post("/api/webhook") async def handle_webhook(request: Request): payload = await request.json() signature = request.headers.get("X-Signature-V2") timestamp = request.headers.get("X-Timestamp") # Verify timestamp freshness if not signature or not timestamp or abs(int(time.time()) - int(timestamp)) > 300: raise HTTPException(status_code=401, detail="Request too old") # Recompute Didit's V2 canonical JSON: shortened floats, sorted keys, # compact separators, Unicode preserved (ensure_ascii=False) canonical = json.dumps( shorten_floats(payload), sort_keys=True, separators=(",", ":"), ensure_ascii=False, ) expected = hmac.new( os.environ["DIDIT_WEBHOOK_SECRET"].encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256 ).hexdigest() if not hmac.compare_digest(signature, expected): raise HTTPException(status_code=401, detail="Invalid signature") # Idempotency: dedupe on payload["event_id"] (reused on retries) if payload["status"] == "Approved": # Update user in database pass return {"received": True} ``` *** ## Status da sessão Estes são os 10 valores possíveis de `status`. São strings exatas, que diferenciam maiúsculas de minúsculas (observe que `Kyc Expired` usa apenas o `K` maiúsculo): | Status | Descrição | | - | - | | `Not Started` | Sessão criada, mas o usuário ainda não abriu o link. | | `In Progress` | O usuário está concluindo a verificação neste momento. | | `In Review` | Verificação sinalizada para revisão humana. | | `Approved` | Todas as verificações foram aprovadas. | | `Declined` | Uma ou mais verificações falharam. | | `Resubmitted` | O revisor pediu que etapas específicas fossem refeitas. | | `Awaiting User` | Sessão KYB principal aguardando a conclusão das partes KYC vinculadas. | | `Abandoned` | O usuário começou, mas não terminou no tempo previsto. | | `Expired` | A sessão expirou antes de o usuário abrir o link. | | `Kyc Expired` | Sessão aprovada anteriormente cujo documento expirou. | Consulte [Status de verificação](https://docs.didit.me/pt-br/integration/verification-statuses.md) para ver o ciclo de vida completo, as transições e o diagrama Mermaid. *** ## Próximos passos 1. **Escolha seu método de integração**: * Aplicativos móveis → [SDKs nativos](https://docs.didit.me/pt-br/integration/native-sdks/overview.md) * Aplicações web → [SDKs web](https://docs.didit.me/pt-br/integration/web-sdks/overview.md) 2. **Configure webhooks**: [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md) 3. **Planeje a capacidade**: [Limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md) 4. **Trate todos os status**: [Status de verificação](https://docs.didit.me/pt-br/integration/verification-statuses.md) 5. **Personalize seu fluxo**: [Fluxos](https://docs.didit.me/pt-br/console/workflows.md) 6. **Verifique se a API está acessível**: [Healthcheck](https://docs.didit.me/pt-br/api-reference/healthcheck.md) ## Precisa de ajuda? * **Suporte**: [support@didit.me](mailto:support@didit.me) * **Onboarding programático**: [Cadastro programático](https://docs.didit.me/pt-br/integration/programmatic-registration.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.