Introducción a la API de integración

Qué es

La API de integración para proveedores de Salud en Ruta permite que una aseguradora, un intermediario o una plataforma sanitaria (por ejemplo, un servicio de telemedicina) envíe avisos de médico o enfermería a domicilio desde su propio sistema y siga su evolución sin pasar por el teléfono ni por el portal.

Es una API REST sobre HTTPS que habla JSON, versionada en la ruta (/v1), con autenticación por clave, errores en formato estándar (RFC 9457) y webhooks firmados para enterarte de cada cambio de estado en el momento en que ocurre.

Para quién es

• Aseguradoras que envían y pagan sus propios avisos.
• Intermediarios (gestoras de asistencia, centrales de servicios) que trabajan para varias aseguradoras y tienen que indicar en cada aviso la aseguradora final del paciente.
• Plataformas sanitarias (telemedicina, por ejemplo, Teladoc) que, tras una videoconsulta, necesitan que un profesional vaya al domicilio.

Si solo vas a enviar unos pocos avisos al día, el portal de proveedores (acceso desde el pie de esta web) puede bastarte: hace lo mismo que la API, sin programar nada.

Qué puedes hacer

• Consultar tu catálogo: los tipos de servicio que tienes contratados, qué profesional requiere cada uno (médico o enfermería), si debes enviar nº de expediente y, si eres intermediario, las aseguradoras para las que trabajas. → Catálogo
• Crear avisos urgentes, normales o con cita, con los datos del paciente, el domicilio y el motivo. → Avisos
• Consultar un aviso (estado, hitos y línea de tiempo) o listar los tuyos con filtros y paginación. → Avisos
• Conocer la hora estimada de llegada cuando la unidad va de camino. → Avisos
• Cancelar un aviso mientras no haya salido la unidad, sin cargo. → Avisos
• Descargar el informe asistencial en PDF cuando el profesional lo ha firmado y el paciente ha consentido compartirlo. → Avisos
• Recibir webhooks en tu sistema con cada cambio de estado, incluida la facturación. → Webhooks
• Probarlo todo en un entorno aislado con datos ficticios y un simulador que hace avanzar los avisos. → Sandbox

Cómo funciona un aviso

Un aviso es una petición de visita a domicilio para un paciente. Cuando lo creas entra como PENDING; la centralita de Salud en Ruta lo asigna a una unidad (médica o de enfermería), la unidad sale hacia el domicilio, llega, atiende al paciente y cierra el aviso. Después, Salud en Ruta lo valida y lo incluye en tu factura.

1. CreadoPENDINGvisit.created
2. AsignadoASSIGNEDvisit.assigned
3. En caminoEN_ROUTEvisit.en_route
4. En domicilioON_SITEvisit.on_site
5. FinalizadoFINISHEDvisit.finished
6. ValidadoVALIDATEDsin webhook
7. FacturadoINVOICEDvisit.invoiced

Cancelado CANCELLED · visit.cancelled
Por la API se puede cancelar mientras está PENDING o ASSIGNED, sin cargo. Con la unidad en camino o en el domicilio, solo la centralita (por teléfono).

Además, cuando el informe asistencial queda disponible para ti se envía report.shared.

Qué no hace la API

• No atiende emergencias. Salud en Ruta atiende urgencias no vitales a domicilio. Ante una emergencia vital, el paciente debe llamar al 112. No envíes por la API avisos que requieran una ambulancia.
• No devuelve datos clínicos. Ni síntomas, ni diagnóstico, ni tratamiento: lo clínico solo sale en el informe asistencial, y solo si el paciente lo consiente. Tampoco datos de los profesionales ni la posición de la unidad. → Pacientes y privacidad
• No modifica avisos ya creados. Si te equivocas en un dato, cancela el aviso (mientras se pueda) y crea otro, o llama a la centralita.
• No cancela avisos con la unidad en camino. A partir de EN_ROUTE solo puede hacerlo la centralita, por teléfono (+34 611 673 280).
• No gestiona claves ni webhooks. Las claves de API y las URL de webhook las da de alta Salud en Ruta desde su intranet; pídelas al equipo técnico.
• No es para el navegador. La clave de API es secreta: las llamadas se hacen siempre desde tu servidor, nunca desde una web o una app móvil.

Siguiente paso

Empieza por la guía de primeros pasos: en cinco minutos tendrás un aviso de prueba creado y tu primer webhook recibido.