Sandbox and simulator

What it is

The sandbox is an isolated test environment for building and validating your integration without touching anything real: a separate deployment of the same API, with its own database, at https://sandbox-api.saludenruta.es/api/integrations/v1. There:

• Paths, fields, errors, signatures and webhook retries are the same as in production.
• Your provider is configured as in production: same type, same service catalogue (with different id values; use the codes, see environments), same end insurers and the same case number requirement.
• There's no dispatch centre and no real units: visits are moved forward by a simulator.
• No emails, notifications, prescriptions or staff alerts are sent, and nothing is invoiced.
• Keys are srd_test_…. A production key here, or a test key in production, gets a 401 /errors/provider-api/wrong-environment.
• Every response carries X-Serad-Environment: sandbox.

The simulator

When you create a visit in the sandbox, the simulator moves it forward on its own, one step every 20 seconds:

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

• Each step sends the same webhooks as production (visit.assigned, visit.en_route…), with the same shape, signature and retries.
• On assignment, the simulator sets a fictitious unit for the day, medical or nursing depending on the service type, so unitType and unit come out just as in production.
• While the visit is en route, GET /visits/{id}/eta returns a simulated estimated time (arrival is the next step).
• The final outcome is always ATTENDED. For other outcomes, or to cancel, use manual simulation.
• Visits end in FINISHED: there's no validation or invoicing in the sandbox, so they never reach INVOICED and visit.invoiced is never sent.

Manual simulation

To test a specific scenario (cancelling with the unit assigned, a visit that stays en route for a good while), create the visit with the X-Sandbox-Simulation: manual header. That visit doesn't move forward on its own: you move it.

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

Advance a visit

POST /sandbox/visits/{id}/advance (scope visits:write) moves it to the next status, or to the one you specify in to:

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

# Straight to on site (goes through the intermediate statuses)
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" }'

• If you skip statuses (from PENDING to ON_SITE), the visit goes through the intermediate ones and you receive the webhook for each, in order.
• The response is the visit with its timeline, like GET /visits/{id}.
• Asking for an earlier or disallowed status (from EN_ROUTE to ASSIGNED, or moving a visit that has already finished) returns 400 /errors/sandbox/visit-not-advanceable, with a message such as "El aviso AV-000004 está en camino y no puede pasar a «asignado».".
• You can also use advance on automatic visits so you don't have to wait the 20 seconds.

Reset the environment

POST /sandbox/reset (scope visits:write) deletes all your test visits and the patients that only appeared in them, so you can start a test run from scratch:

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" }

It only affects your organisation and only the sandbox. Your catalogue, keys and webhooks are left untouched.

Recommended test scenarios

Before asking for your production key, run through these scenarios in the sandbox. They're the ones we'll go through with you during validation (see the go-live checklist).

For each scenario, start with POST /sandbox/reset if you want a clean environment.

Test data

Use made-up data but in a valid format, because it's validated just as in production: