Avisos

Un aviso es una petición de visita de un profesional sanitario al domicilio de un paciente. Esta guía cubre todo lo que puedes hacer con ellos; los detalles de cada campo también están en la referencia de la API.

Crear un aviso

POST /visits con el paciente, el domicilio, el tipo de servicio y el motivo. Envía siempre una cabecera Idempotency-Key única para esa alta: si la conexión se corta y repites la petición, no se crea un aviso duplicado (idempotencia).

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-exp-2026-004512-1" \
  -d '{
    "patient": {
      "firstName": "María",
      "lastName": "García López",
      "documentType": "DNI",
      "documentNumber": "12345678Z",
      "birthDate": "1948-05-17",
      "sex": "FEMALE",
      "phone": "+34600111222"
    },
    "address": {
      "line1": "Calle de Alcalá 120",
      "line2": "3º B",
      "postalCode": "28009",
      "city": "Madrid",
      "province": "Madrid",
      "accessNotes": "Portal 2, código 1234#. Ascensor al fondo."
    },
    "serviceTypeCode": "GENERAL_CONSULTATION",
    "priority": "URGENT",
    "reason": "Fiebre alta desde ayer, 39 ºC, malestar general",
    "externalRef": "EXP-2026-004512",
    "callerName": "Ana García (hija)",
    "callerPhone": "+34600111333"
  }'

La respuesta es 201 Created con el aviso completo (ver la respuesta del aviso). Si repites la misma petición con la misma Idempotency-Key, recibes 200 OK con el mismo aviso y la cabecera Idempotent-Replayed: true.

Campos del alta

Cabeceras del alta:

Prioridad y citas

Para una cita, envía scheduledFrom (inicio) y estimatedMinutes (cuánto durará la atención). El fin de la cita lo calculamos nosotros: scheduledTo = scheduledFrom + estimatedMinutes.

{
  "priority": "SCHEDULED",
  "scheduledFrom": "2026-10-02T09:00:00+02:00",
  "estimatedMinutes": 40
}

Reglas de la cita:

• scheduledFrom lleva siempre zona horaria (+02:00, Z). Sin ella, el servidor la interpretaría en UTC.
• No puede empezar más de 15 minutos en el pasado (/errors/visits/schedule-in-past): se admite el pequeño retraso entre la llamada del paciente y el alta, pero no programar citas pasadas.
• No puede estar a más de 90 días vista (/errors/visits/schedule-beyond-horizon).
• estimatedMinutes va de 30 a 240 en bloques de 10 (30, 40, 50… 240). Cualquier otro valor responde 400 de validación. Si no lo envías, se asumen 60 minutos.

El tiempo estimado se puede ampliar en la centralita con el aviso en curso; el valor actualizado sale en estimatedMinutes al consultar el aviso.

La dirección

Si no envías coordenadas, geocodificamos la dirección. Si la geocodificación falla o el código postal no cuadra con la calle, el aviso se crea igualmente y la centralita revisa la dirección antes de asignarlo, lo que puede retrasar la salida. Para evitarlo:

• Separa bien los campos: el número en line1, el piso en line2.
• Envía el código postal correcto (es lo que más falla).
• Si tu sistema ya tiene las coordenadas validadas del domicilio, envíalas.

La cobertura es Madrid y la Comunidad de Madrid. Si dudas de si una dirección está cubierta, pregúntanos.

El paciente

Cómo identificamos al paciente. Con el tipo y nº de documento y la fecha de nacimiento buscamos si el paciente ya existe en Salud en Ruta; si existe, el aviso se le asocia (así el profesional tiene su historia); si no, se crea. Sin documento (NONE) no hay forma segura de saber si es la misma persona, así que se crea una ficha nueva cada vez. Por eso te pedimos que envíes siempre el documento y la fecha de nacimiento cuando los tengas. Más detalles, y qué datos devolvemos, en pacientes y privacidad.

Paciente de avisos anteriores. Si un paciente ya tuvo un aviso tuyo, puedes enviar su patientId en lugar de patient. Solo admitimos pacientes de tus avisos: un patientId que no lo sea responde 404 (/errors/patients/not-found), igual que uno que no existe. Lo más sencillo por API, de todas formas, es volver a enviar los datos del paciente: el resultado es el mismo.

Errores frecuentes del alta

Todos los códigos, en errores.

La respuesta del aviso

Todas las operaciones sobre un aviso devuelven la misma estructura (dentro de data):

{
  "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
  "code": "AV-000123",
  "status": "EN_ROUTE",
  "statusLabel": "En camino",
  "priority": "URGENT",
  "origin": "PROVIDER_API",
  "externalRef": "EXP-2026-004512",
  "serviceType": { "id": "57605fe9-bade-4040-b403-5eeb58e57c9e", "code": "GENERAL_CONSULTATION", "name": "Consulta general" },
  "requiredProfessional": "DOCTOR",
  "insurer": null,
  "patientName": "María García López",
  "address": { "line1": "Calle de Alcalá 120", "city": "Madrid", "postalCode": "28009" },
  "serviceDate": "2026-10-01",
  "scheduledFrom": null,
  "scheduledTo": null,
  "estimatedMinutes": 60,
  "milestones": {
    "requestedAt": "2026-10-01T09:10:00.000Z",
    "assignedAt": "2026-10-01T09:15:00.000Z",
    "departedAt": "2026-10-01T09:32:00.000Z",
    "arrivedAt": null,
    "finishedAt": null,
    "cancelledAt": null,
    "invoicedAt": null
  },
  "unit": { "type": "MEDICAL", "label": "Unidad médica" },
  "outcome": null,
  "cancellationReason": null,
  "cancelledWithCharge": false,
  "cancellable": false,
  "reportAvailable": false,
  "invoiceId": null,
  "createdAt": "2026-10-01T09:10:00.000Z",
  "updatedAt": "2026-10-01T09:32:00.000Z"
}

Consultar un aviso

GET /visits/{id} devuelve el aviso con su línea de tiempo (timeline): cada cambio de estado con su hora.

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

{
  "timeline": [
    { "status": "PENDING", "label": "Aviso recibido", "at": "2026-10-01T09:10:00.000Z" },
    { "status": "ASSIGNED", "label": "Unidad asignada", "at": "2026-10-01T09:15:00.000Z" },
    { "status": "EN_ROUTE", "label": "Unidad en camino", "at": "2026-10-01T09:32:00.000Z" }
  ]
}

Un aviso de otro proveedor responde 404, igual que uno que no existe: no confirmamos que existan avisos que no son tuyos.

Listar avisos

GET /visits devuelve tus avisos, del más reciente al más antiguo, paginados.

curl "$SERAD_API_URL/visits?status=PENDING,ASSIGNED,EN_ROUTE&dateFrom=2026-10-01&page=1&limit=50" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "items": [ { "id": "c6a3c348-…", "code": "AV-000123", "status": "EN_ROUTE", "…": "…" } ],
    "pagination": { "page": 1, "limit": 50, "totalItems": 134, "totalPages": 3 }
  },
  "message": "Operación realizada correctamente"
}

Para recorrer todos, pide páginas hasta page = totalPages. Si tu objetivo es mantener tu sistema sincronizado, usa los webhooks y deja el listado para una reconciliación periódica (por ejemplo, cada noche, los avisos del día).

Hora estimada de llegada

Con la unidad en camino (EN_ROUTE), GET /visits/{id}/eta calcula cuánto le falta para llegar, por carretera, desde su última posición conocida:

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

{
  "status": 200,
  "data": {
    "status": "EN_ROUTE",
    "etaMinutes": 14,
    "estimatedArrivalAt": "2026-10-01T09:46:00.000Z",
    "estimated": false,
    "calculatedAt": "2026-10-01T09:32:10.000Z"
  },
  "message": "Operación realizada correctamente"
}

• En cualquier otro estado, o si no hay posición reciente de la unidad, etaMinutes y estimatedArrivalAt son null.
• estimated: true indica que no se pudo calcular la ruta por carretera y la cifra es una aproximación en línea recta: tómala con más margen.
• Nunca devolvemos la posición de la unidad, solo el tiempo.
• La ETA cambia con el tráfico. Si la enseñas al paciente, refréscala cada pocos minutos, no cada segundo (cuenta para tu límite de peticiones).

Cancelar un aviso

POST /visits/{id}/cancel con el motivo:

curl -X POST "$SERAD_API_URL/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201/cancel" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "El paciente ya no necesita la visita" }'

Reglas:

• Solo se puede cancelar por la API mientras el aviso está PENDING o ASSIGNED, y entonces no tiene coste. El campo cancellable de la respuesta te dice si se puede en este momento.
• Con la unidad en camino o en el domicilio, la API responde 409 con el tipo /errors/provider/visit-not-cancellable. En ese caso llama a la centralita (+34 611 673 280): la unidad ya ha salido y hay que avisarla. Según tu contrato, esa cancelación puede tener coste (cancelledWithCharge).
• Un aviso ya finalizado o cancelado tampoco se puede cancelar (mismo 409).
• Al cancelar recibes el webhook visit.cancelled.

Informe asistencial

Cuando el profesional firma el informe de la visita, puedes descargarlo en PDF con GET /visits/{id}/report (ámbito reports:read), solo si:

1. el informe está firmado,
2. Salud en Ruta lo ha compartido con tu organización, y
3. el paciente ha consentido que se te envíe.

curl "$SERAD_API_URL/visits/c6a3c348-40b6-4158-a44a-7d85f01a0201/report" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -o informe-AV-000123.pdf

• La respuesta es el PDF (Content-Type: application/pdf, Content-Disposition: attachment; filename="informe-AV-000123.pdf"), no JSON.
• Si no se cumple alguna de las tres condiciones, responde 404 con el tipo /errors/provider/report-not-available. Sin consentimiento del paciente no hay informe, y no podemos saltarnos esa regla.
• Sabrás que está disponible por el webhook report.shared o por reportAvailable: true al consultar el aviso.
• Cada descarga queda registrada como acceso a datos clínicos, con la clave que la hizo. Descárgalo una vez, guárdalo en tu sistema documental con las medidas que exige el RGPD para datos de salud, y no lo vuelvas a pedir en cada consulta.

Más sobre los datos de salud en pacientes y privacidad.