Changelog and versioning

How we version the API

The major version is in the path: /api/integrations/v1. Within a major version we only make backwards-compatible changes, which shouldn't break a well-built integration:

• Adding new endpoints.
• Adding optional request fields.
• Adding fields to responses and webhook payloads.
• Adding new values to a response enum (a new outcome or status).
• Adding webhook event types (you'll only receive them if you subscribe to them).
• Adding new error types (type) or changing the wording of title and detail.

To make sure this doesn't affect you:

• Ignore fields you don't recognise in responses and webhooks; don't fail if a new one appears.
• Handle unknown enum values with a default case.
• Decide based on status and type, never on message text.

A breaking change (removing or renaming a field, making an optional field required, changing the meaning of a value) would only come with a new major version (/v2). In that case we'd keep v1 running in parallel for a transition period and email you with enough notice to adapt.

Change notices (and scheduled maintenance notices) are emailed to the technical contact you gave us. If that changes, let us know.

Changelog

v1.0 — October 2026

First public version of the integration API.

Visits and catalogue

• GET /catalog, POST /visits (with Idempotency-Key), GET /visits, GET /visits/{id}, POST /visits/{id}/cancel and GET /visits/{id}/report.
• serviceTypeCode when creating a visit (or serviceTypeId): the code is the same in both environments; if both are sent, serviceTypeCode wins.
• Estimated time in steps (estimatedMinutes).
• GET /visits/{id}/eta: estimated arrival time while the unit is en route.

Authentication and environments

• X-Api-Key with the visits:write, visits:read and reports:read scopes, and a per-key rate limit.
• Keys with an environment prefix: srd_live_… (production) and srd_test_… (sandbox). A key used in the wrong environment returns 401 /errors/provider-api/wrong-environment. Keys issued earlier in the srd_<prefix>_<secret> format keep working in production.
• X-Serad-Environment header (production or sandbox) on every response.
• Sandbox at https://sandbox-api.saludenruta.es/api/integrations/v1, with its own database and a simulator that moves visits forward and sends webhooks just like production. Sandbox-only endpoints: POST /sandbox/visits/{id}/advance and POST /sandbox/reset, plus the X-Sandbox-Simulation: manual header when creating a visit.

Webhooks

• Signed with HMAC-SHA256: visit.created, visit.assigned, visit.en_route, visit.on_site, visit.finished, visit.cancelled, visit.invoiced and report.shared.
• 12 attempts with exponential backoff (from 30 s up to 1 h, about 5 hours in total) and manual redelivery.

Reference

• Errors in RFC 9457 format.
• GET /openapi.json: public OpenAPI 3.1 specification, webhooks included.
• This developer documentation.