Cambios y versiones

Cómo versionamos

La versión mayor va en la ruta: /api/integrations/v1. Dentro de una versión mayor solo hacemos cambios compatibles, que no deberían romper una integración bien hecha:

• Añadir endpoints nuevos.
• Añadir campos opcionales a las peticiones.
• Añadir campos a las respuestas y a las cargas de los webhooks.
• Añadir valores nuevos a un enumerado de respuesta (un outcome o un status nuevo).
• Añadir tipos de evento de webhook (solo los recibirás si te suscribes a ellos).
• Añadir tipos de error (type) nuevos o cambiar la redacción de title y detail.

Para que esto no te afecte:

• Ignora los campos que no conozcas en las respuestas y en los webhooks; no falles si aparece uno nuevo.
• Trata con un caso por defecto los valores de enumerado desconocidos.
• Decide por status y type, nunca por el texto de los mensajes.

Un cambio incompatible (quitar o renombrar un campo, hacer obligatorio uno opcional, cambiar el significado de un valor) solo llegaría con una nueva versión mayor (/v2). En ese caso mantendríamos la v1 funcionando en paralelo durante un periodo de transición y te avisaríamos por correo con antelación suficiente para adaptarte.

Los avisos de cambios (y de mantenimientos programados) se envían por correo al contacto técnico que nos diste. Si cambia, dínoslo.

Registro de cambios

v1.0 — octubre de 2026

Primera versión pública de la API de integración.

Avisos y catálogo

• GET /catalog, POST /visits (con Idempotency-Key), GET /visits, GET /visits/{id}, POST /visits/{id}/cancel y GET /visits/{id}/report.
• serviceTypeCode en el alta (o serviceTypeId): el código es el mismo en los dos entornos; si llegan los dos, manda serviceTypeCode.
• Tiempo estimado por bloques (estimatedMinutes).
• GET /visits/{id}/eta: hora estimada de llegada con la unidad en camino.

Autenticación y entornos

• X-Api-Key con ámbitos visits:write, visits:read y reports:read, y límite de peticiones por clave.
• Claves con prefijo de entorno: srd_live_… (producción) y srd_test_… (pruebas). Una clave en el entorno equivocado responde 401 /errors/provider-api/wrong-environment. Las claves emitidas antes con el formato srd_<prefijo>_<secreto> siguen funcionando en producción.
• Cabecera X-Serad-Environment (production o sandbox) en todas las respuestas.
• Entorno de pruebas (sandbox) en https://sandbox-api.saludenruta.es/api/integrations/v1, con su propia base de datos y un simulador que hace avanzar los avisos y envía los webhooks como en producción. Endpoints solo de sandbox: POST /sandbox/visits/{id}/advance y POST /sandbox/reset, y la cabecera X-Sandbox-Simulation: manual en el alta.

Webhooks

• Firmados con HMAC-SHA256: visit.created, visit.assigned, visit.en_route, visit.on_site, visit.finished, visit.cancelled, visit.invoiced y report.shared.
• 12 intentos con espera exponencial (de 30 s a 1 h, unas 5 horas en total) y reenvío manual.

Referencia

• Errores en formato RFC 9457.
• GET /openapi.json: especificación OpenAPI 3.1 pública, con los webhooks.
• Esta documentación para desarrolladores.