Agendar una cita

Esta guía recorre el flujo completo para agendar una cita con la API de CitaPro. Usarás los endpoints en este orden: servicios, ubicaciones (sucursales), profesionales, disponibilidad, cliente (crear o buscar) y finalmente crear la reserva.

Paso 1: Obtener servicios

Lista los servicios del negocio para que el usuario elija uno. El servicio define la duración y el precio.

GET /v1/services

Ejemplo de respuesta (campos relevantes):

{
  "total": 10,
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "Corte de cabello",
      "duration": 60,
      "price": 50.0,
      "status": "active"
    }
  ]
}

Guarda el serviceId y la duration (en minutos) del servicio elegido para los siguientes pasos.

Consulta la referencia de Services para el schema completo.

Paso 2: Obtener ubicaciones (sucursales)

Lista las ubicaciones (sucursales) donde se ofrece el servicio. El usuario elegirá dónde quiere la cita.

GET /v1/locations

Ejemplo de respuesta (campos relevantes):

{
  "total": 3,
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Sede Principal",
      "address": "Av. Amazonas N36-152",
      "status": "active"
    }
  ]
}

Guarda el locationId elegido para consultar disponibilidad y crear la reserva.

Consulta la referencia de Locations para el schema completo.

Paso 3: Obtener profesionales (opcional)

Puedes listar los profesionales para que el usuario elija uno concreto, o omitir este paso y dejar que la disponibilidad devuelva todos los profesionales disponibles.

GET /v1/people

Puedes filtrar por locationId para mostrar solo profesionales de la sucursal elegida. La respuesta incluye id, firstname, lastname, email, status, etc.

Guarda el personId si el usuario elige un profesional; si no, omítelo al consultar disponibilidad.

Consulta la referencia de People para el schema completo.

Paso 4: Comprobar disponibilidad

Obtén los slots de tiempo disponibles para el servicio y la ubicación (y opcionalmente el profesional) en un rango de fechas.

GET /v1/bookings/availability?locationId={locationId}&serviceId={serviceId}&startDate=2026-03-10&endDate=2026-03-17

Parámetro	Requerido	Descripción
`locationId`	Sí	UUID de la ubicación
`serviceId`	Sí	UUID del servicio
`startDate`	No	Fecha inicio `YYYY-MM-DD` (por defecto: hoy)
`endDate`	No	Fecha fin `YYYY-MM-DD` (por defecto: startDate + 30 días, máx. 30 días)
`professionalId`	No	Filtrar por un profesional concreto (UUID)

Ejemplo de respuesta:

{
  "days": ["2026-03-10", "2026-03-11", "2026-03-12"],
  "professionals": [
    { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "María García" }
  ],
  "slots": [
    {
      "startTime": "2026-03-10 09:00:00",
      "endTime": "2026-03-10 10:00:00",
      "professionals": [
        { "id": "990e8400-e29b-41d4-a716-446655440004", "name": "María García" }
      ]
    }
  ],
  "limitExceeded": false
}

El usuario elige un slot. Usa el startTime y endTime de ese slot para la reserva (convierte a ISO 8601 si hace falta, ej. 2026-03-10T09:00:00Z). Si eligió profesional, usa el professionals[].id del slot como personId al crear la reserva.

Consulta Bookings – Consultar disponibilidad para más detalle.

Paso 5: Crear o obtener el cliente

Necesitas un clientId para crear la reserva. Puedes buscar un cliente existente (p. ej. por email) o crear uno nuevo.

Opción A: Buscar cliente existente

Lista clientes filtrando por email (o teléfono) y usa el primero que coincida:

GET /v1/clients?filters[0][field]=email&filters[0][operator]==&filters[0][value]=juan@example.com

Si items no está vacío, usa items[0].id como clientId.

Opción B: Crear un cliente nuevo

Si no existe el cliente, créalo:

POST /v1/clients
Content-Type: application/json

Body (campos mínimos requeridos):

{
  "firstname": "Juan",
  "lastname": "Pérez",
  "email": "juan@example.com",
  "phone": "+593991234568"
}

Respuesta: 201 Created con { "id": "660e8400-e29b-41d4-a716-446655440001" }. Usa este id como clientId.

Consulta la referencia de Clients para todos los campos (docType, birthdate, address, customFields, etc.).

Paso 6: Crear la reserva

Crea la cita con los datos reunidos en los pasos anteriores.

POST /v1/bookings
Content-Type: application/json

Body:

Campo	Valor
`startTime`	Inicio del slot elegido (ISO 8601, ej. `2026-03-10T09:00:00Z`)
`endTime`	Fin del slot elegido (ISO 8601, ej. `2026-03-10T10:00:00Z`)
`status`	p. ej. `confirmed` o `pending`
`amount`	Precio del servicio (p. ej. del objeto service)
`clientId`	UUID del cliente del paso 5
`locationId`	UUID de la ubicación del paso 2
`serviceId`	UUID del servicio del paso 1
`personId`	(Opcional) UUID del profesional del slot elegido
`notifyClient`	(Opcional) `true` para enviar confirmación al cliente

Ejemplo:

{
  "startTime": "2026-03-10T09:00:00Z",
  "endTime": "2026-03-10T10:00:00Z",
  "status": "confirmed",
  "amount": 50.00,
  "clientId": "660e8400-e29b-41d4-a716-446655440001",
  "locationId": "770e8400-e29b-41d4-a716-446655440002",
  "serviceId": "880e8400-e29b-41d4-a716-446655440003",
  "personId": "990e8400-e29b-41d4-a716-446655440004",
  "notifyClient": true
}

Respuesta: 201 Created con { "id": "cc0e8400-e29b-41d4-a716-446655440007" } — el ID de la nueva reserva.

Consulta Bookings – Crear reserva para el schema completo y reglas de validación.

Resumen

Paso	Endpoint	Objetivo
1	`GET /services`	Elegir servicio (id, duración, precio)
2	`GET /locations`	Elegir ubicación/sucursal
3	`GET /people`	(Opcional) Elegir profesional
4	`GET /bookings/availability`	Obtener slots disponibles
5	`GET /clients` o `POST /clients`	Obtener o crear cliente
6	`POST /bookings`	Crear la cita

Maneja errores de validación (422) y rate limiting (429) en tu cliente para una integración robusta.