Frequently asked questions

Access and environments

How do I get a key?

Ask the technical team (info@saludenruta.es). We first give you a test key (srd_test_…) and, once we've validated the integration with you, the production one. See getting started.

Does the sandbox cost anything?

No. Nothing is invoiced in the sandbox and you can create as many visits as you like (within your rate limit).

Why doesn't the serviceTypeId I use in the sandbox work in production?

Because they're separate databases and the id values don't match. Use serviceTypeCode, which is the same in both environments. See environments.

I get a 401 with a key I've just copied.

Check that it's in the X-Api-Key header (not in the URL or as a Bearer token), that you copied all of it, and that you're using the key for the right environment (srd_test_ with the sandbox, srd_live_ with production). If the type is wrong-environment, it's the last one. If everything checks out, email us with the key's prefix.

Can I call the API from the browser or a mobile app?

No. The key is secret and would give anyone who extracted it access to your organisation's visits. Always make calls from your server. See best practices.

Visits

Can I change a visit I've already created?

Not through the API. If the visit can still be cancelled, cancel it and create a new one with the correct details. If it can't, or if it's a minor change (a phone number, access notes), call the dispatch centre (+34 611 673 280).

Why can't I cancel a visit?

Because the unit has already set off (EN_ROUTE) or is on site (ON_SITE), or the visit has already finished. Only PENDING or ASSIGNED visits can be cancelled through the API; in every other case you have to call the dispatch centre. See cancel.

How long does the unit take to arrive?

It depends on the priority, the area and the workload at the time. For a specific visit, once the unit is en route, GET /visits/{id}/eta gives you the estimated time.

Do you handle emergencies?

No. Salud en Ruta provides home care for non-life-threatening urgent cases. In a life-threatening emergency, the patient must call 112. Don't send visits that need an ambulance through the API.

Can I send visits for any address?

Coverage is the city of Madrid and the Community of Madrid. If you're unsure about an area, ask us.

What happens if I send a visit with a DNI that already exists under a different name?

The visit is created as usual and the responses show the name you sent. Internally, the dispatch centre reviews the match. See patients and privacy.

How do I find a visit if I didn't store its id?

By your case number: GET /visits?externalRef=EXP-2026-004512. That's why we recommend always sending it.

Webhooks

I'm not receiving webhooks.

Check that your URL is public HTTPS (not localhost or an internal IP address), that it doesn't redirect, that the certificate is valid and that you respond with a 2xx within 10 seconds. Ask us for a webhook.test and we'll tell you what response we got from your server. See test your receiver.

The signature never matches.

It's almost always because it's computed over a body that has already been parsed into an object and serialised again. Use the raw body exactly as it arrives (in Express, express.raw(); in Flask, request.get_data(); in PHP, php://input). Also check that you're using the full secret, with whsec_, and test your function with the sample case.

I receive the same event twice.

That's expected: retries guarantee you don't lose events, at the cost of some arriving more than once. Discard duplicates by the event id. See receiver idempotency.

Events arrive out of order.

That can also happen with retries. Use data.visit.status and the milestones to know where the visit is, rather than the order of arrival.

Reports and data

Why can't I download the report?

Because it hasn't been signed or shared yet, or because the patient hasn't consented to it being sent to you. Without consent there's no report. See care report.

Can I get the diagnosis or treatment through the API?

Only through the care report, with the patient's consent. The API doesn't return individual clinical data. See what we never return.

Is there an official library (SDK)?

Not yet. The API is plain REST and there are samples in six languages; you can also use the openapi.json to generate a client for your language with OpenAPI Generator.