API de Gestão v3: Fluxos e Faturação

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.

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.

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

Lista todos os fluxos da sua aplicação. Devolve as funcionalidades e os limiares de cada fluxo, bem como se é o predefinido.

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

Obtém os detalhes completos de um fluxo específico, incluindo todas as configurações de funcionalidades e os limiares.

PATCH

Atualiza a configuração de um fluxo. Pode alterar quaisquer definições de funcionalidades, limiares ou documentos aceites.

DELETE

Elimina um fluxo. As sessões que já utilizam este fluxo não são afetadas.

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.

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:

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

Lista todos os questionários.

POST

Cria um novo questionário com perguntas personalizadas, lógica de ramificação e traduções.

GET

Obtém os detalhes do questionário, incluindo todas as perguntas e a estrutura do formulário.

PATCH

Atualiza um questionário.

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

Lista todos os utilizadores da sua aplicação, incluindo o estado de verificação e o histórico de sessões.

GET

Obtém os detalhes de um utilizador pelo seu identificador vendor_data.

PATCH

Atualiza os metadados do utilizador.

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.

GET

Lista paginada, com filtros (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to, ordering).

GET

Contagem com os mesmos filtros.

GET

Um modelo: o Utilizador proprietário, a referência de proveniência, a validade, a instrução e o estado.

DELETE

Elimina definitivamente um modelo. Devolve {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Eliminação definitiva em massa. Corpo: {"template_uuids": [...]} ou {"delete_all": true}, com filtros opcionais.

Operações sobre sessões

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

Progresso e contagens de resultados de uma eliminação em massa de sessões que devolveu 202.

GET

Lista as revisões e o registo de atividade de uma sessão.

POST

Adiciona uma nota de revisão ou uma alteração de estado a uma sessão.

Faturação

GET

Obtém o saldo de crédito atual e as definições de recarga automática.

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

Cria uma sessão de checkout do Stripe para carregar saldo. Cada carregamento é de $50 a $20,000 e é adicionado pelo valor nominal.

{
  "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.

GET

Lista todas as listas da aplicação (listas de bloqueio, de permissão e personalizadas).

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

Remove uma entrada de uma lista.

POST

Carrega uma imagem facial para uma lista de bloqueio facial (base64).

Configuração de 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.

{
  "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

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. 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 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/ 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}/. Não é possível desfazer esta ação. Para gerir os destinos um a um, use antes os endpoints de destinos de webhook.

{
  "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

Última modificação em 7 de novembro de 2026

​Autenticação

​Fluxos

​Exemplo rápido: criar um fluxo

​Questionários

​Utilizadores

​Modelos biométricos

​Operações sobre sessões

​Faturação

​Listas (listas de bloqueio, listas de permissão e personalizadas)

​Configuração de webhook

​Resumo completo dos endpoints da API

Autenticação

Fluxos

Exemplo rápido: criar um fluxo

Questionários

Utilizadores

Modelos biométricos

Operações sobre sessões

Faturação

Listas (listas de bloqueio, listas de permissão e personalizadas)

Configuração de webhook

Resumo completo dos endpoints da API