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_runsestá vacío, sea cual sea el modo de tus reglas. Una reglaACTIVEen una aplicación de sandbox nunca se activa, así que la transacción se queda enAPPROVEDcon puntuación0y no se abre ninguna alerta ni ningún caso. - Sin análisis AML ni análisis de wallets.
provider_resultsestá vacío incluso en transacciones cripto de una aplicación con la monitorización activada. - Sin webhooks. No se entrega ni
transaction.creatednitransaction.status.updatedpara una transacción de sandbox. - Sin facturación. Se registra un evento de uso con precio
0.0000y tu saldo no se modifica.
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 campotravel_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 unmode 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.
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 (laurl 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.
Escenarios
Cada escenario es un conjunto con nombre de valores mágicos. Pasa su slug comosandbox_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 predeterminadoapprove 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 respuestabank_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
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
metadataal crear la sesión (por ejemplo,"metadata": {"credential_state": "IL"}) y establece una condición de rama basada enmetadata.credential_state. Los metadatos se evalúan en sandbox exactamente igual que en producción. - Mantén la condición
kyc.regionbasada 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.
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;
123456incluido). Una entrada con formato incorrecto sigue devolviendo400. - OTP por correo electrónico: la comprobación de correo electrónico de sandbox acepta cualquier código con formato válido (
123456incluido). Una entrada con formato incorrecto sigue devolviendo400.
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á deNot 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:
- Autentícate con el propio
Session-Tokende la sesión (devuelto comosession_tokenal crear la sesión), no con la clave de API de tu aplicación: se trata de un endpoint orientado al cliente. - Devuelve
400para un slug de escenario desconocido, y400cuando la sesión ya ha avanzado más allá deNot Started("Scenario can only be armed before the verification starts."). - Devuelve
404cuando elSession-Tokenpertenece a una aplicación de producción (no sandbox) o no coincide con elsession_idde 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_risky luego armaapprove: 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/
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.
statuses el estado que fijó la simulación, yprevious_statusel que tenía la sesión antes.scenariodevuelve tu slug yriskes el caso de riesgo aplicado; cada uno esnullcuando no hay ninguno.send_webhooksdevuelve el valor aplicado.- Devuelve
400para un escenario o riesgo desconocido, cuando no se puede deducir ningúnnew_status, para cualquier otronew_statusy 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_hitdevuelve una coincidencia con el formato de producción y resuelve el análisis comoDeclined;review_aml_possible_matchlo resuelve comoIn 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 elrequest_iddevuelto se resuelve medianteGET /v3/session/{request_id}/decision/yGET /v3/session/{request_id}/generate-pdf/. - Devuelve
400para un slug de escenario desconocido, y400cuando 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 precio0.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, osandbox) 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.