> ## 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 gestión v3: flujos de trabajo y facturación

> Gestiona flujos de trabajo, cuestionarios, usuarios, facturación y listas de bloqueo de Didit con clave de API. Compatible con MCP. Pago por uso.

## 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.

```bash theme={null}
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](https://docs.didit.me/es/integration/programmatic-registration.md).

***

## 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 /v3/workflows/** `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 /v3/workflows/** `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 /v3/workflows/\{uuid}/** `GET`

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

**PATCH /v3/workflows/\{uuid}/** `PATCH`

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

**DELETE /v3/workflows/\{uuid}/** `DELETE`

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

> [!WARNING]
>
> 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`.

```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 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:

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

***

## Cuestionarios

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

**GET /v3/questionnaires/** `GET`

Enumera todos los cuestionarios.

**POST /v3/questionnaires/** `POST`

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

**GET /v3/questionnaires/\{uuid}/** `GET`

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

**PATCH /v3/questionnaires/\{uuid}/** `PATCH`

Actualiza un cuestionario.

**DELETE /v3/questionnaires/\{uuid}/** `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 /v3/users/** `GET`

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

**GET /v3/users/\{vendor\_data}/** `GET`

Obtiene los detalles de un usuario a partir de tu identificador vendor\_data.

**PATCH /v3/users/\{vendor\_data}/** `PATCH`

Actualiza los metadatos de un usuario.

**POST /v3/users/delete/** `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](https://docs.didit.me/es/management-api/biometric-templates/overview.md).

**GET /v3/biometric-templates/** `GET`

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

**GET /v3/biometric-templates/count/** `GET`

Recuento con los mismos filtros.

**GET /v3/biometric-templates/\{template\_uuid}/** `GET`

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

**DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE`

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

**POST /v3/biometric-templates/delete/** `POST`

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

***

## Operaciones de sesión

**POST /v3/sessions/delete/** `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 /v3/sessions/delete/\{job\_id}/** `GET`

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

**GET /v3/sessions/\{uuid}/reviews/** `GET`

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

**POST /v3/sessions/\{uuid}/reviews/** `POST`

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

***

## Facturación

**GET /v3/billing/balance/** `GET`

Obtiene el saldo de créditos actual y la configuración 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`

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.

```json theme={null}
{
  "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](https://docs.didit.me/es/management-api/lists/overview.md).

**GET /v3/lists/** `GET`

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

**POST /v3/lists/\{list\_uuid}/entries/** `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 /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE`

Elimina una entrada de una lista.

**POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST`

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

***

## Configuración de webhooks

**GET /v3/webhook/** `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/`.

```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`

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](https://docs.didit.me/es/console/data-retention.md#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](https://docs.didit.me/es/standalone-apis/digital-id-wallets.md#registra-tu-destino-de-retorno) 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/`](https://docs.didit.me/es/sessions-api/create-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}/`](https://docs.didit.me/es/management-api/webhook/delete-destination).
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](https://docs.didit.me/es/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"]
}
```

***

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.