Sandbox y simulador

Qué es

El sandbox es un entorno de pruebas aislado para desarrollar y validar tu integración sin tocar nada real: otro despliegue de la misma API, con su propia base de datos, en https://sandbox-api.saludenruta.es/api/integrations/v1. Allí:

• Las rutas, los campos, los errores, las firmas y los reintentos de los webhooks son los mismos que en producción.
• Tu proveedor está configurado como en producción: mismo tipo, mismo catálogo de servicios (con otros id; usa los códigos, ver entornos), mismas aseguradoras finales y la misma exigencia de nº de expediente.
• No hay centralita ni unidades reales: los avisos los mueve un simulador.
• No sale ningún correo, notificación, receta ni aviso al personal, y no se factura nada.
• Las claves son srd_test_…. Una clave de producción aquí, o una de pruebas en producción, recibe 401 /errors/provider-api/wrong-environment.
• Todas las respuestas llevan X-Serad-Environment: sandbox.

El simulador

Cuando creas un aviso en el sandbox, el simulador lo hace avanzar solo, un paso cada 20 segundos:

PENDING ──20 s──▶ ASSIGNED ──20 s──▶ EN_ROUTE ──20 s──▶ ON_SITE ──20 s──▶ FINISHED (outcome: ATTENDED)

• En cada paso se envían los mismos webhooks que en producción (visit.assigned, visit.en_route…), con la misma forma, firma y reintentos.
• Al asignar, el simulador pone una unidad ficticia del día, médica o de enfermería según el tipo de servicio, así que unitType y unit salen como en producción.
• Con el aviso en camino, GET /visits/{id}/eta devuelve una hora estimada simulada (la llegada es el siguiente paso).
• El resultado final es siempre ATTENDED (atendido). Para otros finales, o para cancelar, usa la simulación manual.
• Los avisos acaban en FINISHED: en el sandbox no hay validación ni facturación, así que nunca llegan a INVOICED ni se envía visit.invoiced.

Simulación manual

Para probar un escenario concreto (cancelar con la unidad asignada, un aviso que se queda en camino un buen rato), crea el aviso con la cabecera X-Sandbox-Simulation: manual. Ese aviso no avanza solo: lo mueves tú.

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: prueba-manual-0001" \
  -H "X-Sandbox-Simulation: manual" \
  -d @aviso.json

Avanzar un aviso

POST /sandbox/visits/{id}/advance (ámbito visits:write) lo lleva al siguiente estado, o al que indiques en to:

# Al siguiente estado (PENDING → ASSIGNED)
curl -X POST "$SERAD_API_URL/sandbox/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201/advance" \
  -H "X-Api-Key: $SERAD_API_KEY"

# Directamente a en el domicilio (pasa por los intermedios)
curl -X POST "$SERAD_API_URL/sandbox/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201/advance" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "ON_SITE" }'

• Si saltas estados (de PENDING a ON_SITE), el aviso pasa por los intermedios y recibes el webhook de cada uno, en orden.
• La respuesta es el aviso con su línea de tiempo, como GET /visits/{id}.
• Pedir un estado anterior o no permitido (de EN_ROUTE a ASSIGNED, o mover un aviso ya finalizado) responde 400 /errors/sandbox/visit-not-advanceable, con un mensaje como «El aviso AV-000004 está en camino y no puede pasar a «asignado».».
• También puedes usar advance con avisos automáticos para no esperar los 20 segundos.

Limpiar el entorno

POST /sandbox/reset (ámbito visits:write) borra todos tus avisos de prueba y los pacientes que solo aparecían en ellos, para empezar una batería de pruebas desde cero:

curl -X POST "$SERAD_API_URL/sandbox/reset" \
  -H "X-Api-Key: $SERAD_API_KEY"

{ "status": 200, "data": { "deletedVisits": 12 }, "message": "Operación realizada correctamente" }

Solo afecta a tu organización y solo al sandbox. Tu catálogo, tus claves y tus webhooks no se tocan.

Escenarios de prueba recomendados

Antes de pedir la clave de producción, recorre estos escenarios en el sandbox. Son los que repasaremos contigo en la validación (ver la lista de comprobación).

Para cada escenario, empieza con POST /sandbox/reset si quieres un entorno limpio.

Datos de prueba

Usa datos inventados pero con formato válido, porque se validan igual que en producción: