Agendar una cita

Encuentra el servicio. Busca el nombre que usó el paciente con agenda.bookingOfferings.list:

curl --get https://api.getarbol.com/v1/agenda/booking-offerings \
  --data-urlencode "q=neurología" --data-urlencode "limit=3" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Cada oferta en data.data lleva su id, su serviceId, sus sedes y lo que el servicio le pide al paciente: service.bookingChecklist, para contrastarlo con lo que sabes, service.patientInstructions y service.eligibility, como { "minAgeYears": 18, "maxAgeYears": null }. Si hay una regla de edad, necesitarás la fecha de nacimiento del paciente.

Revisa los requisitos. agenda.bookingRequirements.get responde con los campos de admisión, los tipos de documento y los pagadores; payerQuery deja fuera los pagadores que no vienen al caso:

curl --get https://api.getarbol.com/v1/agenda/booking-requirements \
  --data-urlencode "payerQuery=Example Health Plan" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

En data.fields, los campos predefinidos como phone y payer son off, optional o required, y document es optional o required; data.customFields agrega los campos propios de la organización; data.documentTypes lista los códigos de documento, como CC; y cada pagador en data.payers tiene una bookingPolicy, open o staff_only. Reúne cada valor obligatorio que aún no tengas. Si la política del pagador es staff_only, no agendes: pon al paciente en la lista de espera.

Encuentra un cupo. agenda.nearestBookingSlots.list responde con los horarios más cercanos en todas las agendas que ofrecen el servicio:

curl --get https://api.getarbol.com/v1/agenda/nearest-booking-slots \
  --data-urlencode "serviceId=svc_00000000-0000-4000-8000-000000000001" \
  --data-urlencode "timezone=America/Bogota" --data-urlencode "limit=3" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

{
  "startsAt": "2026-11-05T09:00:00-05:00",
  "timezone": "America/Bogota",
  "slotToken": "EXAMPLE_SLOT_TOKEN_0001"
}

Ese es el primer cupo de data.data, abreviado: cada uno también tiene su endsAt, su offeringId y sus resourceIds. Ofrécele los horarios al paciente en la timezone del cupo. Una lista vacía significa que no hay ningún espacio libre en todo el plazo en que se puede agendar el servicio: ofrece la lista de espera.

Agenda la cita cuando el paciente confirme el horario. Envía el slotToken sin cambios a agenda.bookings.create, con el paciente y los datos de admisión que exige la clínica:

curl https://api.getarbol.com/v1/agenda/bookings \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "slotToken": "EXAMPLE_SLOT_TOKEN_0001",
    "patient": { "name": "Example Patient", "documentNumber": "1234567890", "documentType": "CC" },
    "patientBirthDate": "1990-01-01",
    "intake": { "phone": "+57 300 000 0000", "entity": "Example Health Plan" }
  }'

La respuesta es la cita; guarda su id, que necesitan la reprogramación y la cancelación. Abreviado, de data:

{
  "id": "eng_00000000-0000-4000-8000-000000000005",
  "startsAt": "2026-11-05T09:00:00-05:00",
  "guidance": {
    "attendedBy": ["Dr. Example"],
    "patientInstructions": "Trae tu orden médica y llega 15 minutos antes.",
    "location": { "name": "Example Clinic North", "address": "Calle 00 # 00-00", "city": "Bogotá" }
  },
  "slip": { "url": "https://example.com/EXAMPLE-slip.pdf", "expiresAt": "2026-10-30T16:00:00Z" }
}

Confírmale la cita al paciente. Dile el horario y lo que dice guidance: las instrucciones, quién lo atiende y la sede con su dirección. Descarga el comprobante mientras su enlace funcione, dentro de la hora, y envíale el archivo PDF en lugar del enlace:

curl --fail --output appointment-slip.pdf "$SLIP_URL"

Aquí SLIP_URL contiene data.slip.url; el enlace no lleva credenciales. agenda.bookings.get vuelve a leer la cita más adelante, con sus indicaciones y su comprobante. Poner un estado como confirmed le corresponde a la clínica: el personal lo hace con agenda.appointments.changeStatus, que acepta solo personas.