El sandbox
Con una clave de prueba (ebd_test_…) puedes recorrer el ciclo entero
que va a hacer tu integración —conectar un banco, seguir la operación hasta que termina,
recibir los webhooks firmados y pedir refrescos— contra bancos de prueba. Nada sale a
ningún banco, no se gasta cupo y todo es determinista: la misma llamada da siempre lo mismo.
Lo que se simula es solo el banco; el resto (operaciones, importación, reglas, control de
saldo, traspasos, sesiones y webhooks) es el mismo código que en producción.
1. Los bancos de prueba
Como las tarjetas de prueba de un TPV: cada código hace siempre lo mismo. Salen también en
GET /banks cuando llamas con una clave de prueba.
| Código | Qué hace |
|---|---|
sandbox_ok |
Conecta y refresca bien: la operación termina en imported. |
sandbox_reauth |
Conecta; cada refresco termina con el código 3 y la conexión pasa a connection_needs_reauth. |
sandbox_bad_credentials |
Conectar termina en failed con el código 2000; no se crea conexión. |
sandbox_slow |
Como sandbox_ok, pero la operación sigue en pending unos 20 segundos antes de terminar. |
sandbox_provider_down |
Conecta; después los refrescos responden 502 provider_error con Retry-After. |
sandbox_quota_exhausted |
Conecta; después los refrescos responden 429 provider_quota_exceeded con Retry-After. |
Los rechazos tienen la misma forma que en producción: 409 connection_needs_reauth
con details.connect_url, 502 provider_error y
429 provider_quota_exceeded, estos dos con la cabecera
Retry-After. El banco lento tarda unos 20 segundos.
2. Registra un endpoint del sandbox
Un endpoint registrado con una clave de prueba es del sandbox: recibe solo los avisos del
sandbox, y los endpoints de producción no reciben ninguno. Llegan firmados igual que los de
verdad y con "sandbox": true en el sobre.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/webhooks \
-H "Authorization: Bearer ebd_test_…" -H "Content-Type: application/json" \
-d '{"name":"Pruebas","url":"https://tu-servidor.example/avisos","events":["lectura.terminada","lectura.fallida","conexion.necesita_autorizarse","sesion_de_conexion.completada","sesion_de_conexion.fallida"]}'
3. Conecta un banco de prueba
Con entity, el sandbox hace de titular y la conexión se completa sola:
la operación pasa de pending a imported (o a
failed con sandbox_bad_credentials) y te llega
lectura.terminada. Sin entity,
connect_url abre una página del sandbox para elegir el banco a mano.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/connections \
-H "Authorization: Bearer ebd_test_…" -H "Idempotency-Key: prueba-1" \
-H "Content-Type: application/json" -d '{"entity":"sandbox_ok"}'
curl https://app.easybankdata.com/v1/tenants/{tenant}/operations/{operation} -H "Authorization: Bearer ebd_test_…"
4. Un enlace de conexión, sin navegador
Crea el enlace como en producción. Si lo abres, la página es la de siempre (aceptación incluida)
pero en el paso del banco enseña los bancos de prueba en lugar del de verdad. Para tus pruebas
automáticas, simulate hace de titular: acepta, abre y autoriza, y
recibes sesion_de_conexion.abierta y después
.completada o .fallida.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/connect_sessions \
-H "Authorization: Bearer ebd_test_…" -H "Content-Type: application/json" \
-d '{"entity":"sandbox_ok","external_ref":"cliente-42"}'
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/connect_sessions/{session}/simulate \
-H "Authorization: Bearer ebd_test_…"
Para renovar una conexión del sandbox, crea la sesión con
reauthorize_connection y simúlala: la conexión vuelve a quedar activa.
simulate solo existe con claves de prueba (con una real, 403).
5. Pide refrescos
Igual que en producción: 202 con la operación, la misma
idempotencia con Idempotency-Key y las cabeceras del cupo. Lo que trae es
incremental y los movimientos que ya estaban no se duplican.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/connections/{connection}/refresh \
-H "Authorization: Bearer ebd_test_…" -H "Idempotency-Key: refresco-1"
6. Qué datos trae
Dos cuentas por conexión (corriente y ahorro) con 90 días de movimientos inventados de un negocio: alquiler, nóminas, Seguridad Social, IVA trimestral, luz y teléfono, cuota de préstamo, comisiones, cobros de clientes que se repiten cada mes, liquidaciones de TPV, Bizum, compras con tarjeta, un recibo devuelto cada dos meses y un traspaso mensual a la cuenta de ahorro. Los saldos cuadran con los movimientos, y las categorías de serie, los traspasos, la previsión y las alertas tienen con qué trabajar.
Nada es de nadie: los nombres son inventados y los IBAN tienen dígitos de control válidos sobre la entidad 0000, que no existe.
7. Lleva los movimientos a tu ERP
El ciclo del módulo de un ERP entero, con movimientos de los bancos de prueba: lee los movimientos, llévalos a
tu ERP y márcalos como llevados con PUT /transactions/{transaction}/erp_entry
(o hasta 100 a la vez con PUT /transactions/erp_entries). Para que no se registren
dos veces, la lista se filtra con ?erp_entry=missing. Si registraste un endpoint del
sandbox, te llegan los avisos de lectura y de cuenta nueva.
curl -X PUT https://app.easybankdata.com/v1/tenants/{tenant}/transactions/{transaction}/erp_entry -H "Authorization: Bearer ebd_test_…" -H "Content-Type: application/json" -d '{"reference": "llx_bank:4821", "system": "dolibarr"}'
- La conciliación con facturas no se prueba aquí: se hace en tu ERP, con tus facturas, y EasyBankData no las recibe. El servicio solo guarda esa marca por movimiento.
- La marca del sandbox es del sandbox: una clave real no la ve, ni el panel.
8. Lo que conviene saber
-
El sandbox no se mezcla con lo real. Lo que crea una clave de prueba no lo ve ninguna clave
real ni el panel, no ocupa sitio del plan y no cuenta en el cupo. Una clave de prueba no ve nada
real. Todas sus respuestas llevan
X-Clave-De-Prueba: truey los datos,is_demo: true. -
Funciona con cualquier plan, también la Demo. Con una clave de prueba, conectar,
crear enlaces,
simulatey refrescar no exigen la capacidadapi_solicitudes, porque no gastan nada. El resto de capacidades (webhooks,api_avisos, y las de cada función) responde lo que respondería tu plan, igual que en producción. Con una clave real, conectar sigue exigiendoapi_solicitudes. -
Las reglas de categorías que crees con una clave de prueba van atadas a una cuenta del
sandbox (
account_id): una regla general tocaría los movimientos reales. - El sandbox no lee solo. La ronda automática de lecturas no toca las conexiones del sandbox, y las alertas de tesorería no se evalúan en él.
-
Tolera lo que no conozcas. El sobre de los avisos puede ganar campos (como
sandbox) y pueden aparecer tipos de evento nuevos.
Siguiente: empezar · integrar un ERP · la API entera · qué puede fallar