> ## 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 Gestão v3: Fluxos e Faturação > Configure fluxos, questionários, utilizadores e faturação na Didit via API. Pronta para agentes e MCP. Preços por utilização, sem contratos. ## Autenticação Todos os endpoints da API de gestão utilizam a sua chave de API da aplicação. Não são necessários UUIDs da organização ou da aplicação nos URLs, porque 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? [Registe-se programaticamente em 2 chamadas de API](https://docs.didit.me/pt/integration/programmatic-registration.md). *** ## Fluxos Os fluxos definem os passos de verificação que os seus utilizadores seguem (leitura do documento de identificação, prova de vida, correspondência facial, triagem AML, etc.). Cada fluxo de verificação é uma configuração reutilizável que associa às sessões. **GET /v3/workflows/** `GET` Lista todos os fluxos da sua aplicação. Devolve as funcionalidades e os limiares de cada fluxo, bem como se é o predefinido. **POST /v3/workflows/** `POST` Cria um novo fluxo. Defina quais as funcionalidades de verificação a ativar, configure os limiares, os tipos de documento aceites e muito mais. **GET /v3/workflows/\{uuid}/** `GET` Obtém os detalhes completos de um fluxo específico, incluindo todas as configurações de funcionalidades e os limiares. **PATCH /v3/workflows/\{uuid}/** `PATCH` Atualiza a configuração de um fluxo. Pode alterar quaisquer definições de funcionalidades, limiares ou documentos aceites. **DELETE /v3/workflows/\{uuid}/** `DELETE` Elimina um fluxo. As sessões que já utilizam este fluxo não são afetadas. > [!WARNING] > > Recomendamos vivamente que utilize a **Consola Empresarial** para criar e configurar fluxos. O construtor visual de fluxos oferece modelos, configuração de funcionalidades por arrastar e largar, definições de documentos, ajuste de limiares e pré-visualização, tudo sem escrever código. Utilize a API apenas para automação ou gestão programática de fluxos. ### Exemplo rápido: criar um fluxo O `workflow_type` determina o conjunto base de funcionalidades. Depois, as funcionalidades individuais são ativadas ou desativadas 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 para `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, por isso não precisa de uma flag separada para a ativar. Use as flags `is_*_enabled` para adicionar ou remover funcionalidades opcionais, como correspondência facial, prova de vida, triagem AML, NFC, telefone, e-mail, comprovativo de morada, análise de dispositivo e IP, entre outras. Em seguida, utilize 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 pode adicionar aos fluxos de verificação para recolher informação adicional dos utilizadores. **GET /v3/questionnaires/** `GET` Lista todos os questionários. **POST /v3/questionnaires/** `POST` Cria um novo questionário com perguntas personalizadas, lógica de ramificação e traduções. **GET /v3/questionnaires/\{uuid}/** `GET` Obtém os detalhes do questionário, incluindo todas as perguntas e a estrutura do formulário. **PATCH /v3/questionnaires/\{uuid}/** `PATCH` Atualiza um questionário. **DELETE /v3/questionnaires/\{uuid}/** `DELETE` Elimina um questionário. *** ## Utilizadores Faça a gestão das pessoas verificadas (utilizadores) na sua aplicação. Cada utilizador é identificado por uma cadeia de caracteres `vendor_data` que fornece ao criar sessões. **GET /v3/users/** `GET` Lista todos os utilizadores da sua aplicação, incluindo o estado de verificação e o histórico de sessões. **GET /v3/users/\{vendor\_data}/** `GET` Obtém os detalhes de um utilizador pelo seu identificador vendor\_data. **PATCH /v3/users/\{vendor\_data}/** `PATCH` Atualiza os metadados do utilizador. **POST /v3/users/delete/** `POST` Elimina utilizadores em lote. Corpo: `{"vendor_data_list": ["user-1", "user-2"]}` ou `{"delete_all": true}`. Elimina também definitivamente todos os modelos biométricos retidos para esses utilizadores. *** ## Modelos biométricos Modelos biométricos faciais sem imagem que uma aplicação que optou por essa retenção conserva depois de eliminar sessões. Consulte [Modelos biométricos](https://docs.didit.me/pt/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 modelo: o Utilizador proprietário, a referência de proveniência, a validade, a instrução e o estado. **DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE` Elimina definitivamente um modelo. Devolve `{"uuid": "...", "outcome": "purged" | "already_purged"}`. **POST /v3/biometric-templates/delete/** `POST` Eliminação definitiva em massa. Corpo: `{"template_uuids": [...]}` ou `{"delete_all": true}`, com filtros opcionais. *** ## Operações sobre sessões **POST /v3/sessions/delete/** `POST` Elimina sessões em lote. Requer `delete:sessions`. Corpo: `{"session_numbers": ["1", "2", "3"]}` ou `{"delete_all": true}` (restrinja `delete_all` utilizando os filtros de listagem de sessões, com o prefixo `filter_`, como `filter_status`), além de `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction` e `instruction_id`, opcionais. Até 20 sessões correspondentes devolvem `200` com um `face_retention_outcome` por sessão; um número superior devolve `202` com uma tarefa de eliminação. **GET /v3/sessions/delete/\{job\_id}/** `GET` Progresso e contagens de resultados de uma eliminação em massa de sessões que devolveu `202`. **GET /v3/sessions/\{uuid}/reviews/** `GET` Lista as revisões e o registo de atividade de uma sessão. **POST /v3/sessions/\{uuid}/reviews/** `POST` Adiciona uma nota de revisão ou uma alteração de estado a uma sessão. *** ## Faturação **GET /v3/billing/balance/** `GET` Obtém o saldo de crédito atual e as definiçõ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 carregar saldo. Cada carregamento é de \$50 a \$20,000 e é adicionado 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ão e personalizadas) Faça a gestão de listas tipificadas para bloqueio, permissão e condições personalizadas de fluxo. Consulte a documentação completa da [API de listas](https://docs.didit.me/pt/management-api/lists/overview.md). **GET /v3/lists/** `GET` Lista todas as listas da aplicação (listas de bloqueio, de permissão e personalizadas). **POST /v3/lists/\{list\_uuid}/entries/** `POST` Adiciona uma entrada a uma lista. Suporta `reference_session_id` para extrair automaticamente dados de uma sessão, e `reference_object_uuid` para permitir a rastreabilidade de transações, utilizadores 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` Carrega uma imagem facial para uma lista de bloqueio facial (base64). *** ## Configuração de webhook **GET /v3/webhook/** `GET` Obtém a configuração atual do webhook, incluindo o URL, a versão, a chave secreta para verificar as assinaturas dos webhooks e a política de conservação de dados e de retenção de templates biométricos da aplicação. A resposta inclui também `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 o URL do webhook, a versão ou altera a chave secreta. Defina `rotate_secret_key: true` para gerar um novo segredo do webhook (o anterior fica imediatamente invalidado). Define também a política de retenção da aplicação: `data_retention_months` e `face_retention_policy` (`delete_with_session` por predefinição, ou `retain_until_user_deleted`), juntamente com `face_retention_days`, obrigatório e com um valor finito (1-3650) quando a retenção estiver ativa. Consulte [conservação de templates biométricos](https://docs.didit.me/pt/console/data-retention.md#retenção-de-modelo-biométrico). Regista também `allowed_return_hosts`: até 20 nomes de anfitrião simples (por exemplo `app.example.com`, sem esquema, porta, caminho nem curinga) para os quais uma verificação da [API de carteira de identidade digital](https://docs.didit.me/pt/standalone-apis/digital-id-wallets.md#registe-o-seu-destino-de-retorno) pode devolver a pessoa, através de HTTPS. Uma nova lista substitui a registada, e o domínio de marca branca da sua aplicação está sempre permitido. Define também `allowed_domains`: até 50 origens web (por exemplo `https://app.example.com`) nas quais o fluxo de verificação alojado pode ser incorporado e para as quais pode devolver o utilizador com um `callback` da sessão. Cada entrada é composta por um esquema, um anfitrião e uma porta opcional, sem caminho, parâmetros de consulta nem curinga. Use `https`; `http` só é aceite para `localhost`, `127.0.0.1` e `::1`. A Didit guarda cada origem em minúsculas, sem porta predefinida, e devolve a lista em `allowed_domains`. Uma entrada inválida resulta num erro 400 em `allowed_domains`. Uma nova lista substitui a registada, e uma lista vazia remove a restrição. Enquanto a lista não estiver vazia, o [`POST /v3/session/`](https://docs.didit.me/pt/sessions-api/create-session) rejeita um `callback` web fora dela com 400, e o fluxo alojado não redireciona o utilizador para um URL de retorno guardado ou predefinido do fluxo que esteja fora dela. Os esquemas de URL personalizados (ligações profundas de aplicações) e as chamadas de API entre servidores não são afetados. Se enviar `endpoints`, todos os destinos de webhook que a lista não inclua são eliminados permanentemente, juntamente com o respetivo segredo de assinatura e todo o registo de entregas, exatamente como em [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/pt/management-api/webhook/delete-destination). Não é possível desfazer esta ação. Para gerir os destinos um a um, use antes os [endpoints de destinos de webhook](https://docs.didit.me/pt/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 | Eliminar uma sessão | | `/v3/sessions/delete/` | POST | Eliminar sessões em lote | | `/v3/sessions/delete/{job_id}/` | GET | Estado do trabalho de eliminação em massa de sessões | | `/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/eliminaçã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 utilizadores verificados | | `/v3/users/{vendor_data}/` | GET, PATCH | Detalhe/atualização do utilizador | | `/v3/users/delete/` | POST | Eliminar utilizadores em lote (também elimina os respetivos templates biométricos retidos) | | `/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 | Eliminação em massa de templates | | `/v3/lists/` | GET, POST | Listar todas as listas / criar lista | | `/v3/lists/{id}/` | GET, PATCH, DELETE | Detalhe / atualização / eliminaçã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 | Carregar uma imagem facial para uma lista de bloqueio | | `/v3/webhook/` | GET, PATCH | Configuração do webhook (URL, segredo, versão), política de retenção e anfitriões de retorno da carteira | | `/v3/billing/balance/` | GET | Consultar saldo de crédito | | `/v3/billing/top-up/` | POST | Carregar saldo | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.