Referencia de la API · API para desarrolladores

Esta referencia se genera automáticamente a partir de la especificación OpenAPI 3.1 que publica la propia API, así que siempre está al día con lo desplegado. Los ejemplos de curl apuntan al entorno de pruebas; en producción cambia la URL base y la clave.

Todas las respuestas correctas van envueltas en el mismo sobre: { "status": 200, "data": { … }, "message": "…" }, y los listados paginados llevan data.items y data.pagination. Los errores siguen el formato RFC 9457.

Versión: 1.0.0 · OpenAPI 3.1.0
URL base: https://api.saludenruta.es/api/integrations/v1 — Producción
https://sandbox-api.saludenruta.es/api/integrations/v1 — Pruebas (sandbox)
Autenticación: X-Api-Key (cabecera) — Clave del proveedor. Producción: srd_live_…; pruebas (sandbox): srd_test_…

Descargar openapi.json Especificación pública

Provider Integration API (v1)

Avisos, catálogo, informes y sandbox

GET`/catalog`

Tipos de servicio permitidos y aseguradoras finales admitidas

Ámbito: visits:write.

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataProviderCatalogResponseDtoopcional
  Ver campos
  - providerTypestringobligatorio
    Valores
    INSURERINTERMEDIARYPRIVATEOTHER
  - requiresExternalRefbooleanobligatorio
    Si externalRef es obligatorio
  - serviceTypesarray<ProviderCatalogServiceTypeDto>obligatorio
    Tipos de servicio con línea en su tarifa vigente (o todos los activos sin tarifa)
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
    requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
  - insurersarray<ProviderCatalogInsurerDto>obligatorio
    Aseguradoras finales admitidas (solo intermediarios)
    Ver campos
    idstring (uuid)obligatorio
    namestringobligatorio
    Ejemplo
    Sanitas
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X GET "https://sandbox-api.saludenruta.es/api/integrations/v1/catalog" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "providerType": "INSURER",
    "requiresExternalRef": true,
    "serviceTypes": [
      {
        "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
        "code": "GENERAL_CONSULTATION",
        "name": "Consulta general",
        "requiredProfessional": "DOCTOR"
      }
    ],
    "insurers": [
      {
        "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
        "name": "Sanitas"
      }
    ]
  },
  "message": "Operación realizada correctamente"
}

GET`/visits`

Lista avisos del proveedor (filtro por externalRef, estado, fechas)

Ámbito: visits:read. ?externalRef=EXP-… busca por nº de expediente exacto.

Parámetros

Nombre	En	Tipo	Descripción
`page`	consulta	`number`	Número de página (1-indexado)
`limit`	consulta	`number`	Elementos por página
`search`	consulta	`string`	Búsqueda libre (nombre/email según el recurso)
`sortBy`	consulta	`string`	Campo de ordenación
`sortOrder`	consulta	`string`ASC · DESC	—
`status`	consulta	`array<string>`	Uno o varios estados
`priority`	consulta	`string`URGENT · NORMAL · SCHEDULED	—
`dateFrom`	consulta	`string`	Día de servicio desde (incl.)
`dateTo`	consulta	`string`	Día de servicio hasta (incl.)
`externalRef`	consulta	`string`	Nº de expediente exacto
`serviceTypeId`	consulta	`string (uuid)`	—

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataobjectopcional
  Ver campos
  - itemsarray<ProviderVisitResponseDto>opcional
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    AV-000123
    statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
    statusLabelstringobligatorio
    Ejemplo
    Unidad en camino
    prioritystringobligatorio
    Valores
    URGENTNORMALSCHEDULED
    originstringobligatorio
    Valores
    INTRANETPROVIDER_PORTALPROVIDER_API
    externalRefstringopcionalpuede ser null
    Ejemplo
    EXP-2026-004512
    serviceTypeProviderVisitServiceTypeDtoobligatorio
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
    requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
    insurerobjectopcionalpuede ser null
    Aseguradora final
    patientNamestringobligatorio
    Nombre del paciente que envió
    Ejemplo
    María García López
    addressobjectobligatorio
    Domicilio (sin coordenadas ni indicaciones de acceso)
    serviceDatestringobligatorio
    Ejemplo
    2026-09-25
    scheduledFromstring (date-time)opcionalpuede ser null
    scheduledTostring (date-time)opcionalpuede ser null
    Fin de la cita, calculado: inicio + tiempo estimado
    estimatedMinutesnumberobligatorio
    Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
    Ejemplo
    60
    milestonesProviderVisitMilestonesDtoobligatorio
    Ver campos
    requestedAtstring (date-time)obligatorio
    assignedAtstring (date-time)opcionalpuede ser null
    departedAtstring (date-time)opcionalpuede ser null
    arrivedAtstring (date-time)opcionalpuede ser null
    finishedAtstring (date-time)opcionalpuede ser null
    cancelledAtstring (date-time)opcionalpuede ser null
    invoicedAtstring (date-time)opcionalpuede ser null
    unitProviderVisitUnitDtoopcionalpuede ser null
    Solo el tipo de unidad, desde la asignación
    Ver campos
    typestringobligatorio
    Valores
    MEDICALNURSING
    labelstringobligatorio
    Nunca nombres ni matrículas
    Ejemplo
    Unidad médica
    outcomestringopcionalpuede ser null
    Valores
    ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
    cancellationReasonstringopcionalpuede ser null
    cancelledWithChargebooleanobligatorio
    cancellablebooleanobligatorio
    Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
    reportAvailablebooleanobligatorio
    Si hay informe asistencial compartido y descargable
    invoiceIdstring (uuid)opcionalpuede ser null
    createdAtstring (date-time)obligatorio
    updatedAtstring (date-time)obligatorio
  - paginationobjectopcional
    Ver campos
    pagenumberopcional
    Ejemplo
    1
    limitnumberopcional
    Ejemplo
    20
    totalItemsnumberopcional
    Ejemplo
    134
    totalPagesnumberopcional
    Ejemplo
    7
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X GET "https://sandbox-api.saludenruta.es/api/integrations/v1/visits" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "items": [
      {
        "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
        "code": "AV-000123",
        "status": "PENDING",
        "statusLabel": "Unidad en camino",
        "priority": "URGENT",
        "origin": "INTRANET",
        "externalRef": "EXP-2026-004512",
        "serviceType": {
          "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
          "code": "GENERAL_CONSULTATION",
          "name": "Consulta general"
        },
        "requiredProfessional": "DOCTOR",
        "insurer": {},
        "patientName": "María García López",
        "address": {},
        "serviceDate": "2026-09-25",
        "scheduledFrom": "2026-09-25T09:30:00.000Z",
        "scheduledTo": "2026-09-25T09:30:00.000Z",
        "estimatedMinutes": 60,
        "milestones": {
          "requestedAt": "2026-09-25T09:30:00.000Z",
          "assignedAt": "2026-09-25T09:30:00.000Z",
          "departedAt": "2026-09-25T09:30:00.000Z",
          "arrivedAt": "2026-09-25T09:30:00.000Z",
          "finishedAt": "2026-09-25T09:30:00.000Z",
          "cancelledAt": "2026-09-25T09:30:00.000Z",
          "invoicedAt": "2026-09-25T09:30:00.000Z"
        },
        "unit": {
          "type": "MEDICAL",
          "label": "Unidad médica"
        },
        "outcome": "ATTENDED",
        "cancellationReason": "string",
        "cancelledWithCharge": true,
        "cancellable": true,
        "reportAvailable": true,
        "invoiceId": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
        "createdAt": "2026-09-25T09:30:00.000Z",
        "updatedAt": "2026-09-25T09:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 134,
      "totalPages": 7
    }
  },
  "message": "Operación realizada correctamente"
}

POST`/visits`

Crea un aviso

Ámbito: visits:write. Con Idempotency-Key (recomendado), repetir la petición con la misma clave y el mismo cuerpo durante 24 h devuelve el mismo aviso (200, cabecera Idempotent-Replayed: true); con otro cuerpo, 409. El paciente se identifica por documento y se reutiliza si ya existe. externalRef es obligatorio si el proveedor lo exige.

Parámetros

Nombre	En	Tipo	Descripción
`X-Sandbox-Simulation`	cabecera	`string`	Solo sandbox. `manual`: el aviso no avanza solo; muévelo con `POST /sandbox/visits/{id}/advance`
`Idempotency-Key`	cabecera	`string`	Identificador único de la operación en tu sistema (máx. 200 caracteres)

Cuerpo de la petición `ProviderCreateVisitDto`

patientIdstring (uuid)opcional
Paciente de un aviso anterior de este proveedor (GET /client/patients). Si llega, patient no hace falta
patientProviderVisitPatientInputDtoopcional
Datos del paciente. Obligatorio salvo que se indique patientId
Ver campos
- firstNamestringobligatorio
  Ejemplo
  María
- lastNamestringobligatorio
  Ejemplo
  García López
- documentTypestringopcional
  Valores
  DNINIEPASSPORTNONE
  Por defecto
  NONE
- documentNumberstringopcional
  Obligatorio salvo documentType NONE
  Ejemplo
  12345678Z
- birthDatestringopcional
  Ejemplo
  1948-05-17
- sexstringopcional
  Valores
  MALEFEMALEOTHERUNKNOWN
- phonestringopcional
  Ejemplo
  +34600111222
addressVisitAddressInputDtoobligatorio
Domicilio de la visita; se geocodifica si no trae coordenadas
Ver campos
- line1stringobligatorio
  Ejemplo
  Calle de Alcalá 120
- line2stringopcional
  Ejemplo
  3º B
- citystringobligatorio
  Ejemplo
  Madrid
- postalCodestringobligatorio
  Ejemplo
  28009
- provincestringopcional
  Ejemplo
  Madrid
- accessNotesstringopcional
  Ejemplo
  Portal 2, código 1234#
- latitudenumberopcional
  Si falta, se geocodifica
  Ejemplo
  40.4212
- longitudenumberopcional
  Ejemplo
  -3.6765
serviceTypeCodestringopcional
Código del tipo de servicio (GET /catalog). Recomendado: es el mismo en pruebas y en producción, a diferencia del serviceTypeId. Obligatorio si no se indica serviceTypeId
Ejemplo
URG
serviceTypeIdstring (uuid)opcional
Id del tipo de servicio (GET /catalog). Cambia entre entornos: mejor serviceTypeCode. Obligatorio si no se indica serviceTypeCode
prioritystringopcional
Por defecto NORMAL, o SCHEDULED si trae franja
Valores
URGENTNORMALSCHEDULED
scheduledFromstring (date-time)opcional
Ejemplo
2026-09-26T09:00:00+02:00
estimatedMinutesnumberopcional
Tiempo estimado en minutos: bloques de 10 entre 30 y 240. Por defecto 60
Rango
30 – 240
Múltiplo de
10
Ejemplo
60
scheduledTostring (date-time)opcionalobsoleto
Obsoleto: usar estimatedMinutes. Si llega sin él, la duración de la franja se redondea al bloque de 10 min y se usa como tiempo estimado
Ejemplo
2026-09-26T11:00:00+02:00
reasonstringobligatorio
Motivo de la solicitud
Ejemplo
Fiebre alta desde ayer, 39 ºC
externalRefstringopcional
Obligatorio si el proveedor lo exige
Ejemplo
EXP-2026-004512
insurerIdstring (uuid)opcional
Aseguradora final: solo intermediarios, y entre sus aseguradoras gestionadas
callerNamestringopcional
Ejemplo
Ana García (hija)
callerPhonestringopcional
Ejemplo
+34600111333

Respuestas

201Correctaobject
- statusnumberopcional
  Ejemplo
  201
- dataProviderVisitResponseDtoopcional
  Ver campos
  - idstring (uuid)obligatorio
  - codestringobligatorio
    Ejemplo
    AV-000123
  - statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
  - statusLabelstringobligatorio
    Ejemplo
    Unidad en camino
  - prioritystringobligatorio
    Valores
    URGENTNORMALSCHEDULED
  - originstringobligatorio
    Valores
    INTRANETPROVIDER_PORTALPROVIDER_API
  - externalRefstringopcionalpuede ser null
    Ejemplo
    EXP-2026-004512
  - serviceTypeProviderVisitServiceTypeDtoobligatorio
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
  - requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
  - insurerobjectopcionalpuede ser null
    Aseguradora final
  - patientNamestringobligatorio
    Nombre del paciente que envió
    Ejemplo
    María García López
  - addressobjectobligatorio
    Domicilio (sin coordenadas ni indicaciones de acceso)
  - serviceDatestringobligatorio
    Ejemplo
    2026-09-25
  - scheduledFromstring (date-time)opcionalpuede ser null
  - scheduledTostring (date-time)opcionalpuede ser null
    Fin de la cita, calculado: inicio + tiempo estimado
  - estimatedMinutesnumberobligatorio
    Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
    Ejemplo
    60
  - milestonesProviderVisitMilestonesDtoobligatorio
    Ver campos
    requestedAtstring (date-time)obligatorio
    assignedAtstring (date-time)opcionalpuede ser null
    departedAtstring (date-time)opcionalpuede ser null
    arrivedAtstring (date-time)opcionalpuede ser null
    finishedAtstring (date-time)opcionalpuede ser null
    cancelledAtstring (date-time)opcionalpuede ser null
    invoicedAtstring (date-time)opcionalpuede ser null
  - unitProviderVisitUnitDtoopcionalpuede ser null
    Solo el tipo de unidad, desde la asignación
    Ver campos
    typestringobligatorio
    Valores
    MEDICALNURSING
    labelstringobligatorio
    Nunca nombres ni matrículas
    Ejemplo
    Unidad médica
  - outcomestringopcionalpuede ser null
    Valores
    ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
  - cancellationReasonstringopcionalpuede ser null
  - cancelledWithChargebooleanobligatorio
  - cancellablebooleanobligatorio
    Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
  - reportAvailablebooleanobligatorio
    Si hay informe asistencial compartido y descargable
  - invoiceIdstring (uuid)opcionalpuede ser null
  - createdAtstring (date-time)obligatorio
  - updatedAtstring (date-time)obligatorio
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
400Datos inválidos, tipo de servicio no permitido o falta el expedienteProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
403La clave no tiene el ámbito visits:writeProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
409Idempotency-Key reutilizada con otro cuerpo o en cursoProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X POST "https://sandbox-api.saludenruta.es/api/integrations/v1/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -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"
  },
  "serviceTypeId": "57605fe9-bade-4040-b403-5eeb58e57c9e",
  "priority": "URGENT",
  "reason": "Fiebre alta desde ayer",
  "externalRef": "EXP-2026-004512",
  "insurerId": "fe8faeb8-0051-40d5-b0c1-dce10d5f5ba1"
}'

{
  "status": 201,
  "data": {
    "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Unidad en camino",
    "priority": "URGENT",
    "origin": "INTRANET",
    "externalRef": "EXP-2026-004512",
    "serviceType": {
      "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
      "code": "GENERAL_CONSULTATION",
      "name": "Consulta general"
    },
    "requiredProfessional": "DOCTOR",
    "insurer": {},
    "patientName": "María García López",
    "address": {},
    "serviceDate": "2026-09-25",
    "scheduledFrom": "2026-09-25T09:30:00.000Z",
    "scheduledTo": "2026-09-25T09:30:00.000Z",
    "estimatedMinutes": 60,
    "milestones": {
      "requestedAt": "2026-09-25T09:30:00.000Z",
      "assignedAt": "2026-09-25T09:30:00.000Z",
      "departedAt": "2026-09-25T09:30:00.000Z",
      "arrivedAt": "2026-09-25T09:30:00.000Z",
      "finishedAt": "2026-09-25T09:30:00.000Z",
      "cancelledAt": "2026-09-25T09:30:00.000Z",
      "invoicedAt": "2026-09-25T09:30:00.000Z"
    },
    "unit": {
      "type": "MEDICAL",
      "label": "Unidad médica"
    },
    "outcome": "ATTENDED",
    "cancellationReason": "string",
    "cancelledWithCharge": true,
    "cancellable": true,
    "reportAvailable": true,
    "invoiceId": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "createdAt": "2026-09-25T09:30:00.000Z",
    "updatedAt": "2026-09-25T09:30:00.000Z"
  },
  "message": "Operación realizada correctamente"
}

GET`/visits/{id}`

Estado, hitos y línea de tiempo de un aviso

Ámbito: visits:read. Un aviso de otro proveedor responde 404.

Parámetros

Nombre	En	Tipo	Descripción
`id`obligatorio	ruta	`string`	—

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataProviderVisitDetailResponseDtoopcional
  Ver campos
  - idstring (uuid)obligatorio
  - codestringobligatorio
    Ejemplo
    AV-000123
  - statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
  - statusLabelstringobligatorio
    Ejemplo
    Unidad en camino
  - prioritystringobligatorio
    Valores
    URGENTNORMALSCHEDULED
  - originstringobligatorio
    Valores
    INTRANETPROVIDER_PORTALPROVIDER_API
  - externalRefstringopcionalpuede ser null
    Ejemplo
    EXP-2026-004512
  - serviceTypeProviderVisitServiceTypeDtoobligatorio
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
  - requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
  - insurerobjectopcionalpuede ser null
    Aseguradora final
  - patientNamestringobligatorio
    Nombre del paciente que envió
    Ejemplo
    María García López
  - addressobjectobligatorio
    Domicilio (sin coordenadas ni indicaciones de acceso)
  - serviceDatestringobligatorio
    Ejemplo
    2026-09-25
  - scheduledFromstring (date-time)opcionalpuede ser null
  - scheduledTostring (date-time)opcionalpuede ser null
    Fin de la cita, calculado: inicio + tiempo estimado
  - estimatedMinutesnumberobligatorio
    Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
    Ejemplo
    60
  - milestonesProviderVisitMilestonesDtoobligatorio
    Ver campos
    requestedAtstring (date-time)obligatorio
    assignedAtstring (date-time)opcionalpuede ser null
    departedAtstring (date-time)opcionalpuede ser null
    arrivedAtstring (date-time)opcionalpuede ser null
    finishedAtstring (date-time)opcionalpuede ser null
    cancelledAtstring (date-time)opcionalpuede ser null
    invoicedAtstring (date-time)opcionalpuede ser null
  - unitProviderVisitUnitDtoopcionalpuede ser null
    Solo el tipo de unidad, desde la asignación
    Ver campos
    typestringobligatorio
    Valores
    MEDICALNURSING
    labelstringobligatorio
    Nunca nombres ni matrículas
    Ejemplo
    Unidad médica
  - outcomestringopcionalpuede ser null
    Valores
    ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
  - cancellationReasonstringopcionalpuede ser null
  - cancelledWithChargebooleanobligatorio
  - cancellablebooleanobligatorio
    Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
  - reportAvailablebooleanobligatorio
    Si hay informe asistencial compartido y descargable
  - invoiceIdstring (uuid)opcionalpuede ser null
  - createdAtstring (date-time)obligatorio
  - updatedAtstring (date-time)obligatorio
  - timelinearray<ProviderVisitTimelineEntryDto>obligatorio
    Ver campos
    statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
    labelstringobligatorio
    Ejemplo
    Unidad asignada
    atstring (date-time)obligatorio
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
404Aviso no encontradoProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X GET "https://sandbox-api.saludenruta.es/api/integrations/v1/visits/string" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Unidad en camino",
    "priority": "URGENT",
    "origin": "INTRANET",
    "externalRef": "EXP-2026-004512",
    "serviceType": {
      "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
      "code": "GENERAL_CONSULTATION",
      "name": "Consulta general"
    },
    "requiredProfessional": "DOCTOR",
    "insurer": {},
    "patientName": "María García López",
    "address": {},
    "serviceDate": "2026-09-25",
    "scheduledFrom": "2026-09-25T09:30:00.000Z",
    "scheduledTo": "2026-09-25T09:30:00.000Z",
    "estimatedMinutes": 60,
    "milestones": {
      "requestedAt": "2026-09-25T09:30:00.000Z",
      "assignedAt": "2026-09-25T09:30:00.000Z",
      "departedAt": "2026-09-25T09:30:00.000Z",
      "arrivedAt": "2026-09-25T09:30:00.000Z",
      "finishedAt": "2026-09-25T09:30:00.000Z",
      "cancelledAt": "2026-09-25T09:30:00.000Z",
      "invoicedAt": "2026-09-25T09:30:00.000Z"
    },
    "unit": {
      "type": "MEDICAL",
      "label": "Unidad médica"
    },
    "outcome": "ATTENDED",
    "cancellationReason": "string",
    "cancelledWithCharge": true,
    "cancellable": true,
    "reportAvailable": true,
    "invoiceId": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "createdAt": "2026-09-25T09:30:00.000Z",
    "updatedAt": "2026-09-25T09:30:00.000Z",
    "timeline": [
      {
        "status": "PENDING",
        "label": "Unidad asignada",
        "at": "2026-09-25T09:30:00.000Z"
      }
    ]
  },
  "message": "Operación realizada correctamente"
}

GET`/visits/{id}/eta`

Hora estimada de llegada de la unidad (con el aviso en camino)

Ámbito: visits:read. Con la unidad en camino, minutos y hora estimada por carretera desde su última posición. En otros estados, etaMinutes es null. No se devuelve la posición de la unidad.

Parámetros

Nombre	En	Tipo	Descripción
`id`obligatorio	ruta	`string`	—

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataProviderVisitEtaResponseDtoopcional
  Ver campos
  - statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
  - etaMinutesnumberopcionalpuede ser null
    Minutos estimados hasta la llegada; null si no está EN_ROUTE o no hay posición
    Ejemplo
    14
  - estimatedArrivalAtstring (date-time)opcionalpuede ser null
    Hora estimada de llegada
  - estimatedbooleanobligatorio
    true si es una estimación en línea recta (sin OSRM)
  - calculatedAtstring (date-time)obligatorio
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
404Aviso no encontradoProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X GET "https://sandbox-api.saludenruta.es/api/integrations/v1/visits/string/eta" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "status": "PENDING",
    "etaMinutes": 14,
    "estimatedArrivalAt": "2026-09-25T09:30:00.000Z",
    "estimated": true,
    "calculatedAt": "2026-09-25T09:30:00.000Z"
  },
  "message": "Operación realizada correctamente"
}

POST`/visits/{id}/cancel`

Cancela un aviso (solo PENDING/ASSIGNED, sin cargo)

Ámbito: visits:write. Con la unidad en camino, llama a la centralita.

Parámetros

Nombre	En	Tipo	Descripción
`id`obligatorio	ruta	`string`	—

Cuerpo de la petición `ProviderCancelVisitDto`

reasonstringobligatorio
Ejemplo
El paciente ya no necesita la visita

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataProviderVisitResponseDtoopcional
  Ver campos
  - idstring (uuid)obligatorio
  - codestringobligatorio
    Ejemplo
    AV-000123
  - statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
  - statusLabelstringobligatorio
    Ejemplo
    Unidad en camino
  - prioritystringobligatorio
    Valores
    URGENTNORMALSCHEDULED
  - originstringobligatorio
    Valores
    INTRANETPROVIDER_PORTALPROVIDER_API
  - externalRefstringopcionalpuede ser null
    Ejemplo
    EXP-2026-004512
  - serviceTypeProviderVisitServiceTypeDtoobligatorio
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
  - requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
  - insurerobjectopcionalpuede ser null
    Aseguradora final
  - patientNamestringobligatorio
    Nombre del paciente que envió
    Ejemplo
    María García López
  - addressobjectobligatorio
    Domicilio (sin coordenadas ni indicaciones de acceso)
  - serviceDatestringobligatorio
    Ejemplo
    2026-09-25
  - scheduledFromstring (date-time)opcionalpuede ser null
  - scheduledTostring (date-time)opcionalpuede ser null
    Fin de la cita, calculado: inicio + tiempo estimado
  - estimatedMinutesnumberobligatorio
    Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
    Ejemplo
    60
  - milestonesProviderVisitMilestonesDtoobligatorio
    Ver campos
    requestedAtstring (date-time)obligatorio
    assignedAtstring (date-time)opcionalpuede ser null
    departedAtstring (date-time)opcionalpuede ser null
    arrivedAtstring (date-time)opcionalpuede ser null
    finishedAtstring (date-time)opcionalpuede ser null
    cancelledAtstring (date-time)opcionalpuede ser null
    invoicedAtstring (date-time)opcionalpuede ser null
  - unitProviderVisitUnitDtoopcionalpuede ser null
    Solo el tipo de unidad, desde la asignación
    Ver campos
    typestringobligatorio
    Valores
    MEDICALNURSING
    labelstringobligatorio
    Nunca nombres ni matrículas
    Ejemplo
    Unidad médica
  - outcomestringopcionalpuede ser null
    Valores
    ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
  - cancellationReasonstringopcionalpuede ser null
  - cancelledWithChargebooleanobligatorio
  - cancellablebooleanobligatorio
    Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
  - reportAvailablebooleanobligatorio
    Si hay informe asistencial compartido y descargable
  - invoiceIdstring (uuid)opcionalpuede ser null
  - createdAtstring (date-time)obligatorio
  - updatedAtstring (date-time)obligatorio
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
409El aviso ya no se puede cancelar desde la integraciónProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X POST "https://sandbox-api.saludenruta.es/api/integrations/v1/visits/string/cancel" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "El paciente ya no necesita la visita"
}'

{
  "status": 200,
  "data": {
    "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Unidad en camino",
    "priority": "URGENT",
    "origin": "INTRANET",
    "externalRef": "EXP-2026-004512",
    "serviceType": {
      "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
      "code": "GENERAL_CONSULTATION",
      "name": "Consulta general"
    },
    "requiredProfessional": "DOCTOR",
    "insurer": {},
    "patientName": "María García López",
    "address": {},
    "serviceDate": "2026-09-25",
    "scheduledFrom": "2026-09-25T09:30:00.000Z",
    "scheduledTo": "2026-09-25T09:30:00.000Z",
    "estimatedMinutes": 60,
    "milestones": {
      "requestedAt": "2026-09-25T09:30:00.000Z",
      "assignedAt": "2026-09-25T09:30:00.000Z",
      "departedAt": "2026-09-25T09:30:00.000Z",
      "arrivedAt": "2026-09-25T09:30:00.000Z",
      "finishedAt": "2026-09-25T09:30:00.000Z",
      "cancelledAt": "2026-09-25T09:30:00.000Z",
      "invoicedAt": "2026-09-25T09:30:00.000Z"
    },
    "unit": {
      "type": "MEDICAL",
      "label": "Unidad médica"
    },
    "outcome": "ATTENDED",
    "cancellationReason": "string",
    "cancelledWithCharge": true,
    "cancellable": true,
    "reportAvailable": true,
    "invoiceId": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "createdAt": "2026-09-25T09:30:00.000Z",
    "updatedAt": "2026-09-25T09:30:00.000Z"
  },
  "message": "Operación realizada correctamente"
}

GET`/visits/{id}/report`

Descarga el informe asistencial (PDF) si está compartido y consentido

Ámbito: reports:read. Cada descarga queda registrada (CLINICAL_ACCESS).

Parámetros

Nombre	En	Tipo	Descripción
`id`obligatorio	ruta	`string`	—

Respuestas

401API key ausente, inválida, revocada o caducadaProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
404Sin informe compartido para este aviso
application/pdf
429Límite de peticiones de la clave superado (Retry-After)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

POST`/sandbox/visits/{id}/advance`

[Solo sandbox] Avanza un aviso de prueba al siguiente estado o al indicado

Ámbito: visits:write. Dispara los mismos webhooks que en producción para cada estado por el que pasa. Para cancelar, {"to":"CANCELLED"} (desde pendiente, asignado o en camino).

Parámetros

Nombre	En	Tipo	Descripción
`id`obligatorio	ruta	`string`	—

Cuerpo de la petición `SandboxAdvanceVisitDto`

tostringopcional
Estado destino. Sin él, el siguiente. Pasa por los intermedios, con su webhook cada uno
Valores
ASSIGNEDEN_ROUTEON_SITEFINISHEDCANCELLED

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataProviderVisitDetailResponseDtoopcional
  Ver campos
  - idstring (uuid)obligatorio
  - codestringobligatorio
    Ejemplo
    AV-000123
  - statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
  - statusLabelstringobligatorio
    Ejemplo
    Unidad en camino
  - prioritystringobligatorio
    Valores
    URGENTNORMALSCHEDULED
  - originstringobligatorio
    Valores
    INTRANETPROVIDER_PORTALPROVIDER_API
  - externalRefstringopcionalpuede ser null
    Ejemplo
    EXP-2026-004512
  - serviceTypeProviderVisitServiceTypeDtoobligatorio
    Ver campos
    idstring (uuid)obligatorio
    codestringobligatorio
    Ejemplo
    GENERAL_CONSULTATION
    namestringobligatorio
    Ejemplo
    Consulta general
  - requiredProfessionalstringobligatorio
    Valores
    DOCTORNURSE
  - insurerobjectopcionalpuede ser null
    Aseguradora final
  - patientNamestringobligatorio
    Nombre del paciente que envió
    Ejemplo
    María García López
  - addressobjectobligatorio
    Domicilio (sin coordenadas ni indicaciones de acceso)
  - serviceDatestringobligatorio
    Ejemplo
    2026-09-25
  - scheduledFromstring (date-time)opcionalpuede ser null
  - scheduledTostring (date-time)opcionalpuede ser null
    Fin de la cita, calculado: inicio + tiempo estimado
  - estimatedMinutesnumberobligatorio
    Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
    Ejemplo
    60
  - milestonesProviderVisitMilestonesDtoobligatorio
    Ver campos
    requestedAtstring (date-time)obligatorio
    assignedAtstring (date-time)opcionalpuede ser null
    departedAtstring (date-time)opcionalpuede ser null
    arrivedAtstring (date-time)opcionalpuede ser null
    finishedAtstring (date-time)opcionalpuede ser null
    cancelledAtstring (date-time)opcionalpuede ser null
    invoicedAtstring (date-time)opcionalpuede ser null
  - unitProviderVisitUnitDtoopcionalpuede ser null
    Solo el tipo de unidad, desde la asignación
    Ver campos
    typestringobligatorio
    Valores
    MEDICALNURSING
    labelstringobligatorio
    Nunca nombres ni matrículas
    Ejemplo
    Unidad médica
  - outcomestringopcionalpuede ser null
    Valores
    ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
  - cancellationReasonstringopcionalpuede ser null
  - cancelledWithChargebooleanobligatorio
  - cancellablebooleanobligatorio
    Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
  - reportAvailablebooleanobligatorio
    Si hay informe asistencial compartido y descargable
  - invoiceIdstring (uuid)opcionalpuede ser null
  - createdAtstring (date-time)obligatorio
  - updatedAtstring (date-time)obligatorio
  - timelinearray<ProviderVisitTimelineEntryDto>obligatorio
    Ver campos
    statusstringobligatorio
    Valores
    PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
    labelstringobligatorio
    Ejemplo
    Unidad asignada
    atstring (date-time)obligatorio
- messagestringopcional
  Ejemplo
  Operación realizada correctamente
400El aviso no puede pasar a ese estadoProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z
404Aviso no encontrado, o la ruta no existe (producción)ProblemDetailDto
- typestringobligatorio
  Ejemplo
  https://api.dominio.com/errors/validation-error
- titlestringobligatorio
  Ejemplo
  Error de validación
- statusnumberobligatorio
  Ejemplo
  400
- detailstringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
- instancestringobligatorio
  Ejemplo
  /users/123
- errorsarray<FieldErrorDto>opcional
  Ver campos
  - fieldstringobligatorio
    Ejemplo
    email
  - messagestringobligatorio
    Ejemplo
    El campo 'email' no tiene un formato válido
- timestampstringobligatorio
  Ejemplo
  2026-07-07T10:00:00.000Z

curl -X POST "https://sandbox-api.saludenruta.es/api/integrations/v1/sandbox/visits/string/advance" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "ASSIGNED"
}'

{
  "status": 200,
  "data": {
    "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "code": "AV-000123",
    "status": "PENDING",
    "statusLabel": "Unidad en camino",
    "priority": "URGENT",
    "origin": "INTRANET",
    "externalRef": "EXP-2026-004512",
    "serviceType": {
      "id": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
      "code": "GENERAL_CONSULTATION",
      "name": "Consulta general"
    },
    "requiredProfessional": "DOCTOR",
    "insurer": {},
    "patientName": "María García López",
    "address": {},
    "serviceDate": "2026-09-25",
    "scheduledFrom": "2026-09-25T09:30:00.000Z",
    "scheduledTo": "2026-09-25T09:30:00.000Z",
    "estimatedMinutes": 60,
    "milestones": {
      "requestedAt": "2026-09-25T09:30:00.000Z",
      "assignedAt": "2026-09-25T09:30:00.000Z",
      "departedAt": "2026-09-25T09:30:00.000Z",
      "arrivedAt": "2026-09-25T09:30:00.000Z",
      "finishedAt": "2026-09-25T09:30:00.000Z",
      "cancelledAt": "2026-09-25T09:30:00.000Z",
      "invoicedAt": "2026-09-25T09:30:00.000Z"
    },
    "unit": {
      "type": "MEDICAL",
      "label": "Unidad médica"
    },
    "outcome": "ATTENDED",
    "cancellationReason": "string",
    "cancelledWithCharge": true,
    "cancellable": true,
    "reportAvailable": true,
    "invoiceId": "3f1c2b8e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "createdAt": "2026-09-25T09:30:00.000Z",
    "updatedAt": "2026-09-25T09:30:00.000Z",
    "timeline": [
      {
        "status": "PENDING",
        "label": "Unidad asignada",
        "at": "2026-09-25T09:30:00.000Z"
      }
    ]
  },
  "message": "Operación realizada correctamente"
}

POST`/sandbox/reset`

[Solo sandbox] Borra todos tus avisos de prueba

Ámbito: visits:write. Deja el entorno limpio para empezar otra batería de pruebas.

Respuestas

200Correctaobject
- statusnumberopcional
  Ejemplo
  200
- dataSandboxResetResponseDtoopcional
  Ver campos
  - deletedVisitsnumberopcional
    Ejemplo
    12
- messagestringopcional
  Ejemplo
  Operación realizada correctamente

curl -X POST "https://sandbox-api.saludenruta.es/api/integrations/v1/sandbox/reset" \
  -H "X-Api-Key: $SERAD_API_KEY"

{
  "status": 200,
  "data": {
    "deletedVisits": 12
  },
  "message": "Operación realizada correctamente"
}

Webhooks

Peticiones que Salud en Ruta envía a la URL que configures. Ver la guía de webhooks para la firma y los reintentos.

EVENTO`visit.created`

Evento visit.created

Petición que Salud en Ruta envía a tu URL. Verifica la firma: X-Serad-Signature = sha256= + hex(HMAC-SHA256(secreto, <X-Serad-Timestamp>.<cuerpo crudo>)), con una tolerancia de 300 s. Responde 2xx en menos de 10 s; si no, se reintenta: 12 intentos en total con espera exponencial (de 30 s a 1 h, unas 5 horas). X-Serad-Delivery identifica la entrega para descartar duplicados.

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.created",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.assigned`

Evento visit.assigned

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "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-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.en_route`

Evento visit.en_route

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.en_route",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.on_site`

Evento visit.on_site

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.on_site",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.finished`

Evento visit.finished

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.finished",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.cancelled`

Evento visit.cancelled

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.cancelled",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`visit.invoiced`

Evento visit.invoiced

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "visit.invoiced",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

EVENTO`report.shared`

Evento report.shared

Parámetros

Nombre	En	Tipo	Descripción
`X-Serad-Signature`obligatorio	cabecera	`string`	—
`X-Serad-Timestamp`obligatorio	cabecera	`string`	—
`X-Serad-Event`obligatorio	cabecera	`string`	—
`X-Serad-Delivery`obligatorio	cabecera	`string (uuid)`	—

Carga del evento `object`

Sin campos descritos.

Respuesta que esperamos

2XXRecibido. Cualquier otra respuesta se reintenta.
Sin cuerpo

{
  "id": "6f0a9c1e-2b7d-4f8a-9e3c-1d2b3c4d5e6f",
  "type": "report.shared",
  "createdAt": "2026-10-01T09:15:00.000Z",
  "data": {
    "visit": {
      "id": "c6a3c348-40b6-4158-a44a-7d85f01a0201",
      "code": "AV-000018",
      "externalRef": "EXP-2026-004512",
      "status": "ASSIGNED",
      "priority": "URGENT",
      "origin": "PROVIDER_API",
      "serviceTypeCode": "URG",
      "unitType": "MEDICAL",
      "milestones": {
        "requestedAt": "2026-10-01T09:10:00.000Z",
        "assignedAt": "2026-10-01T09:15:00.000Z"
      },
      "outcome": null,
      "cancelledWithCharge": false,
      "invoice": null
    }
  }
}

Esquemas

FieldErrorDto

fieldstringobligatorio
Ejemplo
email
messagestringobligatorio
Ejemplo
El campo 'email' no tiene un formato válido

ProblemDetailDto

typestringobligatorio
Ejemplo
https://api.dominio.com/errors/validation-error
titlestringobligatorio
Ejemplo
Error de validación
statusnumberobligatorio
Ejemplo
400
detailstringobligatorio
Ejemplo
El campo 'email' no tiene un formato válido
instancestringobligatorio
Ejemplo
/users/123
errorsarray<FieldErrorDto>opcional
Ver campos
- fieldstringobligatorio
  Ejemplo
  email
- messagestringobligatorio
  Ejemplo
  El campo 'email' no tiene un formato válido
timestampstringobligatorio
Ejemplo
2026-07-07T10:00:00.000Z

ProviderVisitServiceTypeDto

idstring (uuid)obligatorio
codestringobligatorio
Ejemplo
GENERAL_CONSULTATION
namestringobligatorio
Ejemplo
Consulta general

ProviderVisitMilestonesDto

requestedAtstring (date-time)obligatorio
assignedAtstring (date-time)opcionalpuede ser null
departedAtstring (date-time)opcionalpuede ser null
arrivedAtstring (date-time)opcionalpuede ser null
finishedAtstring (date-time)opcionalpuede ser null
cancelledAtstring (date-time)opcionalpuede ser null
invoicedAtstring (date-time)opcionalpuede ser null

ProviderVisitUnitDto

typestringobligatorio
Valores
MEDICALNURSING
labelstringobligatorio
Nunca nombres ni matrículas
Ejemplo
Unidad médica

ProviderVisitResponseDto

idstring (uuid)obligatorio
codestringobligatorio
Ejemplo
AV-000123
statusstringobligatorio
Valores
PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
statusLabelstringobligatorio
Ejemplo
Unidad en camino
prioritystringobligatorio
Valores
URGENTNORMALSCHEDULED
originstringobligatorio
Valores
INTRANETPROVIDER_PORTALPROVIDER_API
externalRefstringopcionalpuede ser null
Ejemplo
EXP-2026-004512
serviceTypeProviderVisitServiceTypeDtoobligatorio
Ver campos
- idstring (uuid)obligatorio
- codestringobligatorio
  Ejemplo
  GENERAL_CONSULTATION
- namestringobligatorio
  Ejemplo
  Consulta general
requiredProfessionalstringobligatorio
Valores
DOCTORNURSE
insurerobjectopcionalpuede ser null
Aseguradora final
patientNamestringobligatorio
Nombre del paciente que envió
Ejemplo
María García López
addressobjectobligatorio
Domicilio (sin coordenadas ni indicaciones de acceso)
serviceDatestringobligatorio
Ejemplo
2026-09-25
scheduledFromstring (date-time)opcionalpuede ser null
scheduledTostring (date-time)opcionalpuede ser null
Fin de la cita, calculado: inicio + tiempo estimado
estimatedMinutesnumberobligatorio
Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
Ejemplo
60
milestonesProviderVisitMilestonesDtoobligatorio
Ver campos
- requestedAtstring (date-time)obligatorio
- assignedAtstring (date-time)opcionalpuede ser null
- departedAtstring (date-time)opcionalpuede ser null
- arrivedAtstring (date-time)opcionalpuede ser null
- finishedAtstring (date-time)opcionalpuede ser null
- cancelledAtstring (date-time)opcionalpuede ser null
- invoicedAtstring (date-time)opcionalpuede ser null
unitProviderVisitUnitDtoopcionalpuede ser null
Solo el tipo de unidad, desde la asignación
Ver campos
- typestringobligatorio
  Valores
  MEDICALNURSING
- labelstringobligatorio
  Nunca nombres ni matrículas
  Ejemplo
  Unidad médica
outcomestringopcionalpuede ser null
Valores
ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
cancellationReasonstringopcionalpuede ser null
cancelledWithChargebooleanobligatorio
cancellablebooleanobligatorio
Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
reportAvailablebooleanobligatorio
Si hay informe asistencial compartido y descargable
invoiceIdstring (uuid)opcionalpuede ser null
createdAtstring (date-time)obligatorio
updatedAtstring (date-time)obligatorio

ProviderCatalogServiceTypeDto

idstring (uuid)obligatorio
codestringobligatorio
Ejemplo
GENERAL_CONSULTATION
namestringobligatorio
Ejemplo
Consulta general
requiredProfessionalstringobligatorio
Valores
DOCTORNURSE

ProviderCatalogInsurerDto

idstring (uuid)obligatorio
namestringobligatorio
Ejemplo
Sanitas

ProviderCatalogResponseDto

providerTypestringobligatorio
Valores
INSURERINTERMEDIARYPRIVATEOTHER
requiresExternalRefbooleanobligatorio
Si externalRef es obligatorio
serviceTypesarray<ProviderCatalogServiceTypeDto>obligatorio
Tipos de servicio con línea en su tarifa vigente (o todos los activos sin tarifa)
Ver campos
- idstring (uuid)obligatorio
- codestringobligatorio
  Ejemplo
  GENERAL_CONSULTATION
- namestringobligatorio
  Ejemplo
  Consulta general
- requiredProfessionalstringobligatorio
  Valores
  DOCTORNURSE
insurersarray<ProviderCatalogInsurerDto>obligatorio
Aseguradoras finales admitidas (solo intermediarios)
Ver campos
- idstring (uuid)obligatorio
- namestringobligatorio
  Ejemplo
  Sanitas

ProviderVisitPatientInputDto

firstNamestringobligatorio
Ejemplo
María
lastNamestringobligatorio
Ejemplo
García López
documentTypestringopcional
Valores
DNINIEPASSPORTNONE
Por defecto
NONE
documentNumberstringopcional
Obligatorio salvo documentType NONE
Ejemplo
12345678Z
birthDatestringopcional
Ejemplo
1948-05-17
sexstringopcional
Valores
MALEFEMALEOTHERUNKNOWN
phonestringopcional
Ejemplo
+34600111222

VisitAddressInputDto

line1stringobligatorio
Ejemplo
Calle de Alcalá 120
line2stringopcional
Ejemplo
3º B
citystringobligatorio
Ejemplo
Madrid
postalCodestringobligatorio
Ejemplo
28009
provincestringopcional
Ejemplo
Madrid
accessNotesstringopcional
Ejemplo
Portal 2, código 1234#
latitudenumberopcional
Si falta, se geocodifica
Ejemplo
40.4212
longitudenumberopcional
Ejemplo
-3.6765

ProviderCreateVisitDto

patientIdstring (uuid)opcional
Paciente de un aviso anterior de este proveedor (GET /client/patients). Si llega, patient no hace falta
patientProviderVisitPatientInputDtoopcional
Datos del paciente. Obligatorio salvo que se indique patientId
Ver campos
- firstNamestringobligatorio
  Ejemplo
  María
- lastNamestringobligatorio
  Ejemplo
  García López
- documentTypestringopcional
  Valores
  DNINIEPASSPORTNONE
  Por defecto
  NONE
- documentNumberstringopcional
  Obligatorio salvo documentType NONE
  Ejemplo
  12345678Z
- birthDatestringopcional
  Ejemplo
  1948-05-17
- sexstringopcional
  Valores
  MALEFEMALEOTHERUNKNOWN
- phonestringopcional
  Ejemplo
  +34600111222
addressVisitAddressInputDtoobligatorio
Domicilio de la visita; se geocodifica si no trae coordenadas
Ver campos
- line1stringobligatorio
  Ejemplo
  Calle de Alcalá 120
- line2stringopcional
  Ejemplo
  3º B
- citystringobligatorio
  Ejemplo
  Madrid
- postalCodestringobligatorio
  Ejemplo
  28009
- provincestringopcional
  Ejemplo
  Madrid
- accessNotesstringopcional
  Ejemplo
  Portal 2, código 1234#
- latitudenumberopcional
  Si falta, se geocodifica
  Ejemplo
  40.4212
- longitudenumberopcional
  Ejemplo
  -3.6765
serviceTypeCodestringopcional
Código del tipo de servicio (GET /catalog). Recomendado: es el mismo en pruebas y en producción, a diferencia del serviceTypeId. Obligatorio si no se indica serviceTypeId
Ejemplo
URG
serviceTypeIdstring (uuid)opcional
Id del tipo de servicio (GET /catalog). Cambia entre entornos: mejor serviceTypeCode. Obligatorio si no se indica serviceTypeCode
prioritystringopcional
Por defecto NORMAL, o SCHEDULED si trae franja
Valores
URGENTNORMALSCHEDULED
scheduledFromstring (date-time)opcional
Ejemplo
2026-09-26T09:00:00+02:00
estimatedMinutesnumberopcional
Tiempo estimado en minutos: bloques de 10 entre 30 y 240. Por defecto 60
Rango
30 – 240
Múltiplo de
10
Ejemplo
60
scheduledTostring (date-time)opcionalobsoleto
Obsoleto: usar estimatedMinutes. Si llega sin él, la duración de la franja se redondea al bloque de 10 min y se usa como tiempo estimado
Ejemplo
2026-09-26T11:00:00+02:00
reasonstringobligatorio
Motivo de la solicitud
Ejemplo
Fiebre alta desde ayer, 39 ºC
externalRefstringopcional
Obligatorio si el proveedor lo exige
Ejemplo
EXP-2026-004512
insurerIdstring (uuid)opcional
Aseguradora final: solo intermediarios, y entre sus aseguradoras gestionadas
callerNamestringopcional
Ejemplo
Ana García (hija)
callerPhonestringopcional
Ejemplo
+34600111333

ProviderVisitTimelineEntryDto

statusstringobligatorio
Valores
PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
labelstringobligatorio
Ejemplo
Unidad asignada
atstring (date-time)obligatorio

ProviderVisitDetailResponseDto

idstring (uuid)obligatorio
codestringobligatorio
Ejemplo
AV-000123
statusstringobligatorio
Valores
PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
statusLabelstringobligatorio
Ejemplo
Unidad en camino
prioritystringobligatorio
Valores
URGENTNORMALSCHEDULED
originstringobligatorio
Valores
INTRANETPROVIDER_PORTALPROVIDER_API
externalRefstringopcionalpuede ser null
Ejemplo
EXP-2026-004512
serviceTypeProviderVisitServiceTypeDtoobligatorio
Ver campos
- idstring (uuid)obligatorio
- codestringobligatorio
  Ejemplo
  GENERAL_CONSULTATION
- namestringobligatorio
  Ejemplo
  Consulta general
requiredProfessionalstringobligatorio
Valores
DOCTORNURSE
insurerobjectopcionalpuede ser null
Aseguradora final
patientNamestringobligatorio
Nombre del paciente que envió
Ejemplo
María García López
addressobjectobligatorio
Domicilio (sin coordenadas ni indicaciones de acceso)
serviceDatestringobligatorio
Ejemplo
2026-09-25
scheduledFromstring (date-time)opcionalpuede ser null
scheduledTostring (date-time)opcionalpuede ser null
Fin de la cita, calculado: inicio + tiempo estimado
estimatedMinutesnumberobligatorio
Tiempo estimado de realización, en minutos (puede ampliarse con el aviso en curso)
Ejemplo
60
milestonesProviderVisitMilestonesDtoobligatorio
Ver campos
- requestedAtstring (date-time)obligatorio
- assignedAtstring (date-time)opcionalpuede ser null
- departedAtstring (date-time)opcionalpuede ser null
- arrivedAtstring (date-time)opcionalpuede ser null
- finishedAtstring (date-time)opcionalpuede ser null
- cancelledAtstring (date-time)opcionalpuede ser null
- invoicedAtstring (date-time)opcionalpuede ser null
unitProviderVisitUnitDtoopcionalpuede ser null
Solo el tipo de unidad, desde la asignación
Ver campos
- typestringobligatorio
  Valores
  MEDICALNURSING
- labelstringobligatorio
  Nunca nombres ni matrículas
  Ejemplo
  Unidad médica
outcomestringopcionalpuede ser null
Valores
ATTENDEDPATIENT_ABSENTREFERRED_HOSPITALREFUSEDCANCELLED
cancellationReasonstringopcionalpuede ser null
cancelledWithChargebooleanobligatorio
cancellablebooleanobligatorio
Si el proveedor puede cancelarlo ahora (PENDING/ASSIGNED)
reportAvailablebooleanobligatorio
Si hay informe asistencial compartido y descargable
invoiceIdstring (uuid)opcionalpuede ser null
createdAtstring (date-time)obligatorio
updatedAtstring (date-time)obligatorio
timelinearray<ProviderVisitTimelineEntryDto>obligatorio
Ver campos
- statusstringobligatorio
  Valores
  PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
- labelstringobligatorio
  Ejemplo
  Unidad asignada
- atstring (date-time)obligatorio

ProviderVisitEtaResponseDto

statusstringobligatorio
Valores
PENDINGASSIGNEDEN_ROUTEON_SITEFINISHEDVALIDATEDINVOICEDCANCELLED
etaMinutesnumberopcionalpuede ser null
Minutos estimados hasta la llegada; null si no está EN_ROUTE o no hay posición
Ejemplo
14
estimatedArrivalAtstring (date-time)opcionalpuede ser null
Hora estimada de llegada
estimatedbooleanobligatorio
true si es una estimación en línea recta (sin OSRM)
calculatedAtstring (date-time)obligatorio

ProviderCancelVisitDto

reasonstringobligatorio
Ejemplo
El paciente ya no necesita la visita

SandboxAdvanceVisitDto

tostringopcional
Estado destino. Sin él, el siguiente. Pasa por los intermedios, con su webhook cada uno
Valores
ASSIGNEDEN_ROUTEON_SITEFINISHEDCANCELLED

SandboxResetResponseDto

deletedVisitsnumberopcional
Ejemplo
12

ProviderApiKeyResponseDto

idstring (uuid)obligatorio
providerIdstring (uuid)obligatorio
namestringobligatorio
Ejemplo
Integración CRM expedientes
keyPrefixstringobligatorio
Prefijo visible: la clave empieza por srd_live_<prefijo>, srd_test<prefijo>_ o (legacy) srd_<prefijo>_
Ejemplo
a1b2c3d4
keyFormatstringobligatorio
Formato con el que se emitió: live (srd_live_), test (srd_test_) o legacy (srd_<prefijo>_)
Valores
livetestlegacy
Ejemplo
live
scopesarray<string>obligatorio
Valores
visits:writevisits:readreports:read
rateLimitPerMinutenumberobligatorio
Ejemplo
60
expiresAtstring (date-time)opcionalpuede ser null
lastUsedAtstring (date-time)opcionalpuede ser null
lastUsedIpstringopcionalpuede ser null
revokedAtstring (date-time)opcionalpuede ser null
rotatedFromIdstring (uuid)opcionalpuede ser null
createdAtstring (date-time)obligatorio

ProviderApiKeyCreatedDto

idstring (uuid)obligatorio
providerIdstring (uuid)obligatorio
namestringobligatorio
Ejemplo
Integración CRM expedientes
keyPrefixstringobligatorio
Prefijo visible: la clave empieza por srd_live_<prefijo>, srd_test<prefijo>_ o (legacy) srd_<prefijo>_
Ejemplo
a1b2c3d4
keyFormatstringobligatorio
Formato con el que se emitió: live (srd_live_), test (srd_test_) o legacy (srd_<prefijo>_)
Valores
livetestlegacy
Ejemplo
live
scopesarray<string>obligatorio
Valores
visits:writevisits:readreports:read
rateLimitPerMinutenumberobligatorio
Ejemplo
60
expiresAtstring (date-time)opcionalpuede ser null
lastUsedAtstring (date-time)opcionalpuede ser null
lastUsedIpstringopcionalpuede ser null
revokedAtstring (date-time)opcionalpuede ser null
rotatedFromIdstring (uuid)opcionalpuede ser null
createdAtstring (date-time)obligatorio
keystringobligatorio
Clave completa. Solo se muestra en esta respuesta; guárdala en un gestor de secretos
Ejemplo
srd_a1b2c3d4_Qm9yZ2VzIGVzIHVuIGdlbmlvIGRlIGxhIGxpdGVyYXR1cmE

CreateProviderApiKeyDto

namestringobligatorio
Ejemplo
Integración CRM expedientes
scopesarray<string>obligatorio
Valores
visits:writevisits:readreports:read
rateLimitPerMinutenumberopcional
Peticiones por minuto (por defecto 60)
Ejemplo
60
expiresAtstringopcional
Sin valor, no caduca
Ejemplo
2027-12-31T23:59:59Z

ProviderWebhookResponseDto

idstring (uuid)obligatorio
providerIdstring (uuid)obligatorio
urlstringobligatorio
eventsarray<string>obligatorio
Valores
visit.createdvisit.assignedvisit.en_routevisit.on_sitevisit.finishedvisit.cancelledvisit.invoicedreport.shared
activebooleanobligatorio
descriptionstringopcionalpuede ser null
secretHintstringobligatorio
Solo los últimos caracteres
Ejemplo
whsec_…3f9a
createdAtstring (date-time)obligatorio
updatedAtstring (date-time)obligatorio

ProviderWebhookWithSecretDto

idstring (uuid)obligatorio
providerIdstring (uuid)obligatorio
urlstringobligatorio
eventsarray<string>obligatorio
Valores
visit.createdvisit.assignedvisit.en_routevisit.on_sitevisit.finishedvisit.cancelledvisit.invoicedreport.shared
activebooleanobligatorio
descriptionstringopcionalpuede ser null
secretHintstringobligatorio
Solo los últimos caracteres
Ejemplo
whsec_…3f9a
createdAtstring (date-time)obligatorio
updatedAtstring (date-time)obligatorio
secretstringobligatorio
Secreto completo para verificar X-Serad-Signature. Solo en esta respuesta
Ejemplo
whsec_2Qx…

CreateProviderWebhookDto

urlstringobligatorio
Ejemplo
https://integraciones.aseguradora.es/serad/webhooks
eventsarray<string>obligatorio
Valores
visit.createdvisit.assignedvisit.en_routevisit.on_sitevisit.finishedvisit.cancelledvisit.invoicedreport.shared
descriptionstringopcional
Ejemplo
CRM de expedientes (producción)
secretstringopcional
Secreto de firma. Si no se indica, se genera (whsec_…) y se devuelve una vez

UpdateProviderWebhookDto

urlstringopcional
Ejemplo
https://integraciones.aseguradora.es/serad/webhooks
eventsarray<string>opcional
Valores
visit.createdvisit.assignedvisit.en_routevisit.on_sitevisit.finishedvisit.cancelledvisit.invoicedreport.shared
descriptionstringopcional
Ejemplo
CRM de expedientes (producción)
secretstringopcional
Secreto de firma. Si no se indica, se genera (whsec_…) y se devuelve una vez
activebooleanopcional
Desactivado no recibe eventos

ProviderWebhookDeliveryDto

idstring (uuid)obligatorio
endpointIdstring (uuid)obligatorio
eventstringobligatorio
Ejemplo
visit.assigned
eventIdstring (uuid)obligatorio
visitIdstring (uuid)opcionalpuede ser null
statusstringobligatorio
Valores
PENDINGRETRYINGSUCCEEDEDFAILED
attemptsnumberobligatorio
Ejemplo
2
maxAttemptsnumberobligatorio
Ejemplo
6
lastStatusCodenumberopcionalpuede ser null
Ejemplo
500
lastResponsestringopcionalpuede ser null
Truncada a 1000 caracteres
lastErrorstringopcionalpuede ser null
lastAttemptAtstring (date-time)opcionalpuede ser null
nextAttemptAtstring (date-time)opcionalpuede ser null
deliveredAtstring (date-time)opcionalpuede ser null
isTestbooleanobligatorio
redeliveryOfIdstring (uuid)opcionalpuede ser null
payloadobjectobligatorio
Carga enviada (sin datos clínicos)
createdAtstring (date-time)obligatorio

¿Falta algo o algo no cuadra con lo que ves? Escribe al equipo técnico: info@saludenruta.es.

Provider Integration API (v1)

GET/catalog

Respuestas

GET/visits

Parámetros

Respuestas

POST/visits

Parámetros

Cuerpo de la petición ProviderCreateVisitDto

Respuestas

GET/visits/{id}

Parámetros

Respuestas

GET/visits/{id}/eta

Parámetros

Respuestas

POST/visits/{id}/cancel

Parámetros

Cuerpo de la petición ProviderCancelVisitDto

Respuestas

GET/visits/{id}/report

Parámetros

Respuestas

POST/sandbox/visits/{id}/advance

Parámetros

Cuerpo de la petición SandboxAdvanceVisitDto

Respuestas

POST/sandbox/reset

Respuestas

Webhooks

EVENTOvisit.created

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.assigned

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.en_route

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.on_site

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.finished

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.cancelled

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOvisit.invoiced

Parámetros

Carga del evento object

Respuesta que esperamos

EVENTOreport.shared

Parámetros

Carga del evento object

Respuesta que esperamos

Esquemas

GET`/catalog`

GET`/visits`

POST`/visits`

Cuerpo de la petición `ProviderCreateVisitDto`

GET`/visits/{id}`

GET`/visits/{id}/eta`

POST`/visits/{id}/cancel`

Cuerpo de la petición `ProviderCancelVisitDto`

GET`/visits/{id}/report`

POST`/sandbox/visits/{id}/advance`

Cuerpo de la petición `SandboxAdvanceVisitDto`

POST`/sandbox/reset`

EVENTO`visit.created`

Carga del evento `object`

EVENTO`visit.assigned`

Carga del evento `object`

EVENTO`visit.en_route`

Carga del evento `object`

EVENTO`visit.on_site`

Carga del evento `object`

EVENTO`visit.finished`

Carga del evento `object`

EVENTO`visit.cancelled`

Carga del evento `object`

EVENTO`visit.invoiced`

Carga del evento `object`

EVENTO`report.shared`

Carga del evento `object`