Para desarrolladores

Integrá tu sistema con la agenda del consultorio

Historias clínicas, gestión de clínicas, laboratorios, farmacias, software de obras sociales: una API REST con clave, alcances y webhooks firmados. Contrato en OpenAPI 3.1, sin reuniones para empezar.

OpenAPI 3.1 Guía completa Crear una clave (dueños)

1. Una clave por consultorio

El dueño de la cuenta la crea en Configuración → Integraciones → API y webhooks, elige qué alcances tiene y la comparte con vos. Se muestra una sola vez y se revoca al instante.

2. Leé y reservá

Catálogo, disponibilidad real (la misma que ve el paciente), turnos y fichas de contacto. Reservar por API dispara los mismos avisos, señas y listas de espera que el sitio.

3. Recibí cada cambio

Un webhook firmado por cada turno creado, confirmado, reprogramado o cancelado, venga de donde venga: panel, sitio, bot de WhatsApp o tu propia API. Con reintentos.

4. Sin historia clínica

La API expone contacto y cobertura del paciente, nunca notas ni evoluciones. Es dato sensible con régimen propio y no sale por acá.

Reservar un turno

Pasa por el mismo camino que el sitio y el bot: cupo del plan, agenda cerrada, seña anti-ausencia, lista de espera y avisos al paciente. Mandá Idempotency-Key y un reintento nunca crea dos turnos.

curl -X POST https://miagendaprofesional.com/api/v1/appointments \
  -H "Authorization: Bearer map_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c0e2a-…" \
  -d '{
    "patient": { "full_name": "Juan Pérez", "phone": "+5491155551234", "dni": "30111222" },
    "start": "2026-10-15T14:00:00-03:00",
    "location_id": "…", "service_id": "…",
    "external_ref": "tu-id-123"
  }'

Alcances

Cada clave declara qué puede hacer. Pedí el mínimo.

catalog:read
Profesionales, prestaciones y sedes.
availability:read
Horarios libres por fecha, sede, prestación y profesional.
appointments:read
Listar y leer turnos del consultorio.
appointments:write
Reservar, confirmar, reprogramar y cancelar turnos.
patients:read
Buscar y leer fichas de pacientes (datos de contacto, no historia clínica).
patients:write
Crear y actualizar fichas de pacientes.
prescriptions:read
Leer recetas electrónicas, incluida su forma FHIR.
prescriptions:write
Emitir y anular recetas electrónicas.
dispense:write
Registrar la dispensa de una receta.
*
Todos los alcances, incluidos los que se agreguen después.

Eventos por webhook

Firmados con HMAC-SHA256 sobre timestamp.body. Seis intentos con espera creciente. El id se repite en cada reintento: deduplicá con él.

ping
Prueba de entrega pedida desde el panel o desde POST /v1/webhooks/ping.
appointment.created
Se reservó un turno (por cualquier canal: panel, micrositio, bot, API).
appointment.confirmed
El turno pasó a confirmado.
appointment.rescheduled
Cambió la fecha u hora de inicio del turno.
appointment.cancelled
El turno se canceló.
appointment.completed
El turno se marcó como atendido.
appointment.no_show
El paciente no se presentó.
appointment.updated
Cambió el estado del turno a uno no cubierto por los anteriores, o cambió el profesional.
patient.created
Se creó una ficha de paciente.
rx.issued
Se emitió una receta electrónica.
rx.dispensed
Se registró una dispensa (total o parcial) de una receta.
rx.cancelled
Se anuló una receta.
rx.expired
Vencieron recetas (una entrega por día con los códigos).

const esperada = "sha256=" + crypto
  .createHmac("sha256", secret)
  .update(`${req.headers["x-webhook-timestamp"]}.${rawBody}`)
  .digest("hex");
// compará con req.headers["x-webhook-signature"] en tiempo constante
// y rechazá timestamps de más de 5 minutos

Seguridad, en una lista

Claves de 192 bits; se guarda el hash, no la clave.
Tope por clave contado en la base; tope por IP en el borde.
Errores con código estable: programá contra code.
Webhooks sólo a HTTPS público; sin IPs privadas ni metadata.
Firma con timestamp: rechazá lo que tenga más de 5 minutos.
Sin historia clínica, sin configuración, sin texto libre a pacientes.
Todo lo que un tercero hace queda en el turno y en los registros.
Receta electrónica: plataforma inscripta en ReNaPDiS (N° 297).

Versionado y contacto

v1 es estable: agregar campos o eventos no rompe nada, tolerá lo desconocido. Un cambio incompatible es v2, con seis meses de convivencia. Para una integración de producto, escribinos a soporte@miagendaprofesional.com diciendo qué sistema es, cuántos consultorios y qué necesitan leer y escribir.