Luna Health API — Referencia de la API

Endpoints relacionados con biomarcadores

Endpoints relacionados con pacientes

Endpoint de solo lectura para recuperar la configuración de webhook de su organización. La clave secreta nunca se devuelve y los ajustes de webhook se modifican desde la configuración de su cuenta de Luna Health, no a través de la API pública. Actualmente Luna Health envía cinco eventos de pruebas de laboratorio — lab_test.processed, lab_test.failed, lab_test.rejected, lab_test.split y lab_test.split_error —, form.completed y cuatro eventos de citas — appointment.created, appointment.updated, appointment.cancelled y appointment.no_show — como solicitudes POST firmadas a la URL que configure.

Eventos que enviamos

• lab_test.processed — una prueba de laboratorio terminó de procesarse y se extrajeron sus biomarcadores. data siempre incluye lab_test_id, patient_id, status, biomarker_count y timestamp. También puede incluir imageset_id y submission_id: solo se envían para pruebas de laboratorio digitalizadas a partir de un conjunto de imágenes.
• lab_test.failed — una prueba de laboratorio no pudo procesarse. data siempre incluye error y timestamp. También puede incluir lab_test_id, patient_id, imageset_id y submission_id: lab_test_id y patient_id se omiten cuando la falla ocurre antes de identificar la prueba de laboratorio o su paciente, y los campos del conjunto de imágenes solo se envían para cargas digitalizadas.
• lab_test.rejected — un conjunto de imágenes enviado fue rechazado durante la digitalización. data siempre incluye imageset_id, rejection_comment y timestamp. También puede incluir rejection_reason_id, lab_test_id, patient_id y error: rejection_reason_id se omite cuando el servicio de digitalización no indica un código de motivo, y cuando el conjunto de imágenes rechazado no puede asociarse a una prueba de laboratorio, se omiten lab_test_id y patient_id y error explica el motivo.
• lab_test.split — un conjunto de imágenes enviado se dividió en pruebas de laboratorio separadas. data siempre incluye imageset_id, patient_id, sub_file_id y timestamp. También puede incluir lab_test_id: se omite mientras el archivo dividido aún no está vinculado a una prueba de laboratorio.
• lab_test.split_error — no se pudo completar la división de un conjunto de imágenes. data siempre incluye imageset_id, error y timestamp.
• form.completed — un paciente completó un formulario, como un formato de ingreso, admisión o consentimiento. Las respuestas no vienen en el evento: léalas con GET /patient-form?id= usando form_id. Solo se envía si send_form_updates está activado. data siempre incluye form_id, patient_id y completed_at.
• appointment.created — se agendó una cita, desde el panel, su página de reservas, el asistente virtual o POST /appointments. Una nueva serie recurrente envía un evento por cada cita de la serie. status es PENDING cuando la clínica aún debe aprobar la solicitud del paciente. Solo se envía si send_appointment_updates está activado, como todos los eventos appointment. data siempre incluye appointment_id, patient_id, staff_ids, service_id, location_id, status, start_time y end_time.
• appointment.updated — una cita cambió de horario, se asignó a otros profesionales de salud, o ambas cosas. changes indica start_time y/o staff. previous_start_time y previous_staff_ids contienen los valores anteriores al cambio, y son null cuando el canal que hizo el cambio no los reportó. data siempre incluye appointment_id, patient_id, staff_ids, service_id, location_id, status, start_time, end_time, changes, previous_start_time y previous_staff_ids.
• appointment.cancelled — se canceló una cita, por la clínica, por el paciente o mediante POST /appointments/{id}/cancel. data siempre incluye appointment_id, patient_id, staff_ids, service_id, location_id, status, start_time y end_time.
• appointment.no_show — una cita pendiente o confirmada se marcó como inasistencia, desde el panel o mediante POST /appointments/{id}/no-show. data siempre incluye appointment_id, patient_id, staff_ids, service_id, location_id, status, start_time y end_time.

También se entrega un evento test cuando usa el botón de prueba en la configuración de su cuenta, para confirmar que su endpoint funciona antes de habilitarlo.

Los indicadores devueltos por este endpoint controlan la entrega: enabled activa o desactiva el webhook para toda la organización, send_lab_test_updates controla los eventos lab_test anteriores, send_form_updates controla form.completed y send_appointment_updates controla los eventos appointment. Cada familia de eventos está desactivada hasta que la active en la configuración de su cuenta. send_biomarker_updates está reservado para una futura familia de eventos biomarker; hoy no se envía ningún evento de biomarcadores.

Ignore cualquier tipo de evento que no reconozca: podemos agregar nuevos tipos de evento, y siempre llegan desactivados para un webhook existente hasta que los active.

Cada formulario completado se anuncia una sola vez, aunque el paciente lo envíe dos veces. Aun así, trate la entrega como al menos una vez y use los identificadores de data (como form_id, lab_test_id o appointment_id) para ignorar cualquier evento que ya haya procesado. Los eventos de citas reportan cambios hechos por cualquier canal, incluidas sus propias llamadas a la API, así que compare appointment_id con los cambios que su integración acaba de hacer para no procesarlos dos veces.

Estructura de la carga útil

Cada entrega es una solicitud HTTP POST con Content-Type: application/json y el mismo sobre. Solo data varía según el evento:

{
  "event": "lab_test.processed",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "organization_id": "6543210fedcba9876543210f",
  "data": {
    "lab_test_id": "6543210fedcba9876543210a",
    "patient_id": "6543210fedcba9876543210b",
    "status": "COMPLETED",
    "biomarker_count": 42,
    "timestamp": "2025-01-01T00:00:00.000Z"
  }
}

Una entrega de form.completed solo incluye el formulario, el paciente y cuándo se completó el formulario:

{
  "event": "form.completed",
  "timestamp": "2025-01-01T00:00:05.000Z",
  "organization_id": "6543210fedcba9876543210f",
  "data": {
    "form_id": "6543210fedcba9876543210c",
    "patient_id": "6543210fedcba9876543210b",
    "completed_at": "2025-01-01T00:00:00.000Z"
  }
}

Una entrega de appointment.updated para una cita que se movió a otra hora y a otro profesional de salud:

{
  "event": "appointment.updated",
  "timestamp": "2025-01-02T15:00:01.000Z",
  "organization_id": "6543210fedcba9876543210f",
  "data": {
    "appointment_id": "6543210fedcba9876543210d",
    "patient_id": "6543210fedcba9876543210b",
    "staff_ids": ["6543210fedcba98765432101"],
    "service_id": "6543210fedcba98765432102",
    "location_id": null,
    "status": "CONFIRMED",
    "start_time": "2025-01-03T17:00:00.000Z",
    "end_time": "2025-01-03T17:50:00.000Z",
    "changes": ["start_time", "staff"],
    "previous_start_time": "2025-01-03T16:00:00.000Z",
    "previous_staff_ids": ["6543210fedcba98765432103"]
  }
}

Los eventos contienen identificadores, no valores clínicos. Use esos identificadores para leer los registros desde los endpoints de Pruebas de Laboratorio y Biomarcadores, las respuestas de un formulario completado desde GET /patient-form y una cita desde GET /appointments.

Cómo verificar una entrega

Cada solicitud incluye el encabezado X-Luna-Signature: el HMAC-SHA256 del cuerpo original de la solicitud, firmado con su clave secreta de webhook y codificado en hexadecimal. Vuelva a calcular el HMAC sobre los bytes exactos que recibió y compárelo con una comparación de tiempo constante antes de confiar en la carga útil. Rechace cualquier solicitud cuya firma no coincida.

Comportamiento de entrega

Cada evento se intenta una sola vez, con un tiempo de espera de 10 segundos, y no se reintenta automáticamente. Responda 2xx con prontitud y realice el trabajo lento fuera de la solicitud para no perder una entrega por tiempo de espera. Como no hay reintentos, concilie con los endpoints de lectura si su integración necesita una garantía de completitud.

Su endpoint debe ser una dirección HTTPS pública. Se rechaza http:// sin cifrar, así como las direcciones internas, privadas y de loopback —incluidos los nombres de host que resuelvan a una de ellas—, porque las entregas contienen identificadores vinculados a pacientes.

Endpoints relacionados con pruebas de laboratorio

Endpoints para consultar las etiquetas de pacientes de su organización y para asignarlas o quitarlas a un paciente. Las etiquetas son solo rótulos: no permiten escribir datos clínicos ni de contacto, y tanto el paciente como la etiqueta están acotados a su organización. Asignar o quitar etiquetas requiere una clave de API con permiso de escritura.

Endpoints para listar y gestionar citas de su organización, y para consultar los profesionales de salud, servicios y horarios disponibles para agendar

Endpoints para recuperar registros de pagos (facturas) de su organización: listar pagos con filtrado por estado, método de pago, paciente y rango de fechas, y consultar un pago individual por ID. De la factura (CFDI) solo se exponen su UUID del SAT, serie, folio, estado y fechas de timbrado o cancelación; nunca los datos fiscales del receptor ni del emisor, los archivos XML/PDF ni identificadores de Stripe.