Conecta tus sistemas con la API de Luna Salud: activa tu token y haz tu primera consulta
La API de Luna Salud te permite consultar la información de tu cuenta de forma programática: citas, pacientes, notas clínicas, pagos, biomarcadores y resultados de laboratorio. Es una API REST de solo lectura — puedes leer datos para reportes e integraciones, pero no crear, modificar ni eliminar registros — así que puedes experimentar sin miedo a romper nada. Esta guía te lleva desde habilitar el acceso hasta tu primera solicitud exitosa.
¿Para qué sirve la API?
La API te da acceso directo a los datos de tu organización para usarlos fuera de Luna Salud. Algunos ejemplos:
Reportes personalizados
Conecta los datos de tu clínica con Google Sheets, Excel o Power BI y arma reportes a tu medida.
Conciliación de pagos
Consulta los pagos registrados con el endpoint /payments y concílialos con tu contabilidad o tu ERP.
Dashboards en tiempo real
Construye tableros con las métricas de citas, pacientes e ingresos de tu organización.
Seguimiento de laboratorio
Lee resultados de laboratorio y biomarcadores para alimentar sistemas de monitoreo clínico, con webhooks que te avisan cuando hay datos nuevos.
Antes de empezar: habilita el acceso a la API
El acceso a la API se habilita por organización y no viene activado de fábrica. Para poder generar tu token necesitas tres cosas:
- Acceso a la API habilitado para tu organización. Lo activa el equipo de Luna Salud; pídelo por WhatsApp y te lo habilitamos.
- Rol de Administrador. Solo los administradores pueden ver y generar el token de acceso.
- Tu token generado. El token no existe hasta que lo generas tú mismo — te enseñamos cómo en la siguiente sección.
¿No ves la pestaña «Herramientas de Desarrollo»?
Esa pestaña solo aparece cuando eres administrador y la API está habilitada para tu organización. Si eres administrador y no la ves en Cuenta → Organización, la API aún no está activada para tu clínica: escríbenos por WhatsApp y la habilitamos.
Si alguien de tu equipo intenta usar la API sin que esté habilitada, recibirá un error 403 con el mensaje «El acceso a la API no está habilitado para esta organización».
Activa tu token de acceso, paso a paso
Inicia sesión como administrador
Entra a account.lunahealth.app con una cuenta que tenga rol de Administrador.
Abre Herramientas de Desarrollo
Ve a Cuenta → Organización y entra a la pestaña Herramientas de Desarrollo. Ahí vive todo lo relacionado con la API: tu token, la documentación y la configuración de webhooks.
Genera tu token
En la sección Token de Acceso de Luna Health, pulsa «Obtener Token de Acceso». El token no existe hasta que lo generas: este clic es el que lo activa.
Muéstralo y cópialo
Pulsa «Mostrar Token» y luego «Copiar al Portapapeles». Guárdalo en un lugar seguro (un gestor de secretos o las variables de entorno de tu servidor).
Utiliza esta clave para autorizar en el servicio API de Luna Health.
Tu token vence a los 90 días
Cada token es válido por 90 días. Cuando expira, tus solicitudes empiezan a devolver un error 401 con el mensaje «El token de API ha expirado». La solución es regenerarlo desde esta misma pantalla y actualizar tus integraciones con el token nuevo.
Regenerar invalida el token anterior al instante. Cualquier sistema que siga usando el token viejo dejará de funcionar en ese momento, así que planea el cambio.
Autentícate: tu primera solicitud
Todas las solicitudes van a la misma URL base:
https://account.lunahealth.app/apiY todas requieren tu token en el encabezado Authorization con el prefijo Bearer. Esta solicitud lista tus pacientes y es perfecta para verificar que todo funciona:
# Tu primera solicitud: listar pacientes
curl "https://account.lunahealth.app/api/patients?rowsPerPage=5&page=0" \
-H "Authorization: Bearer TU_TOKEN_DE_ACCESO"Si recibes un 200 OK con un JSON como este, ya estás dentro:
{
"items": [
{
"id": "pat456",
"first_name": "María",
"last_name": "García",
"email": "maria@ejemplo.com"
}
],
"meta": { "totalRowCount": 128, "page": 0, "rowsPerPage": 5 }
}Si en cambio recibes un 401 o un 403, salta a la sección de errores comunes más abajo: ahí está el significado exacto de cada mensaje y cómo resolverlo.
Endpoints disponibles
Todos los endpoints son de solo lectura (método GET) y devuelven JSON. Los datos siempre están limitados a tu organización: nunca verás información de otra clínica, y los endpoints de pacientes jamás exponen cuentas del personal.
| Endpoint | Qué devuelve | Filtros y parámetros |
|---|---|---|
| /appointments | Citas de tu organización. | from, to (fecha ISO), status (NEW, PENDING, CONFIRMED, COMPLETED, CANCELED), patientId, rowsPerPage (5–200), page, sortDir |
| /patients | Directorio de pacientes. | active, query (coincidencia exacta de nombre, apellido o correo), rowsPerPage (5–200), page, sortDir |
| /patient | Perfil básico de un paciente. | id (obligatorio) |
| /patient-charts | Notas clínicas y expediente estructurado: consultas, signos vitales, alergias, diagnósticos y procedimientos. | patientId (obligatorio) |
| /biomarkers | Biomarcadores de un paciente, con conteos por estado. | patientId (obligatorio), start_date, end_date, status (OPTIMAL, ACCEPTABLE, CRITICAL, IN_VERIFICATION), page, limit (1–100) |
| /lab-tests | Estudios de laboratorio de un paciente. | patientId (obligatorio), start_date, end_date, page, limit (1–100) |
| /lab-test-biomarkers | Biomarcadores de un estudio específico, con valores, unidades y rangos de referencia. | labTestId (obligatorio) |
| /payments | Pagos (recibos) de tu organización. | from, to, status (PAID, PENDING, CANCELED, REFUNDED), paymentMethod (CARD, BANK, CASH, INSURANCE, OTHER), patientId, rowsPerPage (5–200), page, sortDir |
| /payment | Un pago específico. | id (obligatorio) |
| /webhooks/config | La configuración de webhooks de tu organización (nunca incluye la llave secreta). | — |
Referencia técnica completa
Cada endpoint tiene su esquema de respuesta detallado, todos los parámetros y ejemplos de código en Node.js y Python en docs.lunasalud.mx. Este artículo es la guía de arranque; la referencia es esa.
Ejemplos prácticos
Citas de un mes, con su respuesta
# Citas de agosto 2026, 50 por página
curl "https://account.lunahealth.app/api/appointments?from=2026-08-01T00:00:00Z&to=2026-08-31T23:59:59Z&rowsPerPage=50&page=0" \
-H "Authorization: Bearer TU_TOKEN_DE_ACCESO"{
"items": [
{
"id": "abc123",
"status": "CONFIRMED",
"title": "Consulta general",
"start_time": "2026-08-15T10:00:00.000Z",
"end_time": "2026-08-15T10:30:00.000Z",
"telemedicine": false,
"patient": { "id": "pat456", "first_name": "María", "last_name": "García" },
"staffs": [{ "id": "stf789", "first_name": "Ana", "last_name": "López" }],
"service": { "id": "srv001", "name": "Consulta general" },
"location": { "id": "loc001", "name": "Consultorio Roma Norte" }
}
],
"meta": { "totalRowCount": 42, "page": 0, "rowsPerPage": 50 }
}Pagos con tarjeta del mes
# Pagos pagados con tarjeta en agosto 2026
curl "https://account.lunahealth.app/api/payments?from=2026-08-01T00:00:00Z&to=2026-08-31T23:59:59Z&status=PAID&paymentMethod=CARD" \
-H "Authorization: Bearer TU_TOKEN_DE_ACCESO"Biomarcadores críticos de un paciente
# Solo los biomarcadores en estado crítico
curl "https://account.lunahealth.app/api/biomarkers?patientId=pat456&status=CRITICAL" \
-H "Authorization: Bearer TU_TOKEN_DE_ACCESO"Límites y paginación
- 100 solicitudes por minuto por usuario. Si te pasas, recibirás un 429; espera unos segundos y reintenta. Para cargas grandes, espacia tus solicitudes.
- Paginación en todos los listados. Usa
page(empieza en 0) conrowsPerPage(5–200 en citas, pacientes y pagos) olimit(1–100 en biomarcadores y estudios de laboratorio). El total viene enmeta. - La paginación profunda está limitada. Si
page × rowsPerPagesupera 10,000, recibirás un 400. No es un capricho: en lugar de recorrer miles de páginas, acota confrom/too los filtros de fecha y recorre ventanas más pequeñas.
El patrón recomendado para sincronizar datos
Recorre por ventanas de fecha (por ejemplo, semana por semana con from y to) en lugar de paginar todo el histórico de golpe. Es más rápido, no choca con el límite de paginación y te permite reanudar donde te quedaste.
Errores comunes y cómo resolverlos
Los errores llegan con su código HTTP y un mensaje claro. Estos son los que verás con más frecuencia:
| Código | Mensaje | Cómo resolverlo |
|---|---|---|
| 401 | «No autorizado. Por favor, proporcione un token de API válido.» | Falta el encabezado o está mal formado. Verifica que envías Authorization: Bearer TU_TOKEN — con el prefijo Bearer y un espacio. |
| 401 | «El token de API ha expirado.» | Pasaron los 90 días de vigencia. Regenera el token en Herramientas de Desarrollo y actualiza tus integraciones. |
| 401 | «El token de API ha sido revocado.» | Alguien regeneró el token después de que copiaste el tuyo. Usa siempre el token más reciente de la pantalla de Herramientas de Desarrollo. |
| 403 | «El acceso a la API no está habilitado para esta organización.» | Tu organización aún no tiene la API activada. Escríbenos por WhatsApp para habilitarla. |
| 404 | «Paciente no encontrado.» / «Recurso no encontrado.» | El ID no existe o pertenece a otra organización. Verifica que el ID venga de una consulta previa a tu propia cuenta. |
| 400 | «El desplazamiento de paginación es demasiado grande.» | Superaste el límite de 10,000 registros de profundidad. Acota con filtros de fecha en lugar de paginar tan profundo. |
| 429 | «Límite de solicitudes excedido.» | Superaste las 100 solicitudes por minuto. Espera unos segundos y reintenta, idealmente con reintentos exponenciales. |
Webhooks: entérate sin preguntar
Además de consultar la API, puedes configurar un webhook para que Luna Salud avise a tu servidor cuando haya datos nuevos, en lugar de estar consultando cada cierto tiempo. Hoy hay dos tipos de eventos:
Sucede algo en Luna Salud
Se sube un estudio de laboratorio o se actualizan biomarcadores de un paciente
Luna Salud te notifica
Enviamos un POST a la URL que configuraste, firmado con tu llave secreta
Tu sistema reacciona
Consulta el detalle con la API y actualiza tus tableros o alertas
La configuración vive en la misma pestaña de Herramientas de Desarrollo, en la sección Configuración de Webhooks:
Puedes consultar tu configuración actual (URL, eventos suscritos y estado) con GET /webhooks/config. Por seguridad, ese endpoint nunca devuelve la llave secreta; los cambios de configuración se hacen siempre desde la plataforma, no por la API.
Seguridad de tu token
Tu token da acceso de lectura a la información de toda tu organización, incluyendo datos clínicos de pacientes. Trátalo como una contraseña:
- Nunca lo pongas en código del navegador, apps móviles ni repositorios públicos como GitHub.
- Nunca lo compartas por WhatsApp, correo o chat, ni con proveedores que no lo necesiten.
- Nunca lo escribas directo en el código: úsalo desde variables de entorno o un gestor de secretos en tu servidor.
¿Se filtró tu token?
Regenéralo de inmediato en Cuenta → Organización → Herramientas de Desarrollo con «Regenerar Token de Acceso». El token filtrado queda invalidado al instante y solo el nuevo seguirá funcionando.
Preguntas frecuentes
¿Por qué no veo la pestaña Herramientas de Desarrollo en mi cuenta?
El acceso a la API se habilita por organización y la pestaña solo aparece para administradores con la API activada. Si eres administrador y no la ves en Cuenta → Organización, la API aún no está habilitada para tu clínica: escríbenos por WhatsApp y la activamos.
¿Mi token de API expira?
Sí. Cada token es válido por 90 días. Al expirar, tus solicitudes devuelven un error 401 con el mensaje «El token de API ha expirado»; genera uno nuevo con Regenerar Token de Acceso en Herramientas de Desarrollo y actualiza tus integraciones con el token nuevo.
¿Puedo crear o modificar citas y pacientes desde la API?
No por ahora. La API es de solo lectura: puedes consultar citas, pacientes, expedientes, pagos, biomarcadores y resultados de laboratorio, pero no crear, editar ni eliminar registros. Cualquier cambio de datos se hace desde la plataforma.
¿Cuántas solicitudes puedo hacer a la API?
Hasta 100 solicitudes por minuto por usuario. Si superas el límite recibirás un error 429; espera unos segundos y reintenta. Para volúmenes grandes, recorre los datos por ventanas de fecha con los filtros from y to en lugar de paginar todo el histórico de golpe.
¿Qué hago si mi token se filtró o alguien más lo conoce?
Regenéralo de inmediato en Cuenta → Organización → Herramientas de Desarrollo con Regenerar Token de Acceso. El token anterior queda invalidado al instante y solo el nuevo funcionará; actualiza tus integraciones para no quedarte sin acceso.
¿Listo para construir?
La referencia técnica completa tiene el esquema de cada endpoint con todos los parámetros y ejemplos de código en Node.js y Python.
