> ## 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. # API de gerenciamento v3: fluxos de trabalho e faturamento > A API de gerenciamento da Didit configura fluxos, questionários, usuários, faturamento e listas de bloqueio via chave de API. Pronta para MCP. ## Autenticação Todos os endpoints da API de gerenciamento usam a chave de API da sua aplicação. Não é preciso incluir UUIDs de organização ou de aplicação nas URLs: a aplicação é identificada pela sua chave. ```bash theme={null} curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/... ``` Ainda não tem uma chave de API? [Registre-se programaticamente em 2 chamadas de API](https://docs.didit.me/pt-br/integration/programmatic-registration.md). *** ## Fluxos de verificação (workflows) Os fluxos de verificação (workflows) definem as etapas de verificação pelas quais seus usuários passam (leitura do documento de identidade, prova de vida, correspondência facial, análise AML etc.). Cada fluxo é uma configuração reutilizável que você vincula às sessões. **GET /v3/workflows/** `GET` Lista todos os fluxos da sua aplicação. Retorna os recursos e limiares de cada fluxo e se ele é o padrão. **POST /v3/workflows/** `POST` Cria um novo fluxo. Defina quais recursos de verificação ativar, configure limiares, os tipos de documento aceitos e muito mais. **GET /v3/workflows/\{uuid}/** `GET` Obtém todos os detalhes de um fluxo específico, incluindo todas as configurações de recursos e limiares. **PATCH /v3/workflows/\{uuid}/** `PATCH` Atualiza a configuração de um fluxo. Você pode modificar qualquer configuração de recurso, limiar ou documento aceito. **DELETE /v3/workflows/\{uuid}/** `DELETE` Exclui um fluxo. As sessões que já usam esse fluxo não são afetadas. > [!WARNING] > > Recomendamos fortemente usar o **Business Console** para criar e configurar fluxos. O construtor visual de fluxos oferece modelos, configuração de recursos por arrastar e soltar, configurações de documentos, ajuste de limiares e pré-visualização, tudo sem escrever código. Use a API apenas para automação ou gerenciamento programático de fluxos. ### Exemplo rápido: criar um fluxo O `workflow_type` determina o conjunto base de recursos. Depois, cada recurso é ativado ou desativado com as flags `is_*_enabled`. ```bash theme={null} curl -X POST https://verification.didit.me/v3/workflows/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_face_match_enabled": true, "is_liveness_enabled": true, "is_aml_enabled": false }' ``` Valores disponíveis de `workflow_type`: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, `address_verification`, `questionnaire_verification`, `email_verification`, `phone_verification`. Nos fluxos `kyc`, a verificação de identidade é incluída automaticamente: você não precisa de uma flag separada para ela. Use as flags `is_*_enabled` para adicionar ou remover recursos opcionais, como correspondência facial, prova de vida, AML, NFC, telefone, e-mail, comprovante de endereço, Análise de dispositivo e IP e outros. Em seguida, use o fluxo ao criar sessões: ```bash theme={null} curl -X POST https://verification.didit.me/v3/session/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "callback_url": "https://myapp.com/callback", "workflow_id": "WORKFLOW_UUID_FROM_ABOVE" }' ``` *** ## Questionários Formulários personalizados que você pode adicionar aos fluxos de verificação para coletar informações adicionais dos usuários. **GET /v3/questionnaires/** `GET` Liste todos os questionários. **POST /v3/questionnaires/** `POST` Crie um novo questionário com perguntas personalizadas, lógica de ramificação e traduções. **GET /v3/questionnaires/\{uuid}/** `GET` Obtenha os detalhes do questionário, incluindo todas as perguntas e a estrutura do formulário. **PATCH /v3/questionnaires/\{uuid}/** `PATCH` Atualize um questionário. **DELETE /v3/questionnaires/\{uuid}/** `DELETE` Exclua um questionário. *** ## Usuários Gerencie as pessoas verificadas (usuários) da sua aplicação. Cada usuário é identificado por uma string `vendor_data` que você informa ao criar sessões. **GET /v3/users/** `GET` Lista todos os usuários da sua aplicação, incluindo o status de verificação e o histórico de sessões de cada um. **GET /v3/users/\{vendor\_data}/** `GET` Obtém os detalhes de um usuário pelo seu identificador vendor\_data. **PATCH /v3/users/\{vendor\_data}/** `PATCH` Atualiza os metadados do usuário. **POST /v3/users/delete/** `POST` Exclui usuários em lote. Corpo: `{"vendor_data_list": ["user-1", "user-2"]}` ou `{"delete_all": true}`. Também elimina permanentemente todos os templates biométricos retidos desses usuários. *** ## Templates biométricos Templates biométricos faciais, sem imagens, que uma aplicação que optou por esse recurso retém após excluir sessões. Consulte [Templates biométricos](https://docs.didit.me/pt-br/management-api/biometric-templates/overview.md). **GET /v3/biometric-templates/** `GET` Lista paginada com filtros (`vendor_data`, `vendor_user_uuid`, `status`, `source_type`, `retained_from`, `retained_to`, `ordering`). **GET /v3/biometric-templates/count/** `GET` Contagem com os mesmos filtros. **GET /v3/biometric-templates/\{template\_uuid}/** `GET` Um template: usuário proprietário, referência de procedência, validade, instrução e status. **DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE` Elimina permanentemente um template. Retorna `{"uuid": "...", "outcome": "purged" | "already_purged"}`. **POST /v3/biometric-templates/delete/** `POST` Eliminação permanente em massa. Corpo: `{"template_uuids": [...]}` ou `{"delete_all": true}`, além de filtros opcionais. *** ## Operações de sessão **POST /v3/sessions/delete/** `POST` Exclui sessões em lote. Requer `delete:sessions`. Corpo: `{"session_numbers": ["1", "2", "3"]}` ou `{"delete_all": true}` (restrinja o `delete_all` com os filtros de List Sessions prefixados com `filter_`, como `filter_status`), além dos parâmetros opcionais `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction` e `instruction_id`. Até 20 sessões correspondentes retornam `200` com um `face_retention_outcome` por sessão; acima disso, a resposta é `202` com um job de exclusão. **GET /v3/sessions/delete/\{job\_id}/** `GET` Progresso e contagens de resultados de uma exclusão de sessões em massa que retornou `202`. **GET /v3/sessions/\{uuid}/reviews/** `GET` Lista as revisões e o registro de atividades de uma sessão. **POST /v3/sessions/\{uuid}/reviews/** `POST` Adiciona uma nota de revisão ou uma alteração de status a uma sessão. *** ## Faturamento **GET /v3/billing/balance/** `GET` Obtém o saldo atual de créditos e as configurações de recarga automática. ```json theme={null} { "balance": "142.5000", "auto_refill_enabled": true, "auto_refill_amount": "100.0000", "auto_refill_threshold": "10.0000" } ``` **POST /v3/billing/top-up/** `POST` Cria uma sessão de checkout do Stripe para recarregar créditos. Cada recarga vai de \$50 a \$10,000 e é creditada pelo valor nominal. ```json theme={null} { "amount_in_dollars": 100, "success_url": "https://myapp.com/billing/success", "cancel_url": "https://myapp.com/billing/cancel" } ``` *** ## Listas (listas de bloqueio, listas de permissões e personalizadas) Gerencie listas classificadas por tipo para bloqueio, permissão e condições personalizadas de fluxo de verificação (workflow). Consulte a [documentação completa da API de listas](https://docs.didit.me/pt-br/management-api/lists/overview.md). **GET /v3/lists/** `GET` Lista todas as listas da aplicação (listas de bloqueio, listas de permissões e personalizadas). **POST /v3/lists/\{list\_uuid}/entries/** `POST` Adiciona uma entrada a uma lista. Aceita `reference_session_id` para extrair dados automaticamente de uma sessão e `reference_object_uuid` para rastreabilidade até transações, usuários ou empresas. **DELETE /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE` Remove uma entrada de uma lista. **POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST` Envia uma imagem de rosto para uma lista de bloqueio de rostos (base64). *** ## Configuração de webhook **GET /v3/webhook/** `GET` Obtém a configuração atual do webhook, incluindo URL, versão, a chave secreta para verificar as assinaturas do webhook e a política de retenção de dados e de retenção de templates biométricos da aplicação. A resposta também traz `allowed_domains`, descrito em `PATCH /v3/webhook/` abaixo. ```json theme={null} { "webhook_url": "https://myapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "whsec_a1b2c3d4e5f6...", "capture_method": "both", "data_retention_months": null, "face_retention_policy": "delete_with_session", "face_retention_days": null, "allowed_return_hosts": ["app.example.com"], "allowed_domains": ["https://app.example.com"] } ``` **PATCH /v3/webhook/** `PATCH` Atualiza a URL e a versão do webhook ou rotaciona a chave secreta. Defina `rotate_secret_key: true` para gerar um novo segredo do webhook (o antigo é invalidado imediatamente). Também define a política de retenção da aplicação: `data_retention_months` e `face_retention_policy` (`delete_with_session`, o padrão, ou `retain_until_user_deleted`), junto com um `face_retention_days` finito e obrigatório (1-3650) quando a retenção está ativada. Consulte [Retenção de templates biométricos](https://docs.didit.me/pt-br/console/data-retention.md#retenção-de-template-biométrico). Também registra `allowed_return_hosts`: até 20 nomes de host simples (por exemplo `app.example.com`, sem esquema, porta, caminho ou curinga) para os quais uma verificação da [API de carteira de Digital ID](https://docs.didit.me/pt-br/standalone-apis/digital-id-wallets.md#registre-o-seu-destino-de-retorno) pode enviar a pessoa de volta por HTTPS. Uma nova lista substitui a registrada, e o domínio de marca própria da sua aplicação é sempre permitido. Também define `allowed_domains`: até 50 origens web (por exemplo `https://app.example.com`) nas quais o fluxo de verificação hospedado pode ser incorporado e para as quais pode enviar o usuário de volta com um `callback` de sessão. Cada entrada é um esquema, um host e uma porta opcional, sem caminho, query ou curinga. Use `https`; `http` só é aceito para `localhost`, `127.0.0.1` e `::1`. A Didit armazena cada origem em letras minúsculas e sem porta padrão, e retorna a lista em `allowed_domains`. Uma entrada inválida resulta em erro 400 em `allowed_domains`. Uma nova lista substitui a registrada, e uma lista vazia remove a restrição. Enquanto a lista não estiver vazia, [`POST /v3/session/`](https://docs.didit.me/pt-br/sessions-api/create-session) rejeita com 400 um `callback` web fora dela, e o fluxo hospedado não redireciona o usuário para um callback armazenado ou padrão do fluxo que esteja fora dela. Esquemas de URL personalizados (deep links de apps) e chamadas de API entre servidores não são afetados. Se você enviar `endpoints`, todo destino do webhook que ficar fora da lista é excluído permanentemente, junto com seu segredo de assinatura e todo o seu registro de entregas, exatamente como [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/pt-br/management-api/webhook/delete-destination). Isso não pode ser desfeito. Para gerenciar os destinos um de cada vez, use os [endpoints de destino do webhook](https://docs.didit.me/pt-br/management-api/webhook/list-destinations.md). ```json theme={null} { "webhook_url": "https://myapp.com/webhooks/didit", "webhook_version": "v3", "allowed_domains": ["https://app.example.com"] } ``` *** ## Resumo completo dos endpoints da API | Endpoint | Método | Descrição | | - | - | - | | `/v3/session/` | POST | Criar uma sessão de verificação | | `/v3/sessions/` | GET | Listar todas as sessões | | `/v3/session/{id}/decision/` | GET | Obter o resultado da verificação da sessão | | `/v3/session/{id}/update-status/` | PATCH | Aprovar ou recusar uma sessão | | `/v3/session/{id}/delete/` | DELETE | Excluir uma única sessão | | `/v3/sessions/delete/` | POST | Excluir sessões em lote | | `/v3/sessions/delete/{job_id}/` | GET | Status do job de exclusão de sessões em massa | | `/v3/sessions/{id}/reviews/` | GET, POST | Atividade/revisões da sessão | | `/v3/workflows/` | GET, POST | Listar/criar fluxos | | `/v3/workflows/{id}/` | GET, PATCH, DELETE | Detalhe/atualização/exclusão do fluxo | | `/v3/questionnaires/` | GET, POST | Listar/criar questionários | | `/v3/questionnaires/{id}/` | GET, PATCH, DELETE | Detalhe do questionário | | `/v3/users/` | GET | Listar usuários verificados | | `/v3/users/{vendor_data}/` | GET, PATCH | Detalhe/atualização do usuário | | `/v3/users/delete/` | POST | Excluir usuários em lote (também elimina os templates biométricos retidos deles) | | `/v3/biometric-templates/` | GET | Listar templates biométricos retidos | | `/v3/biometric-templates/count/` | GET | Contar templates biométricos retidos | | `/v3/biometric-templates/{id}/` | GET, DELETE | Detalhe / eliminação do template | | `/v3/biometric-templates/delete/` | POST | Eliminar templates em massa | | `/v3/lists/` | GET, POST | Listar todas as listas / criar lista | | `/v3/lists/{id}/` | GET, PATCH, DELETE | Detalhe / atualização / exclusão da lista | | `/v3/lists/{id}/entries/` | GET, POST | Listar entradas / adicionar entrada | | `/v3/lists/{id}/entries/{eid}/` | DELETE | Remover entrada | | `/v3/lists/{id}/entries/face-upload/` | POST | Enviar rosto para a lista de bloqueio | | `/v3/webhook/` | GET, PATCH | Configuração do webhook (URL, segredo, versão), política de retenção e hosts de retorno da carteira | | `/v3/billing/balance/` | GET | Consultar o saldo de créditos | | `/v3/billing/top-up/` | POST | Recarregar créditos | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.