Agendar citas de calendario

Usa los endpoints de calendario para agendar citas en tu calendario de Dialtu desde n8n, Zapier, un formulario web o tu propio backend, y para comprobar cuánto espacio queda antes de hacerlo:

Get bookable capacity per service — GET /api/v2/public/calendar/availability
List bookable services — GET /api/v2/public/calendar/services
Book an appointment — POST /api/v2/public/calendar/events
Listas de espera: añadir, listar, quitar y resumir entradas bajo /api/v2/public/calendar/waitlist/

Todos los campos de una reserva son obligatorios. Esta API no tiene valores por defecto: nunca elige por ti el servicio, el profesional ni el tipo de cita, nunca deriva la hora de fin de una duración y nunca envía una notificación que no hayas configurado. Si un valor no coincide con algo de tu cuenta, la solicitud se rechaza y el error lista lo que sí se habría aceptado.

Conceptos

Una cita se compone de cuatro cosas, y tú aportas las cuatro.

Cosa	Qué es	Cómo la envías
Cliente	El paciente o cliente. Se busca por teléfono; se crea automáticamente la primera vez. Solo hace falta nombre cuando el número es nuevo en tu cuenta.	objeto `client`
Servicio	Para qué es la cita (“Consulta”, “Corte de pelo”).	`service_id` o `service_name`
Profesional	Con quién es la cita.	`professional_id` o `professional_name`
Tipo de cita	El formato (Presencial, Videollamada, Llamada).	`event_type_id` o `event_type_name`

Para cada uno de los tres últimos, envía el ID o el nombre. Los IDs se comparan de forma exacta. Los nombres se comparan sin distinguir mayúsculas ni acentos, así que consulta medica encuentra Consulta Médica. Si envías ambos, se usa el ID. Llama a List bookable services una vez para ver los IDs y nombres exactos que acepta tu cuenta:

{
  "status": "success",
  "data": [
    {
      "id": 12,
      "name": "Consulta Médica",
      "default_duration_minutes": 30,
      "professionals": [ { "id": 4, "name": "Dra. Ana Gómez" }, { "id": 7, "name": "Dr. Luis Peña" } ],
      "event_types": [ { "id": 1, "name": "In-Person" }, { "id": 2, "name": "Video call" } ]
    }
  ]
}

Horas y el campo `timezone`

Envía la hora local que le diste al cliente, más la zona IANA a la que pertenece:

{ "start_at": "2026-09-15T14:00:00", "end_at": "2026-09-15T14:30:00", "timezone": "America/Bogota" }

No tienes que calcular el desfase UTC ni preocuparte por el horario de verano: las reglas de esa zona en esa fecha se aplican por ti. Si lo prefieres, incluye un desfase explícito (2026-09-15T09:00:00-05:00); entonces el desfase prevalece sobre timezone, que sigue siendo obligatorio. end_at es obligatorio y nunca se deriva de la duración por defecto del servicio: cuánto dura la cita es una afirmación tuya, no algo que la API deduzca.

Dos cosas que esta API hace distinto

Nunca rechaza por disponibilidad. Si la hora cae fuera del horario laboral o choca con otra cita, se agenda igualmente. Tu sistema es dueño de la agenda; Dialtu la registra. No verás un 409 en una reserva normal.
No decide qué mensajes salen. Que el cliente reciba una solicitud de confirmación o recordatorios, y con cuánta antelación, viene de la configuración del propio calendario en Dialtu (Calendario → Configuración → Notificaciones). Una cita agendada por aquí recibe exactamente los mismos mensajes que una agendada en el panel. No hay campos para ello, a propósito: esos mensajes se facturan a la cuenta de Dialtu, así que los elige el dueño de la cuenta.

Una reserva de principio a fin

curl -X POST https://api.dialtu.com/api/v2/public/calendar/events \
  -H "Authorization: Bearer pk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "client": { "first_name": "Jane", "last_name": "Roe", "phone": "+573001112233", "email": "jane.roe@example.com" },
    "service_name": "Consulta Médica",
    "professional_name": "Ana Gómez",
    "event_type_name": "In-Person",
    "start_at": "2026-09-15T14:00:00",
    "end_at": "2026-09-15T14:30:00",
    "timezone": "America/Bogota"
  }'

{
  "status": "success",
  "data": {
    "id": 8811,
    "start_at": "2026-09-15T19:00:00Z",
    "end_at": "2026-09-15T19:30:00Z",
    "status": "booked",
    "source": "api",
    "confirmation_status": "pending",
    "client": { "id": 512, "name": "Jane Roe", "phone": "+573001112233" },
    "calendar_profile": { "calendar_profile_id": 4, "name": "Dra. Ana Gómez" },
    "service": { "id": 12, "name": "Consulta Médica", "color": "#6633ff" },
    "event_type": { "id": 1, "name": "In-Person", "color": "#2b8a3e" },
    "custom_fields": { "booked_by": "api" },
    "created_at": "2026-09-02T18:04:11Z"
  },
  "client_id": 512,
  "client_created": true
}

Guarda data.id: es el ID de la cita en Dialtu. client_created indica si la solicitud creó el cliente (true) o coincidió con uno existente (false).

Comprobar la capacidad antes

Get bookable capacity per service responde “¿cuántas citas más caben?” por servicio en un rango de fechas. capacity se suma por profesional, no por instante — tres profesionales libres a las 09:00 son tres clientes a los que puedes llamar, no un hueco — y es una cota superior: reservar un hueco puede eliminar más de un candidato cuando interactúan los márgenes. Mantén days alineado con la ventana de búsqueda del agente que hará las llamadas, para no encolar clientes a los que el agente luego dirá que no hay disponibilidad.

Conectarlo con n8n

Nodo HTTP Request

Método POST, URL https://api.dialtu.com/api/v2/public/calendar/events.

Autenticación

Generic Credential Type → Header Auth, nombre Authorization, valor Bearer pk_xxxxxxxx.

Cuerpo

Body Content Type JSON; pega el cuerpo de arriba y sustituye los valores por expresiones de tus nodos anteriores. Consulta una vez los nombres de servicio, profesional y tipo de cita con List bookable services y deja los IDs fijos: nada es opcional.

Ante un error

Lee error_code del cuerpo de la respuesta. Ningún 400 merece reintentarse sin cambios; un 500 sí. Ver Errores.

Todavía no disponible

Leer, listar, reprogramar y cancelar citas por la API no está implementado. Cancela o mueve una cita desde el panel de Dialtu. Si eliminas la cita en tu sistema, la de Dialtu se queda: cancélala a mano.

Empezar

Guías

Endpoints

Agendar citas de calendario

Conceptos

Horas y el campo `timezone`

Dos cosas que esta API hace distinto

Una reserva de principio a fin

Comprobar la capacidad antes

Conectarlo con n8n

Todavía no disponible

​Conceptos

​Horas y el campo timezone

​Dos cosas que esta API hace distinto

​Una reserva de principio a fin

​Comprobar la capacidad antes

​Conectarlo con n8n

​Todavía no disponible

Conceptos

Horas y el campo `timezone`

Dos cosas que esta API hace distinto

Una reserva de principio a fin

Comprobar la capacidad antes

Conectarlo con n8n

Todavía no disponible