Sandbox
Sandbox
El entorno de pruebas del gateway: respuestas deterministas, sin dinero ni datos reales, decididas por la llave y no por la URL. Qué simula cada módulo, en qué se diferencia de producción, relojes de prueba, simuladores y la CLI.
En esta página
El sandbox es el gateway respondiendo con un motor simulado: los mismos endpoints, los mismos cuerpos de petición y de respuesta, los mismos códigos de error, pero sin tocar el motor real, sin mover dinero y sin datos de afiliados reales. Es donde construyes y pruebas tu integración completa antes de pedir la llave de producción.
Tres propiedades que debes conocer #
1. La llave decide, no la URL #
Toda llave de API se emite para un entorno: sandbox o prod. Con una llave de sandbox el
gateway responde con el motor simulado en cualquier URL a la que llames; con una llave de
producción llega al motor real. No hay forma de “apuntar mal”: el comportamiento lo fija la llave.
| Entorno | URL base | Python / JS / PHP | .NET | Go |
|---|---|---|---|---|
| Producción | https://api.compense.co | "production" (por defecto) | CompenseEnvironment.Production | compense.Production |
| Sandbox | https://sandbox.dev.compense.co/gw | "sandbox" | CompenseEnvironment.Sandbox | compense.Sandbox |
| Dev | https://gateway.dev.compense.co | "dev" | CompenseEnvironment.Dev | compense.Dev |
En la práctica: usa la URL de sandbox con tu llave de sandbox mientras integras, y al salir a producción cambia las dos cosas (llave y URL) por configuración, sin tocar código. Más en Entornos.
2. Es determinista #
La misma petición produce la misma respuesta (salvo el campo generated_at). No hay azar: el
resultado depende del documento de prueba que envías, de algunos montos mágicos y de los
valores que eliges. Gracias a eso puedes escribir pruebas automáticas estables que afirmen, por
ejemplo, que CC 1000000002 siempre es rechazado por NOT_ELIGIBLE. Todos los cuerpos del sandbox
traen "environment": "sandbox".
3. No guarda estado #
El sandbox no tiene base de datos: el estado de cada objeto viaja en su id. Una solicitud de
crédito radicada con CC 1000000001 recibe un id sbx-E-… (la E es el perfil “elegible”), y una
consulta, decisión o desembolso posterior con ese id responde de forma coherente. Consecuencias:
- Repetir una escritura con los mismos datos devuelve el mismo id (idempotencia natural).
- Una escritura devuelve el estado nuevo, pero no cambia lo que devuelven las lecturas posteriores
(por ejemplo, responder una PQRS no la deja
resolveden el siguienteGET; registrar un pago de cartera no reduce la deuda). - Los webhooks no se emiten: el sandbox no hace
POSTa tus endpoints (ver Probar tus webhooks).
Qué simula cada módulo #
| Módulo | Qué puedes probar |
|---|---|
| Afiliados | Cinco documentos con perfil fijo (elegible, inelegible, revisión manual, con deudas, inexistente). |
| Créditos | Radicar, decidir, desembolsar y consultar; rechazo por perfil o por monto mayor a 50.000.000. |
| Subsidios y cuota monetaria | El mismo ciclo que créditos; generación de cuota monetaria por perfil. |
| Billetera | Saldo por perfil, P2P, Bre-B, pago de facturas y recargas con sus errores documentados; bolsillos, tarjetas y FX. |
| Cartera | Un préstamo al día, uno en mora y uno castigado; validación de recaudos. |
| Salud | Catálogo, cupos, citas, facturas de salud y pagos del pagador. |
| Administrativo | Colaboradores, novedades, periodos de nómina, comprobantes, terceros y tesorería. |
| PQRS | Radicar, responder, cambiar estado y una bandeja fija de 5 PQRS. |
| Webhooks | Endpoints, secretos y tres entregas fijas; sin envío HTTP real. |
| Solo sandbox | Relojes de prueba y simuladores de ciclo de vida. |
Todos los documentos, montos e ids de prueba están en Datos de prueba.
Diferencias con producción #
| Aspecto | Sandbox | Producción |
|---|---|---|
| Motor | Simulado y determinista | Real |
| Dinero | No se mueve | Se mueve |
| Afiliados | Catálogo de prueba (1000000001…1000000004, 9999999999) | Tus afiliados |
| Documento desconocido | Se trata como elegible (para que cualquier prueba fluya) | 404 si no existe |
| Estado | Viaja en el id; las escrituras no cambian lecturas posteriores | Persistente |
| Webhooks | No se envían; el catálogo es de muestra | Entregas reales firmadas |
| Idempotencia | Natural (misma petición, mismo id) y además la del gateway | La del gateway |
Rutas sandbox/* (relojes, simuladores) | Disponibles | 403 con una llave de producción |
| Autenticación, scopes, límites de tasa | Iguales | Iguales |
Lo que el sandbox no puede probar
La latencia y los tiempos de espera reales de los proveedores, la recepción de webhooks (para eso
usa una llave de producción en el ambiente dev, ver Probar tus webhooks)
y los datos de tus afiliados. Planea una ronda de pruebas en dev antes de producción.
Herramientas solo para el sandbox #
Además de simular los módulos, el sandbox trae operaciones que solo existen en él (tag sandbox
del API, sin scope propio: las autoriza que la llave sea de sandbox):
- Relojes de prueba: una fuente de tiempo virtual que puedes adelantar para probar lo que depende del paso del tiempo.
- Simuladores de ciclo de vida: avanzan una transferencia de billetera o un desembolso de crédito un estado a la vez, hasta su estado terminal, incluidos los fallos.
- CLI
compense: órdenes de consola para webhooks y sandbox, incluida en los SDK de Python y JavaScript.