API pública

Conecta tu sitio web o tu propio sistema con la agenda de Lexa. Con una clave de API puedes consultar sucursales, servicios, profesionales y horas disponibles, buscar un paciente por RUT y agendarle una cita, todo desde tu código y sin entrar a Lexa.

1. Cuándo te sirve (y cuándo no)

La API es para agendar desde afuera: tu sitio web con diseño propio, tu app, un chatbot, o un sistema que ya usas y quieres que escriba en la agenda de Lexa.

🔴 La API no crea fichas de pacientes. Solo agenda para pacientes que ya existen en tu centro. Es a propósito: el consentimiento de datos de la Ley 21.719 lo tiene que dar el paciente en pantalla, y eso lo hace el centro, no un sistema de un tercero.

Si lo que necesitas es que un paciente nuevo reserve solo, lo tuyo es la Agenda online: un widget que se pega en tu web, pide el consentimiento y crea la ficha. No hace falta programar nada.

2. Crear tu clave

Como administrador, ve a Administración → Cuenta Lexa → Claves de API y ponle un nombre que te diga después para qué es ("Web del centro", "Bot de WhatsApp"). Cada integración debería tener la suya: así puedes revocar una sin dejar caer las demás.

⚠️ La clave se muestra una sola vez. No se guarda en ninguna parte que la pueda recuperar, ni siquiera nosotros: en la base solo queda su huella. Cópiala al crearla y guárdala donde guardes tus otras contraseñas. Si la pierdes, revoca esa y crea otra.

En esa misma pantalla ves cada clave con su último uso y el consumo del mes, y puedes revocar la que ya no uses. Una clave revocada deja de funcionar de inmediato: cualquier sistema que la esté usando empieza a recibir error en la siguiente llamada.

Trátala como una contraseña. Quien la tenga puede leer tu agenda y crear citas a nombre de tu centro, así que no la pongas en el código JavaScript de tu página: ahí la ve cualquiera que abra el navegador. Va en tu servidor.

3. Cómo autenticar

Cada llamada lleva la clave en la cabecera X-Api-Key:

curl https://lexa-api.azurewebsites.net/public/v1/branches \
  -H "X-Api-Key: lxa_live_tuclaveaca"

La clave identifica a tu centro. No hace falta mandar ningún identificador de empresa: si lo mandaras, se ignora. Todo lo que la API lee y escribe es de tu centro y de ningún otro.

4. Los endpoints

Todos cuelgan de https://lexa-api.azurewebsites.net/public/v1.

Los identificadores son códigos largos (tipo 3fa85f64-5717-4562-b3fc-2c963f66afa6) y no números correlativos. Los obtienes de las respuestas: primero pides sucursales, con esa sucursal pides servicios, y así.

Horas: siempre con zona horaria

Las horas van y vuelven en formato ISO-8601 con el desfase horario explícito: 2026-09-20T10:00:00-03:00. No es un capricho de formato. En Chile el reloj cambia dos veces al año, y hay un día en que las 00:30 sencillamente no existen; con el desfase puesto, la hora que pides es la que agendas, sin ambigüedad.

Agendar

curl -X POST https://lexa-api.azurewebsites.net/public/v1/appointments \
  -H "X-Api-Key: lxa_live_tuclaveaca" \
  -H "Idempotency-Key: 9f1c6e2a-3b4d-4c8e-9a11-7f2e5d0c8b41" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "branchId": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "serviceId": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
    "therapistId": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
    "start": "2026-09-20T10:00:00-03:00"
  }'

La cita se crea con las mismas reglas que si la agendara alguien desde Lexa: horario del profesional, feriados, choques con otras citas, precio del servicio. Si alguna regla la rechaza, te llega el motivo redactado, no un error genérico.

La cita queda visible en la agenda al instante y recepción recibe su aviso, igual que con una reserva online.

5. Reintentos sin citas duplicadas

El POST /appointments exige la cabecera Idempotency-Key: un valor único que inventas tú por cada operación (un UUID sirve).

Sirve para lo que pasa de verdad: mandas la petición, se corta la conexión y no sabes si la cita quedó. Reintentas con la misma clave y en vez de una segunda cita recibes la respuesta de la primera. Distinto es agendar otra cita: eso lleva una clave nueva.

• Misma clave, mismo contenido → te devolvemos la respuesta guardada. No se crea nada.
• Misma clave, contenido distinto → error: es otra operación, usa otra clave.
• Misma clave mientras la primera todavía se está procesando → error temporal, reintenta en unos segundos.

Las claves se recuerdan 24 horas.

6. Límites y consumo

Cada respuesta trae tu consumo del mes en las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. El mismo número lo ves en Administración → Cuenta Lexa → Claves de API.

Pasarse de la ráfaga devuelve 429: espera y reintenta, no insistas en el momento.

7. Errores

Los errores vienen en JSON con un campo code estable —léelo desde tu código, en vez de comparar el texto— y un detail en español pensado para mostrárselo a alguien.

Un 401 es clave inválida, revocada o vencida. Un 429, demasiadas llamadas.

8. Preguntas frecuentes

¿Cuánto cuesta? Está incluida en tu plan. El consumo se cuenta y se te muestra, y hoy no se corta por cupo.

¿Puedo cancelar o reagendar por la API? Todavía no. Esta primera versión lee el catálogo, busca paciente y agenda. Cancelar y reagendar se hacen desde Lexa.

¿Puedo cobrarle al paciente al agendar? Por la API no. Si necesitas cobro al reservar, eso lo hace la Agenda online con Flow.

Perdí la clave, ¿me la pueden recuperar? No, y no es una política: técnicamente no existe en ninguna parte. Revoca esa y crea otra.

¿Qué pasa si revoco una clave que está en uso? Deja de funcionar en la siguiente llamada. Si es la de un sistema en producción, ten lista la nueva antes de revocar la vieja.

¿La API puede ver datos clínicos? No. Solo el catálogo para agendar (sucursales, servicios, profesionales, horas), y de un paciente devuelve nada más que su nombre para que confirmes a quién estás agendando. Notas clínicas, documentos y datos de contacto no se exponen.