Primeros pasos

Cómo se consigue acceso

El acceso a la API lo habilita Salud en Ruta para cada proveedor con contrato. No hay registro público: así nos aseguramos de que cada clave corresponde a una organización con la que tenemos un acuerdo de tratamiento de datos.

1. Pide el acceso escribiendo al equipo técnico (info@saludenruta.es) con el nombre de tu organización, una persona de contacto técnico y, si ya la tienes, la URL donde quieres recibir los webhooks de pruebas.
2. Te damos una clave de pruebas (srd_test_…) y activamos tu entorno de pruebas (sandbox), con tu mismo catálogo de servicios y datos ficticios. Si nos has dado una URL, también el secreto del webhook (whsec_…).
3. Desarrollas y pruebas contra el sandbox todo lo que necesites: no hay coste ni riesgo, y los avisos avanzan solos gracias al simulador.
4. Validamos la integración contigo siguiendo la lista de comprobación: alta de avisos, cancelación, recepción y verificación de webhooks, gestión de errores.
5. Te damos la clave de producción (srd_live_…) y el secreto del webhook de producción. A partir de ahí, cada aviso es real: llega a la centralita y sale una unidad.

Tu primera integración en 5 minutos

Necesitas tu clave de pruebas y, para el último paso, una URL pública donde recibir webhooks (para probar, sirve un servicio como webhook.site o un túnel tipo ngrok hacia tu equipo). Los ejemplos usan curl; en ejemplos de código tienes los mismos pasos en JavaScript, Python, PHP, Java y C#.

Guarda la clave en una variable de entorno para no escribirla en cada comando:

export SERAD_API_KEY="srd_test_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
export SERAD_API_URL="https://sandbox-api.saludenruta.es/api/integrations/v1"

1. Consulta tu catálogo

El catálogo te dice qué tipos de servicio puedes pedir y si tu contrato exige nº de expediente:

curl "$SERAD_API_URL/catalog" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "providerType": "INSURER",
    "requiresExternalRef": true,
    "serviceTypes": [
      { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general", "requiredProfessional": "DOCTOR" },
      { "id": "0c7f3a52-3f1d-4b8e-9d6a-2f4b5c6d7e8f", "code": "NURSING_CARE", "name": "Curas de enfermería", "requiredProfessional": "NURSE" }
    ],
    "insurers": []
  },
  "message": "Se ha obtenido el catálogo"
}

Si la respuesta es un 401, revisa la clave y que estás usando la URL del sandbox con una clave srd_test_… (entornos).

2. Crea un aviso

Usa el code de uno de tus tipos de servicio y envía una Idempotency-Key única (si la petición se corta y la repites con la misma clave, no se crea un aviso duplicado):

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: primeros-pasos-0001" \
  -d '{
    "patient": {
      "firstName": "María",
      "lastName": "García López",
      "documentType": "DNI",
      "documentNumber": "12345678Z",
      "birthDate": "1948-05-17",
      "phone": "+34600111222"
    },
    "address": {
      "line1": "Calle de Alcalá 120",
      "line2": "3º B",
      "city": "Madrid",
      "postalCode": "28009"
    },
    "serviceTypeCode": "GENERAL_CONSULTATION",
    "priority": "URGENT",
    "reason": "Fiebre alta desde ayer, 39 ºC",
    "externalRef": "EXP-2026-004512"
  }'

La respuesta (201 Created) es el aviso, con su id y su code legible (AV-000123):

{
  "status": 201,
  "data": {
    "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Pendiente",
    "priority": "URGENT",
    "origin": "PROVIDER_API",
    "externalRef": "EXP-2026-004512",
    "serviceType": { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general" },
    "requiredProfessional": "DOCTOR",
    "patientName": "María García López",
    "address": { "line1": "Calle de Alcalá 120", "city": "Madrid", "postalCode": "28009" },
    "estimatedMinutes": 60,
    "milestones": { "requestedAt": "2026-10-01T09:10:00.000Z", "assignedAt": null, "departedAt": null, "arrivedAt": null, "finishedAt": null, "cancelledAt": null, "invoicedAt": null },
    "cancellable": true,
    "reportAvailable": false
  },
  "message": "Se ha creado el aviso"
}

Guarda el id: es el identificador del aviso en todas las demás llamadas.

3. Consulta el aviso

En el sandbox, el simulador hace avanzar el aviso solo cada 20 segundos: asignado, en camino, en el domicilio y finalizado. Consulta su estado:

curl "$SERAD_API_URL/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201" \
  -H "X-Api-Key: $SERAD_API_KEY"

Verás cómo cambian status, los milestones (la hora de cada hito) y la timeline. En una integración real no harías esto en bucle: para eso están los webhooks.

4. Recibe tu primer webhook

Pide al equipo técnico que dé de alta tu URL de pruebas para los eventos que te interesen (lo normal: todos). Te daremos un secreto whsec_… para verificar la firma. A partir de ahí, cada cambio de estado de tus avisos llega a tu URL como un POST:

POST /serad/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: SaludEnRuta-Webhooks/1.0
X-Serad-Event: visit.assigned
X-Serad-Delivery: 9b2f0c4e-1a7d-4e3b-8f6a-5c4d3b2a1f0e
X-Serad-Timestamp: 1790846100
X-Serad-Signature: sha256=5d1c…e9a0

{"id":"6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f","type":"visit.assigned","createdAt":"2026-10-01T09:15:00.000Z","data":{"visit":{"id":"c6a3c348-40b6-4158-a44a-7d85f01a0201","code":"AV-000123","status":"ASSIGNED", …}}}

Crea otro aviso y comprueba que te llegan visit.created, visit.assigned, visit.en_route, visit.on_site y visit.finished. Tu receptor tiene que responder 2xx en menos de 10 segundos; si no, reintentamos.

Y después

• Lee la guía de avisos para conocer todos los campos, las prioridades y las citas programadas.
• Implementa la verificación de la firma y la deduplicación de webhooks.
• Gestiona los errores y los límites de uso.
• Prueba los escenarios recomendados antes de pedir la clave de producción.