Saltar al contenido principal
El sandbox de Didit es el equivalente a las tarjetas de prueba de Stripe o a las plantillas de documentos de Sumsub: te permite reproducir cualquier resultado de verificación de forma determinista, sin tocar proveedores reales, datos personales (PII) reales ni tu saldo.
La fuente de verdad de estos datos es serialize_catalog() en el servicio de verificación, que está disponible en tiempo real en GET /v1/sandbox/scenarios/. Se genera una copia sometida a pruebas de detección de desviaciones en docs/sandbox/SANDBOX_REFERENCE.md, dentro del repositorio service-didit-verification, mediante pipenv run python scripts/generate_sandbox_reference.py. Esta página refleja esa referencia: si algo de aquí parece desactualizado, confía siempre en el endpoint del catálogo en tiempo real. El endpoint del catálogo requiere autenticación: envía tu clave de API (x-api-key) igual que en cualquier otra llamada, o un token de sesión si lo consultas desde dentro de una sesión en curso.

Modelo de entornos

El sandbox es un modo por aplicación (ApplicationDetail.mode == SANDBOX), la misma idea que el modo de prueba de Stripe. Mientras una sesión se ejecuta en una aplicación de sandbox:
  • Todos los proveedores externos (OCR, AML, coincidencia facial, prueba de vida, NFC, teléfono, correo electrónico, IP, POA, validación de base de datos, Document AI) están simulados: nunca se llama a ningún tercero.
  • La prueba de vida se ejecuta exactamente igual que en producción. Un flujo con prueba de vida activa ejecuta la captura activa real en el sandbox, tanto en el flujo alojado como a través de la transferencia al flujo web de los SDK nativos, para que puedas probar la experiencia que tendrán tus usuarios. Solo el resultado de la prueba de vida se simula, mediante el escenario o el valor mágico, y el informe registra el método que configura tu flujo.
  • Los dominios personalizados solo existen en producción. Una aplicación de sandbox no puede añadir un dominio personalizado; las sesiones de sandbox siempre se ejecutan en el dominio predeterminado de verificación alojada.
  • Las sesiones nunca se cobran y se omite la comprobación de saldo.
  • Se aplica una cuota por aplicación de 500 creaciones de sesión cada 24 h.
  • Los webhooks incluyen "environment": "sandbox" (las sesiones en producción incluyen "environment": "live").
  • El flujo alojado expone el entorno de la sesión para que la interfaz pueda advertir a los usuarios de que no suban datos personales (PII) reales.
  • Los resultados nunca dependen de los píxeles: los datos extraídos y los estados provienen del escenario o del valor mágico. Los archivos capturados en sí (documentos, selfie, vídeo, archivos de POA) se almacenan de verdad, exactamente igual que en una sesión en producción.

Monitorización de transacciones en sandbox

El sandbox está diseñado en torno a la sesión: simula los proveedores a los que llamaría una sesión de verificación. La Monitorización de transacciones no tiene ningún proveedor que simular, así que una aplicación de sandbox sigue el otro camino: la transacción se guarda, pero nunca se ejecuta sobre ella nada que decida, analice, notifique o cobre. Una transacción creada en una aplicación de sandbox se guarda y se devuelve como siempre, y no le ocurre nada de lo siguiente:
  • Sin evaluación de reglas. rule_runs está vacío, sea cual sea el modo de tus reglas. Una regla ACTIVE en una aplicación de sandbox nunca se activa, así que la transacción se queda en APPROVED con puntuación 0 y no se abre ninguna alerta ni ningún caso.
  • Sin análisis AML ni análisis de wallets. provider_results está vacío incluso en transacciones cripto de una aplicación con la monitorización activada.
  • Sin webhooks. No se entrega ni transaction.created ni transaction.status.updated para una transacción de sandbox.
  • Sin facturación. Se registra un evento de uso con precio 0.0000 y tu saldo no se modifica.
Cada respuesta de transacción incluye un campo environment ("live" o "sandbox") para que un rule_runs vacío nunca resulte ambiguo: "sandbox" significa que las reglas no se evaluaron, no que ninguna coincidiera. La Business Console indica lo mismo en la tarjeta Risk & decision de la transacción, en lugar de un simple “No rules evaluated”.
Travel Rule es la única excepción a “no se ejecuta nada”. En una aplicación con Travel Rule activado, una transacción travelRule de sandbox sigue ejecutando el motor de intercambio: se crea el registro de la transferencia y este avanza por sus estados. Lo que el sandbox nunca hace es comunicarse con nadie fuera de Didit. Su única contraparte es la Didit Test VASP, integrada en la plataforma: ningún mensaje de cumplimiento llega a un VASP de contraparte real por ningún canal (TRP, una membresía de red que hayas conectado, correo electrónico o INTERNAL), se omite el análisis de atribución del VASP de contraparte y, al cancelar, no se envía nada a ninguna contraparte. Los webhooks travel_rule.status.updated se entregan marcados con "environment": "sandbox".Saliente - una transacción travelRule que envías tú. La comprobación de threshold_amount se ejecuta primero y, en sandbox, solo se aplica cuando envías transaction_details.amount_in_default_currency, porque el sandbox no convierte divisas; sin ese campo, toda transferencia de sandbox se considera por encima del umbral. Una transferencia sin respuesta expira tras confirmation_timeout_hours y, a continuación, se aplica tu timeout_outcome a la transacción. Por encima del umbral, la comprobación de wallets sin custodia se aplica con normalidad: una transferencia a una wallet sin custodia declarada pasa a UNCONFIRMED_OWNERSHIP sin que se envíe nada, y puedes completarla en sandbox mediante el widget de propiedad de wallet, o mediante confirmar la propiedad cuando la wallet de destino ya está en tu libreta de direcciones de wallets. Cualquier otra transferencia por encima del umbral va a la Didit Test VASP por el canal TEST_VASP, que responde a ella dentro de Didit con el escenario que elijas mediante la wallet o el nombre del beneficiario: se completa, se rechaza, presenta una discrepancia, pasa a COUNTERPARTY_VASP_NOT_REACHABLE, expira (y entonces se aplica tu timeout_outcome a la transacción) o queda a la espera de la propiedad de la wallet. Consulta Probar Travel Rule en sandbox para ver todos los escenarios.Entrante - POST /v3/travel-rule/inbound/. El registro nunca envía nada por un canal, así que no se simula nada: el sandbox resuelve el depósito contra tu libreta de direcciones de wallets y lo liquida de forma síncrona, exactamente igual que en producción. Se resuelve en un resultado real en lugar de AWAITING_COUNTERPARTY: ON_HOLD (sin coincidencia en la libreta de direcciones), UNCONFIRMED_OWNERSHIP (no se ha verificado la propiedad de la entrada coincidente), COUNTERPARTY_MISMATCHED_DATA (el nombre del beneficiario no coincide con el titular de la wallet) o COMPLETED y después FINISHED (coincidió con una entrada verificada). Para recibir en su lugar una transferencia de la Didit Test VASP, usa Disparar una transferencia entrante de la Test VASP con una de las wallets de tu propia libreta de direcciones.

Escenarios de la Test VASP de Travel Rule

El campo travel_rule.scenarios del catálogo enumera estos escenarios salientes. Indica el nombre del beneficiario que aparece abajo en una transacción travelRule saliente después de activar Travel Rule en tu aplicación de sandbox. Las comprobaciones del umbral y de wallets sin custodia declaradas descritas arriba se ejecutan primero. También puedes elegir un escenario con la dirección de la wallet del beneficiario en lugar del nombre (la wallet prevalece cuando se indican ambos), y una transferencia que no indica ninguno de los dos se completa como accept. Probar Travel Rule en sandbox enumera la wallet de cada escenario y su resultado exacto. El disparador entrante de la Test VASP solo acepta accept y name_mismatch en su campo scenario.
Cómo poner a prueba una regla antes de que entre en producción. Usa Backtest: vuelve a ejecutar la regla sobre tu historial real de transacciones e informa de evaluated / matched / affected_entities sin modificar el estado de ninguna transacción. Combínalo con el modo TEST en la aplicación de producción (una regla TEST se evalúa en cada nueva transacción de producción y registra las coincidencias que habría encontrado, sin cambiar la puntuación ni el estado) y cambia a ACTIVE cuando la selectividad sea la adecuada.

Cómo cambiar entre producción y sandbox

Producción y sandbox son aplicaciones separadas, de modo que el tráfico de prueba y los datos de producción nunca se mezclan. Cada aplicación tiene un mode con el valor live o sandbox:
  • Usa la clave de API de una aplicación en modo sandbox para obtener sesiones simulables, sin facturación y con resultados simulados.
  • Usa la clave de API de una aplicación en modo producción para verificaciones reales.
El campo sandbox_scenario (al crear la sesión y en la API de AML independiente) y los endpoints de simulación solo se aceptan en aplicaciones sandbox; en las aplicaciones de producción se rechazan.

Sandbox en el flujo de verificación alojado

Las sesiones creadas en una aplicación sandbox muestran elementos adicionales de interfaz en el flujo de verificación alojado (la url que devuelve POST /v3/session/):
  • Banner de sandbox dentro de la tarjeta. Cada pantalla muestra un banner dentro de la tarjeta, “Solo datos de prueba - sin llamadas reales”, para que siempre quede claro que la sesión no realiza llamadas a proveedores reales ni afecta a tu saldo. Los archivos capturados se almacenan como en cualquier sesión, así que usa los documentos de muestra y los datos de prueba en lugar de documentos de identidad o información personal reales.
  • Selector de escenario previo al flujo. Antes de que empiece la captura, un selector dentro de la tarjeta guía al usuario para elegir un resultado de prueba: primero elige un resultado y luego un disparador para ese resultado. Al confirmar, se invoca POST /v3/session/{session_id}/sandbox/arm/ (consulta Activar (o reactivar) la sesión antes de que empiece el flujo más abajo) y el flujo continúa con los valores mágicos de ese escenario ya aplicados.
  • Franja de documentos de muestra. Una única fila de documentos de muestra de sandbox (hasta 3) aparece justo debajo del componente de carga o captura de documentos. Toca uno para usarlo en lugar de subir un documento real.
Las sesiones sandbox almacenan los archivos capturados reales: los documentos, la selfie, el video de prueba de vida y los archivos de prueba de domicilio se suben y se conservan exactamente igual que en una sesión de producción. Los datos extraídos (campos de verificación de identidad, puntuaciones de coincidencia facial, resultados de prueba de vida y similares) y el propio resultado de la sesión (Aprobado / En revisión / Rechazado) los simula el escenario o el valor mágico, y nunca se obtienen de los archivos capturados. La Business Console marca las secciones de datos extraídos de una sesión sandbox con una etiqueta Datos simulados, para que los revisores distingan de un vistazo qué partes de la sesión son la captura real y cuáles dependen del escenario.

Escenarios

Cada escenario es un conjunto con nombre de valores mágicos. Pasa su slug como sandbox_scenario al crear la sesión (o al endpoint de simulación) para reproducir el resultado. Los escenarios review_* existen para que puedas probar la experiencia de revisión manual (la cola de revisión de la consola, los webhooks In Review, las acciones de aprobar o rechazar del revisor) sin necesitar una entrada que provoque un rechazo. Los dos escenarios kyb_* anteriores definen expected_details.registration_number en lugar de expected_details.first_name: solo se aplican a sesiones de Verificación de empresas (KYB).

Valores mágicos

Un valor mágico es una entrada concreta que hace que una función simulada emita un riesgo concreto. Para activarlo, asigna el valor mágico al campo de entrada (directamente o mediante un escenario).

Consulta sin documento y wallets de identidad

Las aplicaciones de sandbox pueden habilitar todas las wallets de identidad del catálogo de países, incluidas las que no están disponibles en las aplicaciones de producción. El escenario predeterminado approve simula una identidad verificada sin iniciar sesión en una wallet externa. El resultado se guarda en la sesión y el flujo continúa con su siguiente paso normal. El sandbox no valida credenciales reales de wallets ni cobra por los intentos simulados. Las solicitudes de consulta siguen validando los campos introducidos y aplican el límite de intentos configurado, que de forma predeterminada es uno. Usa los siguientes escenarios para probar los reintentos y las reglas de respaldo: Los fallos de wallet siguen la configuración del país para pasar a la captura de documento o rechazar. Los intentos de consulta completados se registran por separado, de modo que dos intentos permitidos producen dos resultados antes del respaldo. Todo el uso del sandbox sigue siendo gratuito.

Verificación de cuenta de Verificación bancaria

La Verificación bancaria aún no está habilitada en producción, así que esta sección se aplica cuando lo esté: hasta entonces, una clave de sandbox recibe la misma respuesta bank_verification_not_available que una clave de producción. Un paso de Verificación bancaria en sandbox ofrece ambos métodos en todos los países, en el orden que define el paso, en un servicio simulado sin banco y sin coste. Con el orden predeterminado, la persona empieza en el inicio de sesión bancario y elige Introduce los datos de tu cuenta para ejecutar la verificación de cuenta; define bank_method_order como ["account_lookup", "open_banking"] para empezar por ella. Los cuatro últimos caracteres de la cuenta introducida determinan la respuesta; consulta Pruébalo en sandbox para ver todas las terminaciones y una cuenta válida por formato. La API de verificación de cuenta devuelve las respuestas correspondientes para una clave de sandbox según las mismas terminaciones.

Los documentos de muestra

Nunca subas documentos de identidad reales en sandbox. Usa en su lugar los documentos de muestra integrados.
El flujo alojado ofrece tres documentos de muestra, uno por tipo de documento: Toca una muestra en la tira para usarla en lugar de una captura real. Los datos extraídos y el resultado de la sesión siempre provienen del escenario o del valor mágico seleccionado, así que cualquier muestra funciona con cualquier escenario.

Identidad de muestra: pruebas de expected_details

Cada documento de sandbox se genera a partir de una única identidad fija. Los valores extraídos son los mismos en todas las sesiones y nunca se derivan de la fecha actual, así que puedes rellenar expected_details con ellos y comprobar de principio a fin tu comparación de campos y tu gestión de advertencias. Si envías los valores siguientes, las comprobaciones de comparación se superan; si envías cualquier otro, se activa a propósito la advertencia *_MISMATCH_WITH_PROVIDED correspondiente. Las fechas son comunes a todos los documentos de muestra: El resto de la identidad depende del documento que uses:
first_name y last_name son la excepción: el sandbox replica en el documento generado los nombres que envías en expected_details, así que la coincidencia de nombres pasa con cualquier nombre. Usa el valor mágico SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED para probar una discrepancia de nombre, y SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED para una discrepancia de fecha de nacimiento.
Si tu flujo restringe documents_allowed a un país o tipo de documento que excluye el pasaporte electrónico de Brasil, el sandbox genera en su lugar un documento del primer país permitido, de modo que nationality, id_country y el nombre del documento corresponden a ese país. Las fechas anteriores no cambian.

Qué no incluye el documento generado

El documento generado es la plantilla genérica del país y tipo de documento permitidos, así que los campos que solo aporta un documento real emitido por el Estado quedan vacíos. El que importa para el enrutamiento es la región / estado de EE. UU. (kyc.region): una licencia de conducir o un documento de identidad de EE. UU. en sandbox no tiene estado, así que una condición de rama como Region equals IL nunca puede cumplirse en sandbox y, cuando tampoco se cumple ninguna otra rama de ese nodo, el flujo toma la rama de respaldo del nodo (la rama sin condiciones). No se trata de una revisión ni de un fallo de la rama: la condición simplemente no tiene nada que leer. Un campo ausente también falla con not equals y not in; consulta cómo leen las condiciones de rama los datos de la sesión para ver la diferencia entre un campo ausente y una cadena vacía. Para probar en sandbox un flujo que depende del estado, basa la decisión en un valor de la sesión que controles tú, en lugar de en el documento:
  • Envía el estado en metadata al crear la sesión (por ejemplo, "metadata": {"credential_state": "IL"}) y establece una condición de rama basada en metadata.credential_state. Los metadatos se evalúan en sandbox exactamente igual que en producción.
  • Mantén la condición kyc.region basada en el documento para el tráfico de producción si también necesitas que el documento acredite el estado; en modo de producción, la región se lee del documento real.
Todo lo demás del enrutamiento es idéntico a producción: el grafo del flujo, las condiciones de rama, los valores de metadata y expected_details, los nodos de acción y los nodos de estado se ejecutan de verdad. El sandbox nunca envía por sí solo una sesión a revisión: una sesión de sandbox termina en revisión solo cuando el flujo la dirige allí (un escenario review_*, un valor mágico asociado a una acción de revisión o un nodo de estado en el grafo).

Códigos OTP y activación de correos electrónicos

  • OTP por teléfono: la comprobación telefónica de sandbox acepta cualquier código con formato válido (de 4 a 8 dígitos; 123456 incluido). Una entrada con formato incorrecto sigue devolviendo 400.
  • OTP por correo electrónico: la comprobación de correo electrónico de sandbox acepta cualquier código con formato válido (123456 incluido). Una entrada con formato incorrecto sigue devolviendo 400.
De forma predeterminada, las sesiones de sandbox no envían correos electrónicos (alertas de revisión, cambio de estado, OTP, reenvío, enlace de nueva sesión, etc.). Para enviar un correo electrónico de todos modos, usa uno de estos patrones de activación en la dirección del destinatario:

Controlar resultados: escenarios, valores mágicos, armado y el endpoint de simulación

Hay cinco formas de controlar el resultado en sandbox.

1. sandbox_scenario al crear la sesión

Indica el slug del escenario al crear la sesión (POST /v3/session/). El proceso de creación expande los valores mágicos incluidos en el escenario en los campos de entrada de la sesión, de modo que los proveedores simulados emiten el resultado previsto a través del pipeline real del flujo.

2. Valores mágicos introducidos a mano

Define tú mismo los campos de entrada individuales (por ejemplo, expected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED" o user_email = "sandbox+aml_hit@didit.test"). Consulta la tabla de valores mágicos anterior para ver el registro completo.

3. Armar (o volver a armar) la sesión antes de que empiece el flujo

Define o sustituye el escenario armado en una sesión que ya existe, siempre que no haya avanzado más allá de Not Started. Este es el endpoint que invoca el selector de escenarios previo al flujo, y puedes invocarlo tú mismo para crear un selector personalizado o un entorno de pruebas:
Respuesta 200:
  • Autentícate con el propio Session-Token de la sesión (devuelto como session_token al crear la sesión), no con la clave de API de tu aplicación: se trata de un endpoint orientado al cliente.
  • Devuelve 400 para un slug de escenario desconocido, y 400 cuando la sesión ya ha avanzado más allá de Not Started ("Scenario can only be armed before the verification starts.").
  • Devuelve 404 cuando el Session-Token pertenece a una aplicación de producción (no sandbox) o no coincide con el session_id de la ruta.
  • Volver a armar sustituye el escenario anterior. Solo borra los valores mágicos que escribió el escenario anterior y deja intacto todo lo que el usuario ya haya introducido a mano (correo electrónico, nombre, etc.). Por ejemplo: arma decline_phone_high_risk y luego arma approve: el número de teléfono vuelve a quedar sin definir, pero un correo electrónico introducido por el cliente se conserva tras ambas llamadas.

4. El endpoint de simulación

Fuerza un estado final a posteriori:
  • Consola / clave de API (requiere el privilegio write:sessions; una clave de API con alcance limitado necesita acceso de escritura a las sesiones): POST /v3/session/{session_id}/simulate/
  • Flujo alojado (encabezado Session-Token): POST /v3/session/{session_id}/sandbox/simulate/
Ambos funcionan con sesiones sandbox de KYC y KYB. Una sesión de producción (no sandbox) devuelve 404, al igual que un Session-Token que no coincide con el session_id de la ruta. Todos los campos del cuerpo son opcionales, pero se requiere al menos uno de new_status, scenario o risk: send_webhooks: true envía exactamente los mismos webhooks que un cambio de estado real: status.updated, más los eventos user.status.updated y user.data.updated (o business.status.updated y business.data.updated en una sesión de empresa) que provoca el cambio, a los destinos suscritos a ellos. Con send_webhooks: false el estado cambia igualmente, pero no se registra ni se envía ningún webhook. La recuperación de webhooks perdidos nunca reenvía esa decisión, y la consola se sigue actualizando en tiempo real. El siguiente cambio de estado de la sesión envía webhooks con normalidad.
Respuesta 200:
  • status es el estado que fijó la simulación, y previous_status el que tenía la sesión antes.
  • scenario devuelve tu slug y risk es el caso de riesgo aplicado; cada uno es null cuando no hay ninguno.
  • send_webhooks devuelve el valor aplicado.
  • Devuelve 400 para un escenario o riesgo desconocido, cuando no se puede deducir ningún new_status, para cualquier otro new_status y cuando la sesión ya tiene el estado solicitado (["The new status is the same as the current status."]).

5. sandbox_scenario en la API de AML independiente

El análisis AML desde el back-end no tiene usuario final ni sesión que armar, así que el slug va en la propia solicitud de análisis (POST /v3/aml/):
  • decline_aml_hit devuelve una coincidencia con el formato de producción y resuelve el análisis como Declined; review_aml_possible_match lo resuelve como In Review. Un escenario que no arma ningún resultado AML deja el análisis limpio.
  • Con save_api_request: true (el valor por defecto), el análisis se guarda exactamente igual que con una clave de producción, de modo que el request_id devuelto se resuelve mediante GET /v3/session/{request_id}/decision/ y GET /v3/session/{request_id}/generate-pdf/.
  • Devuelve 400 para un slug de escenario desconocido, y 400 cuando la clave de API pertenece a una aplicación de producción.

Dónde aparece sandbox_scenario

El slug del escenario armado (null si no hay ninguno activado) se devuelve en algunas ubicaciones y se omite intencionadamente en otras: Si tu integración necesita aplicar lógica condicional en función del escenario activado del lado del servidor, consúltalo en el payload del webhook o de cualquiera de los dos endpoints de decisión (v1 o v3).

Uso y facturación

El uso en sandbox se registra, pero nunca se cobra:
  • Cada llamada simulada sigue registrando un evento de uso (is_sandbox: true, con precio 0.0000) para que el volumen de sandbox sea visible al depurar, pero nunca se suma a tus totales de uso, nunca se descuenta del saldo y nunca aparece en una factura.
  • Las secciones de saldo, recarga y uso en producción de la Business Console excluyen por defecto el uso en sandbox. Los endpoints de uso de recargas aceptan un parámetro environment (live, el valor por defecto, o sandbox) para que puedas consultar el volumen de sandbox por separado, siempre sin coste y sin consumir el plan gratuito.
  • La verificación de correo electrónico y la verificación de teléfono se facturan por solicitud y no según el resultado de la sesión, y sandbox no puede reproducir eso por completo en la capa de webhooks. Las comprobaciones de correo electrónico y teléfono en sandbox siguen registrando un evento de uso por solicitud con precio 0.0000, igual que cualquier otra función simulada: es una divergencia conocida y aceptada respecto a la facturación en producción, no un error.
  • La estructura de la respuesta de la validación de base de datos en sandbox difiere intencionadamente de la estructura por proveedor de producción, ya que no hay ningún proveedor real que reproducir. Considera los payloads de validación de base de datos en sandbox como una representación del resultado (estado y código de advertencia), no como una vista previa exacta, byte a byte, de la respuesta de un proveedor en producción.
Última modificación el 1 de noviembre de 2026