Saltar al contingut principal
El sandbox de Didit equival a les targetes de prova de Stripe o a les plantilles de documents de Sumsub: et permet reproduir qualsevol resultat de verificació de manera determinista, sense tocar proveïdors reals, dades personals reals ni el teu saldo.
La font de veritat d’aquestes dades és serialize_catalog() al servei de verificació, que es serveix en directe a GET /v1/sandbox/scenarios/. Es genera una còpia verificada amb proves de deriva a docs/sandbox/SANDBOX_REFERENCE.md del repositori service-didit-verification amb pipenv run python scripts/generate_sandbox_reference.py. Aquesta pàgina reflecteix aquesta referència: si alguna cosa d’aquí sembla desactualitzada, confia sempre en l’endpoint de catàleg en directe. L’endpoint de catàleg requereix autenticació: envia la teva clau d’API (x-api-key) com en qualsevol altra crida, o un token de sessió si el consultes des d’una sessió en curs.

Model d’entorn

El sandbox és un mode per aplicació (ApplicationDetail.mode == SANDBOX), la mateixa idea que el mode de prova de Stripe. Mentre una sessió s’executa sota una aplicació de sandbox:
  • Tots els proveïdors externs (OCR, AML, coincidència facial, prova de vida, NFC, telèfon, correu electrònic, IP, comprovant de domicili, validació de bases de dades i IA documental) són simulats: mai no es crida cap tercer.
  • La prova de vida funciona exactament igual que en producció. Un flux de treball de prova de vida activa executa la captura activa real al sandbox, tant en el flux allotjat com en el pas web dels SDK natius, de manera que pots provar l’experiència que tindran els teus usuaris. Només es simula el resultat de la prova de vida, mitjançant l’escenari o el valor màgic, i l’informe registra el mètode que configura el teu flux de treball.
  • Els dominis personalitzats són només de producció. Una aplicació de sandbox no pot afegir un domini personalitzat; les sessions de sandbox sempre s’executen al domini de verificació allotjat per defecte.
  • Les sessions mai es cobren i la comprovació de saldo s’omet.
  • S’aplica una quota per aplicació de 500 creacions de sessió / 24 h.
  • Els webhooks porten "environment": "sandbox" (les sessions de producció porten "environment": "live").
  • El flux allotjat mostra l’entorn de la sessió perquè la interfície pugui advertir els usuaris que no pugin dades personals reals.
  • Els resultats mai no depenen dels píxels: les dades extretes i els estats provenen de l’escenari o del valor màgic. El contingut capturat (documents, selfie, vídeo, fitxers de comprovant de domicili) s’emmagatzema de veritat, exactament com en una sessió de producció.

Monitoratge de transaccions en sandbox

El sandbox és de tipus sessió: simula els proveïdors que cridaria una sessió de verificació. El Monitoratge de transaccions no té cap proveïdor a simular, així que una aplicació sandbox segueix l’altra via: la transacció s’emmagatzema, però mai no s’executa res que hi prengui decisions, la sotmeti a cribratge, en faci notificacions o en faci el cobrament. Una transacció creada en una aplicació sandbox es persisteix i es retorna com de costum, i no li passa cap de les coses següents:
  • Cap avaluació de regles. rule_runs és buit, siguin quins siguin els modes de les teves regles. Una regla ACTIVE en una aplicació sandbox mai no s’activa, de manera que la transacció es manté APPROVED amb puntuació 0 i no s’obre cap alerta ni cas.
  • Cap cribratge AML ni de carteres. provider_results és buit fins i tot per a transaccions de criptoactius en una aplicació amb el monitoratge habilitat.
  • Cap webhook. Ni transaction.created ni transaction.status.updated no s’envien per a una transacció sandbox.
  • Cap facturació. Es registra un esdeveniment d’ús amb preu 0.0000 i el teu saldo no canvia.
Cada resposta de transacció inclou un camp environment ("live" o "sandbox"), de manera que un rule_runs buit mai no és ambigu: "sandbox" vol dir que les regles no s’han avaluat, no que cap d’elles no hagi coincidit. La Business Console diu el mateix a la targeta Risk & decision de la transacció, en lloc de mostrar un simple “No rules evaluated”.
La Travel Rule és l’única excepció a «no s’executa res». En una aplicació amb la Travel Rule habilitada, una transacció travelRule de sandbox sí que executa el motor d’intercanvi: el registre de la transferència es crea i avança pels seus estats. El que el sandbox mai no fa és comunicar-se amb ningú fora de Didit. L’única contrapart és el Didit Test VASP, integrat a la plataforma: cap missatge de compliment no arriba a un VASP contrapart real per cap canal (TRP, una pertinença a xarxa que hagis connectat, correu electrònic o INTERNAL), s’omet el cribratge d’atribució del VASP contrapart, i una cancel·lació no envia res a la contrapart. Els webhooks travel_rule.status.updated s’envien, marcats amb "environment": "sandbox".Sortint - una transacció travelRule que tu envies. La comprovació de threshold_amount s’executa primer. En sandbox només s’aplica quan envies transaction_details.amount_in_default_currency, perquè el sandbox no converteix monedes; sense aquest camp, cada transferència sandbox superaria el llindar. Una transferència sense resposta caduca després de confirmation_timeout_hours, i llavors s’aplica el teu timeout_outcome a la transacció. Per sobre del llindar, la comprovació de cartera autoallotjada s’aplica com de costum: una transferència a una cartera autoallotjada declarada passa a UNCONFIRMED_OWNERSHIP sense cap enviament, i la pots completar en sandbox amb el widget de verificació de titularitat de la cartera, o amb confirmar la titularitat quan la cartera de destinació ja és a la teva llibreta d’adreces de carteres. Qualsevol altra transferència per sobre del llindar va al Didit Test VASP pel canal TEST_VASP, que la respon dins de Didit amb l’escenari que triïs segons la cartera o el nom del beneficiari: es completa, és rebutjada, no coincideix, passa a COUNTERPARTY_VASP_NOT_REACHABLE, caduca (llavors s’aplica el teu timeout_outcome a la transacció) o espera la titularitat de la cartera. Consulta Prova la Travel Rule en sandbox per veure tots els escenaris.Entrant - POST /v3/travel-rule/inbound/. La inscripció mai no es tramet per cap canal, de manera que res d’aquesta inscripció no se simula: el sandbox resol el dipòsit contra la teva llibreta d’adreces de carteres i el liquida de manera síncrona, exactament com en producció. El resultat és sempre un resultat real i mai AWAITING_COUNTERPARTY: ON_HOLD (sense coincidència a la llibreta d’adreces), UNCONFIRMED_OWNERSHIP (l’entrada coincident no té la titularitat verificada), COUNTERPARTY_MISMATCHED_DATA (el nom del beneficiari no coincideix amb el del titular de la cartera), o COMPLETED i després FINISHED (coincidència amb una entrada verificada). Per rebre una transferència del Didit Test VASP, fes servir Activa una transferència entrant del Test VASP amb una de les carteres de la teva llibreta d’adreces.

Escenaris del Test VASP de la Travel Rule

El travel_rule.scenarios del catàleg enumera aquests escenaris de sortida. Estableix el nom del beneficiari indicat a continuació en una transacció travelRule de sortida, després d’habilitar la Travel Rule a la teva aplicació sandbox. Les comprovacions de llindar i de cartera autoallotjada declarada descrites anteriorment s’executen primer. També pots triar un escenari amb l’adreça de la cartera del beneficiari en lloc del nom (la cartera té prioritat quan s’indiquen tots dos), i una transferència que no indica cap dels dos es completa com a accept. Prova la Travel Rule en sandbox enumera la cartera de cada escenari i el resultat exacte. L’activador de Test VASP entrant només accepta accept i name_mismatch al seu camp scenario.
Com provar una regla abans de posar-la en producció. Fes servir el Backtest: reprodueix la regla sobre el teu historial real de transaccions i informa de evaluated / matched / affected_entities sense modificar l’estat de cap transacció. Combina’l amb el mode TEST a l’aplicació en producció: una regla TEST s’avalua en cada nova transacció real i registra amb què hauria coincidit, sense canviar la puntuació ni l’estat, i després passa a ACTIVE quan la selectivitat sigui l’adequada.

Com canviar entre producció i sandbox

La producció i el sandbox són aplicacions separades, de manera que el trànsit de prova i les dades de producció mai es barregen. Cada aplicació té un mode de live o sandbox:
  • Fes servir la clau d’API d’una aplicació en mode sandbox per obtenir sessions simulades, sense facturació i simulables.
  • Fes servir la clau d’API d’una aplicació en mode de producció per a verificacions reals.
El camp sandbox_scenario (a la creació de sessió i a l’API AML independent) i els endpoints de simulació només s’accepten en aplicacions sandbox; en aplicacions de producció es rebutgen.

Sandbox al flux de verificació allotjat

Les sessions creades en una aplicació sandbox mostren elements d’interfície addicionals al flux de verificació allotjat (la url que retorna POST /v3/session/):
  • Bàner de sandbox dins la targeta. Cada pantalla mostra un bàner dins la targeta amb el text “Només dades de prova - sense crides reals”, perquè quedi sempre clar que la sessió mai crida proveïdors reals i mai no toca el teu saldo. Els suports capturats s’emmagatzemen com en qualsevol sessió, de manera que has d’utilitzar els documents de mostra i les dades de prova en lloc de documents d’identitat reals o informació personal.
  • Selector d’escenaris previ al flux. Abans que comenci la captura, un selector dins la targeta guia l’usuari per triar un resultat de prova: tria un resultat i després un activador per a aquest resultat. En confirmar, es crida POST /v3/session/{session_id}/sandbox/arm/ (vegeu Armar (o tornar a armar) la sessió abans que comenci el flux més avall), i després es continua el flux amb els valors màgics de l’escenari ja aplicats.
  • Franja de documents de mostra. Una sola fila de documents de mostra del sandbox (fins a 3) es troba just sota del component de pujada o captura de documents. Toca’n un per utilitzar-lo en lloc d’una pujada real.
Les sessions sandbox emmagatzemen els suports reals capturats: documents, selfie, vídeo de prova de vida i fitxers de comprovant de domicili es pugen i es conserven exactament com ho farien en una sessió de producció. Les dades extretes (camps de verificació d’identitat, puntuacions de coincidència facial, resultats de prova de vida i similars) i el resultat de la sessió (Aprovada / En revisió / Rebutjada) són simulats per l’escenari o pel valor màgic, i mai no es deriven dels suports capturats. La Business Console marca les seccions de dades extretes d’una sessió sandbox amb un distintiu Dades simulades, perquè els revisors puguin veure d’un cop d’ull quines parts de la sessió corresponen a la captura real i quines es basen en l’escenari.

Escenaris

Cada escenari és un conjunt de valors màgics amb nom. Passa’n el slug com a sandbox_scenario en crear la sessió (o a l’endpoint de simulació) per reproduir el resultat. Els escenaris review_* existeixen perquè puguis provar l’experiència de revisió manual (la cua de revisió de la consola, els webhooks de In Review i les accions d’aprovació i rebuig del revisor) sense necessitat d’una entrada que provoqui un rebuig clar. Els dos escenaris kyb_* de dalt estableixen expected_details.registration_number en lloc de expected_details.first_name: només s’apliquen a les sessions de verificació d’empreses (KYB).

Valors màgics

Un valor màgic és una entrada concreta que fa que una funcionalitat simulada emeti un risc concret. Estableix el camp d’entrada amb el valor màgic (directament o mitjançant un escenari) per activar-lo.

Consulta sense document i carteres d’identitat

Les aplicacions de sandbox poden activar totes les carteres d’identitat del catàleg del país, incloses les que no estan disponibles a les aplicacions en producció. L’escenari predeterminat approve simula una identitat verificada sense iniciar sessió a cap cartera externa. El resultat es desa a la sessió i segueix el pas següent habitual del flux de treball. El sandbox no valida una credencial de cartera real ni cobra pels intents simulats. Les sol·licituds de consulta continuen validant els camps introduïts i apliquen el límit d’intents configurat, que per defecte és d’un intent. Utilitza els escenaris següents per provar els reintents i les regles d’alternativa: Els errors de la cartera segueixen l’opció configurada al país: passar a la captura del document o rebutjar. Els intents de consulta completats es registren per separat, de manera que dos intents permesos produeixen dos resultats abans de l’alternativa. Tot l’ús del sandbox continua sent gratuït.

Comprovació del compte de verificació bancària

Un pas de verificació bancària en sandbox ofereix tots dos mètodes a tots els països, en l’ordre que defineix el pas, amb un servei simulat sense cap banc real i sense cost. Amb l’ordre predeterminat, la persona comença a la pantalla d’inici de sessió bancari i tria Introdueix les dades del teu compte per fer la comprovació del compte; estableix bank_method_order a ["account_lookup", "open_banking"] per començar per aquesta opció. Els quatre últims caràcters del compte introduït determinen la resposta; consulta Prova-ho al sandbox per veure totes les terminacions i un compte vàlid per format. L’API de comprovació de compte respon amb una clau de sandbox segons les mateixes terminacions.

Els documents de mostra

No pugis mai documents d’identitat reals al sandbox. Usa els documents de mostra integrats.
El flux allotjat ofereix tres documents de mostra, un per tipus de document: Toca una mostra de la franja per usar-la en lloc d’una captura real. Les dades extretes i el resultat de la sessió sempre provenen de l’escenari o del valor màgic seleccionat, de manera que qualsevol mostra funciona amb qualsevol escenari.

Identitat de mostra: prova de expected_details

Cada document del sandbox és fabricat a partir d’una identitat fixa. Els valors extrets són els mateixos en cada sessió i mai no es deriven de la data actual, de manera que pots omplir expected_details amb ells i comprovar de principi a fi la comparació de camps i la gestió d’advertències. Si passes els valors següents, les comprovacions de comparació es compleixen; si passes qualsevol altre valor, s’activa a propòsit l’advertència *_MISMATCH_WITH_PROVIDED corresponent. Totes les mostres de document comparteixen les dates: La resta de la identitat depèn del document que usis:
first_name i last_name són l’excepció: el sandbox copia al document fabricat els noms que envies a expected_details, de manera que la comparació de noms té èxit amb qualsevol nom. Usa el valor màgic SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED per provar una discrepància de nom, i SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED per a una discrepància de data de naixement.
Si el teu flux de treball restringeix documents_allowed a un país o tipus de document que exclou l’ePassport del Brasil, el sandbox fabrica un document a partir del primer país permès. Així, nationality, id_country i el nom del document corresponen a aquest país. Les dates anteriors no canvien.

Què no inclou el document fabricat

El document fabricat és la plantilla genèrica del país i del tipus de document permesos, de manera que els camps que només proporciona un document real emès per un estat queden buits. El camp que importa per a l’encaminament és la regió / estat dels EUA (kyc.region): un permís de conduir o un document d’identitat dels EUA del sandbox no té estat. Per això, una condició de branca com Region equals IL mai no coincidirà al sandbox i, si cap altra branca del node tampoc no coincideix, el flux segueix la branca de reserva del node (la branca sense condicions). Això no és una revisió ni un error de la branca: la condició simplement no té res per llegir. Un camp absent també fa fallar not equals i not in; consulta com les condicions de branca llegeixen les dades de la sessió per veure la diferència entre un camp absent i una cadena buida. Per provar un flux que depèn de l’estat al sandbox, decideix a partir d’un valor que controlis a la sessió i no del document:
  • Envia l’estat a metadata quan crees la sessió (per exemple, "metadata": {"credential_state": "IL"}) i fes la branca sobre metadata.credential_state. Al sandbox, les metadades s’avaluen exactament igual que en producció.
  • Mantén la condició kyc.region, derivada del document, per al trànsit en producció si també necessites que el document acrediti l’estat; en mode producció la regió es llegeix del document real.
La resta de l’encaminament és idèntica a producció: el graf del flux de treball, les condicions de branca, els valors de metadata i expected_details, els nodes d’acció i els nodes d’estat s’executen de veritat. El sandbox mai no força una sessió a revisió per si sol: una sessió del sandbox acaba En revisió només quan el flux de treball l’encamina allà (un escenari review_*, un valor màgic assignat a una acció de revisió o un node d’estat al graf).

Codis OTP i opció d’activar l’enviament de correus electrònics

  • OTP de telèfon: la comprovació de telèfon del sandbox accepta qualsevol codi ben format (de 4 a 8 dígits; 123456 inclòs). Les entrades mal formades continuen retornant 400.
  • OTP de correu electrònic: la comprovació de correu del sandbox accepta qualsevol codi ben format (123456 inclòs). Les entrades mal formades continuen retornant 400.
Per defecte, les sessions del sandbox no envien correus electrònics (alertes de revisió, canvis d’estat, OTP, reenviaments, enllaços de nova sessió, etc.). Per enviar un correu igualment, usa un d’aquests patrons per activar l’enviament a l’adreça del destinatari:

Dirigir els resultats: escenaris, valors màgics, armat i l’endpoint de simulació

Hi ha cinc maneres de controlar el resultat d’una sessió sandbox.

1. sandbox_scenario en crear la sessió

Defineix el slug de l’escenari en crear la sessió (POST /v3/session/). El flux de creació expandeix els valors màgics inclosos a l’escenari als camps d’entrada de la sessió, de manera que els proveïdors simulats emetin el resultat previst a través de la canalització real del flux de treball.

2. Valors màgics introduïts manualment

Defineix tu mateix els camps d’entrada individuals (per exemple expected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED", o user_email = "sandbox+aml_hit@didit.test"). Consulta el registre complet a la taula de valors màgics de més amunt.

3. Armar (o tornar a armar) la sessió abans que comenci el flux

Defineix o substitueix l’escenari armat en una sessió que ja existeix, sempre que no hagi avançat més enllà de Not Started. Aquest és l’endpoint que crida el selector d’escenaris abans del flux, i tu el pots cridar directament per construir un selector personalitzat o un entorn de prova:
Resposta 200:
  • Autentica’t amb el Session-Token propi de la sessió (que es retorna com a session_token en crear la sessió), no amb la clau d’API de la teva aplicació: és un endpoint de cara al client.
  • Retorna 400 per a un slug d’escenari desconegut, i també 400 una vegada la sessió ha superat Not Started ("Scenario can only be armed before the verification starts.").
  • Retorna 404 quan el Session-Token pertany a una aplicació en producció (no sandbox), o quan no coincideix amb el session_id de la ruta.
  • Tornar a armar substitueix l’escenari anterior. Només esborra els valors màgics que va escriure l’escenari anterior, i deixa intacte tot el que l’usuari ja hagi introduït manualment (correu electrònic, nom, etc.). Per exemple: si armes decline_phone_high_risk i després armes approve, el número de telèfon torna a no estar definit, però un correu electrònic introduït pel client es conserva en totes dues crides.

4. L’endpoint de simulació

Força un estat final a posteriori:
  • Consola / clau d’API (requereix el privilegi write:sessions; una clau d’API amb àmbit necessita accés d’escriptura a les sessions): POST /v3/session/{session_id}/simulate/
  • Flux allotjat (capçalera Session-Token): POST /v3/session/{session_id}/sandbox/simulate/
Tots dos funcionen amb sessions sandbox de KYC i de KYB. Una sessió en producció (no sandbox) retorna 404, i també ho fa un Session-Token que no coincideixi amb el session_id de la ruta. Cada camp del cos és opcional, però cal almenys un de new_status, scenario o risk: send_webhooks: true envia exactament els webhooks que envia un canvi d’estat real: status.updated, i també els esdeveniments user.status.updated i user.data.updated (o business.status.updated i business.data.updated en una sessió d’empresa) que el canvi provoca, cap als destins subscrits a aquests esdeveniments. Amb send_webhooks: false l’estat sí que canvia, però no es registra ni s’envia cap webhook. La recuperació de webhooks perduts mai torna a enviar aquesta decisió, i la consola es continua actualitzant en directe. El següent canvi d’estat de la sessió envia webhooks com de costum.
Resposta 200:
  • status és l’estat que ha establert la simulació, i previous_status és el que tenia la sessió abans.
  • scenario repeteix el teu slug i risk és el cas de risc aplicat; cadascun és null quan no n’hi ha cap.
  • send_webhooks repeteix el valor aplicat.
  • Retorna 400 per a un escenari o un risc desconeguts, quan no es pot derivar cap new_status, per a qualsevol altre new_status, i quan la sessió ja té l’estat sol·licitat (["The new status is the same as the current status."]).

5. sandbox_scenario a l’API AML independent

El cribratge AML de back-end no té usuari final ni sessió a armar, de manera que el slug va a la mateixa sol·licitud de cribratge (POST /v3/aml/):
  • decline_aml_hit retorna una coincidència amb el format de producció i resol el cribratge com a Declined; review_aml_possible_match el resol com a In Review. Un escenari que no arma cap resultat AML deixa el cribratge net.
  • Amb save_api_request: true (el valor per defecte) el cribratge es persisteix exactament igual que amb una clau de producció, de manera que el request_id retornat es pot consultar mitjançant GET /v3/session/{request_id}/decision/ i GET /v3/session/{request_id}/generate-pdf/.
  • Retorna 400 per a un slug d’escenari desconegut, i 400 quan la clau d’API pertany a una aplicació en producció.

On apareix sandbox_scenario

El slug de l’escenari armat (null si no n’hi ha cap) es retorna en alguns punts i s’omet intencionadament en d’altres: Si la teva integració necessita bifurcar segons l’escenari armat al servidor, llegeix-lo de l’embolcall del webhook o de qualsevol dels dos endpoints de decisió (v1 o v3).

Ús i facturació

L’ús de sandbox es registra, però mai es cobra:
  • Cada crida simulada registra igualment un esdeveniment d’ús (is_sandbox: true, amb un preu de 0.0000), perquè el volum del sandbox sigui visible per a la depuració. Tot i això, mai se suma als teus totals d’ús, mai es descompta del saldo i mai apareix en una factura.
  • Les superfícies de saldo, de recàrrega i d’ús en producció de la Business Console filtren l’ús del sandbox per defecte. Els endpoints d’ús de recàrregues accepten el paràmetre environment (live, el valor per defecte, o sandbox), perquè el volum del sandbox es pugui consultar per separat. Això sempre es fa sense cost i sense consumir el pla gratuït.
  • La verificació de correu electrònic i de telèfon es factura per sol·licitud, no pel resultat de la sessió, i el sandbox no pot reproduir això del tot a la capa de webhook. Les comprovacions de correu electrònic i de telèfon del sandbox registren igualment un esdeveniment d’ús per sol·licitud, a preu 0.0000, igual que qualsevol altra funcionalitat simulada. Aquesta és una divergència acceptada i coneguda respecte del comportament de facturació en producció, i no és un error.
  • L’estructura de la resposta de la validació de bases de dades en sandbox divergeix intencionadament de la de cada proveïdor en producció, ja que no hi ha cap proveïdor real que reproduir. Considera els payloads de validació de bases de dades del sandbox com un substitut del resultat (estat i codi d’advertència), no com una previsualització byte a byte de la resposta d’un proveïdor en producció.
Darrera modificació el 7 de novembre del 2026