API de gestión v3: flujos de trabajo y facturación

Autenticación

Todos los endpoints de la API de gestión usan la clave de API de tu aplicación. No necesitas UUID de organización ni de aplicación en las URL: la aplicación se identifica a partir de tu clave.

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

¿Aún no tienes una clave de API? Regístrate de forma programática con 2 llamadas a la API.

Flujos de verificación

Los flujos de verificación (workflows) definen los pasos de verificación por los que pasan tus usuarios (escaneo del documento de identidad, prueba de vida, coincidencia facial, análisis AML, etc.). Cada flujo es una configuración reutilizable que asocias a las sesiones.

GET

Lista todos los flujos de tu aplicación. Devuelve las funciones y los umbrales de cada flujo, y si es el flujo predeterminado.

POST

Crea un flujo nuevo. Define qué funciones de verificación activar, establece umbrales, configura los tipos de documento aceptados y mucho más.

GET

Obtiene todos los detalles de un flujo concreto, incluidas todas las configuraciones de funciones y los umbrales.

PATCH

Actualiza la configuración de un flujo. Puedes modificar cualquier ajuste de funciones, los umbrales o los documentos aceptados.

DELETE

Elimina un flujo. Las sesiones que ya usan este flujo no se ven afectadas.

Te recomendamos encarecidamente usar la Business Console para crear y configurar flujos. El constructor visual de flujos ofrece plantillas, configuración de funciones mediante arrastrar y soltar, ajustes de documentos, ajuste de umbrales y vista previa, todo sin escribir código. Usa la API solo para la automatización o la gestión programática de flujos.

Ejemplo rápido: crear un flujo

El workflow_type determina el conjunto base de funciones. Después, cada función se activa o desactiva con los indicadores 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 disponibles de workflow_type: kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification. En los flujos kyc, la verificación de identidad se incluye automáticamente: no necesitas un indicador aparte para ella. Usa los indicadores is_*_enabled para añadir o quitar funciones opcionales como coincidencia facial, prueba de vida, AML, NFC, teléfono, correo electrónico, prueba de domicilio, análisis de dispositivo e IP, y más. Después, usa el flujo al crear sesiones:

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"
  }'

Cuestionarios

Formularios personalizados que puedes añadir a los flujos de verificación para recopilar información adicional de los usuarios.

GET

Enumera todos los cuestionarios.

POST

Crea un cuestionario nuevo con preguntas personalizadas, lógica de ramificación y traducciones.

GET

Obtiene los detalles de un cuestionario, incluidas todas las preguntas y la estructura del formulario.

PATCH

Actualiza un cuestionario.

DELETE

Elimina un cuestionario.

Usuarios

Gestiona las personas verificadas (usuarios) de tu aplicación. Cada usuario se identifica mediante una cadena vendor_data que proporcionas al crear sesiones.

GET

Enumera todos los usuarios de tu aplicación, incluidos su estado de verificación y su historial de sesiones.

GET

Obtiene los detalles de un usuario a partir de tu identificador vendor_data.

PATCH

Actualiza los metadatos de un usuario.

POST

Elimina usuarios en lote. Cuerpo: {"vendor_data_list": ["user-1", "user-2"]} o {"delete_all": true}. También purga todas las plantillas biométricas conservadas para esos usuarios.

Plantillas biométricas

Plantillas biométricas faciales sin imágenes que conserva una aplicación que ha optado por participar tras eliminar sesiones. Consulta Plantillas biométricas.

GET

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

GET

Recuento con los mismos filtros.

GET

Una plantilla: usuario propietario, referencia de procedencia, caducidad, instrucción y estado.

DELETE

Purga una plantilla. Devuelve {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Purga masiva. Cuerpo: {"template_uuids": [...]} o {"delete_all": true}, además de filtros opcionales.

Operaciones de sesión

POST

Elimina sesiones en lote. Requiere delete:sessions. Cuerpo: {"session_numbers": ["1", "2", "3"]} o {"delete_all": true} (limita el alcance de delete_all mediante filtros de List Sessions con el prefijo filter_, como filter_status), además de los opcionales retain_face_embeddings, face_retention_days, face_retention_deadline, deletion_instruction e instruction_id. Si coinciden hasta 20 sesiones, se devuelve 200 con un face_retention_outcome por sesión; si coinciden más, se devuelve 202 con un trabajo de eliminación.

GET

Progreso y recuentos de resultados de una eliminación masiva de sesiones que devolvió 202.

GET

Lista las revisiones y el registro de actividad de una sesión.

POST

Añade una nota de revisión o un cambio de estado a una sesión.

Facturación

GET

Obtiene el saldo de créditos actual y la configuración de recarga automática.

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

POST

Crea una sesión de pago de Stripe para recargar créditos. Cada recarga puede ser de entre $50 y $10,000 y se abona por su valor nominal.

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

Listas (listas de bloqueo, listas de permitidos y personalizadas)

Gestiona listas de distintos tipos para bloquear, permitir y definir condiciones personalizadas en los flujos. Consulta la documentación completa de la API de listas.

GET

Enumera todas las listas de la aplicación (listas de bloqueo, listas de permitidos y personalizadas).

POST

Añade una entrada a una lista. Admite reference_session_id para extraer automáticamente los datos de una sesión, y reference_object_uuid para la trazabilidad de transacciones, usuarios o empresas.

DELETE

Elimina una entrada de una lista.

POST

Sube una imagen facial a una lista de bloqueo de rostros (base64).

Configuración de webhooks

GET

Obtiene la configuración actual del webhook, incluidos la URL, la versión, la clave secreta para verificar las firmas de los webhooks y la política de retención de datos y de retención de plantillas biométricas de la aplicación. La respuesta también incluye allowed_domains, que se describe más abajo en PATCH /v3/webhook/.

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

Actualiza la URL o la versión del webhook, o rota la clave secreta. Establece rotate_secret_key: true para generar un nuevo secreto de webhook (el anterior se invalida de inmediato). También define la política de retención de la aplicación: data_retention_months y face_retention_policy (delete_with_session, el valor predeterminado, o retain_until_user_deleted), junto con un face_retention_days finito obligatorio (1-3650) cuando la retención está activada. Consulta Retención de plantillas biométricas. También registra allowed_return_hosts: hasta 20 nombres de host simples (por ejemplo app.example.com, sin esquema, puerto, ruta ni comodín) a los que una verificación de la API de wallet de identidad digital puede redirigir a la persona mediante HTTPS. Una lista nueva sustituye a la registrada, y el dominio de marca blanca de tu aplicación siempre está permitido.También define allowed_domains: hasta 50 orígenes web (por ejemplo https://app.example.com) en los que se puede incrustar el flujo de verificación alojado y a los que puede redirigir al usuario mediante un callback de sesión. Cada entrada consta de un esquema, un host y un puerto opcional, sin ruta, consulta ni comodín. Usa https; http solo se acepta para localhost, 127.0.0.1 y ::1. Didit almacena cada origen en minúsculas y sin puerto predeterminado, y devuelve la lista en allowed_domains. Una entrada no válida provoca un error 400 en allowed_domains. Una lista nueva sustituye a la registrada, y una lista vacía elimina la restricción. Mientras la lista no esté vacía, POST /v3/session/ rechaza con un error 400 cualquier callback web que no figure en ella, y el flujo alojado no redirige al usuario a un callback almacenado o predeterminado del flujo que no figure en ella. Los esquemas de URL personalizados (deep links de aplicaciones) y las llamadas a la API entre servidores no se ven afectados.Si envías endpoints, todos los destinos de webhook que la lista omita se eliminan de forma permanente, junto con su secreto de firma y todo su registro de entregas, exactamente igual que con DELETE /v3/webhook/destinations/{destination_uuid}/. Esta acción no se puede deshacer. Para gestionar los destinos de uno en uno, usa en su lugar los endpoints de destinos de webhook.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}

Resumen completo de endpoints de la API

Endpoint	Método	Descripción
`/v3/session/`	POST	Crear una sesión de verificación
`/v3/sessions/`	GET	Listar todas las sesiones
`/v3/session/{id}/decision/`	GET	Obtener el resultado de verificación de la sesión
`/v3/session/{id}/update-status/`	PATCH	Aprobar o rechazar una sesión
`/v3/session/{id}/delete/`	DELETE	Eliminar una sesión
`/v3/sessions/delete/`	POST	Eliminar sesiones en lote
`/v3/sessions/delete/{job_id}/`	GET	Estado del trabajo de eliminación masiva de sesiones
`/v3/sessions/{id}/reviews/`	GET, POST	Actividad y revisiones de la sesión
`/v3/workflows/`	GET, POST	Listar y crear flujos
`/v3/workflows/{id}/`	GET, PATCH, DELETE	Detalle, actualización y eliminación del flujo
`/v3/questionnaires/`	GET, POST	Listar y crear cuestionarios
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	Detalle del cuestionario
`/v3/users/`	GET	Listar usuarios verificados
`/v3/users/{vendor_data}/`	GET, PATCH	Detalle y actualización del usuario
`/v3/users/delete/`	POST	Eliminar usuarios en lote (también purga sus plantillas biométricas retenidas)
`/v3/biometric-templates/`	GET	Listar plantillas biométricas retenidas
`/v3/biometric-templates/count/`	GET	Contar plantillas biométricas retenidas
`/v3/biometric-templates/{id}/`	GET, DELETE	Detalle y purga de la plantilla
`/v3/biometric-templates/delete/`	POST	Purgar plantillas en lote
`/v3/lists/`	GET, POST	Listar todas las listas y crear una lista
`/v3/lists/{id}/`	GET, PATCH, DELETE	Detalle, actualización y eliminación de la lista
`/v3/lists/{id}/entries/`	GET, POST	Listar entradas y añadir una entrada
`/v3/lists/{id}/entries/{eid}/`	DELETE	Eliminar una entrada
`/v3/lists/{id}/entries/face-upload/`	POST	Subir un rostro a una lista de bloqueo
`/v3/webhook/`	GET, PATCH	Configuración del webhook (URL, secreto, versión), política de retención y hosts de retorno de wallets
`/v3/billing/balance/`	GET	Consultar el saldo de créditos
`/v3/billing/top-up/`	POST	Recargar créditos

Última modificación el 1 de noviembre de 2026

​Autenticación

​Flujos de verificación

​Ejemplo rápido: crear un flujo

​Cuestionarios

​Usuarios

​Plantillas biométricas

​Operaciones de sesión

​Facturación

​Listas (listas de bloqueo, listas de permitidos y personalizadas)

​Configuración de webhooks

​Resumen completo de endpoints de la API

Autenticación

Flujos de verificación

Ejemplo rápido: crear un flujo

Cuestionarios

Usuarios

Plantillas biométricas

Operaciones de sesión

Facturación

Listas (listas de bloqueo, listas de permitidos y personalizadas)

Configuración de webhooks

Resumen completo de endpoints de la API