APIActualizado: Junio 2026

API — Citas

Crea, consulta y cancela citas programáticamente desde tu sistema externo.

Endpoints

POST/api/v1/citas

Crea una nueva cita. Verifica disponibilidad y aplica el overlap check en una transacción serializable.

GET/api/v1/citas

Lista las citas del negocio. Soporta filtros por fecha, estado y servicio.

GET/api/v1/citas/:id

Obtiene los detalles de una cita específica.

PATCH/api/v1/citas/:id

Actualiza una cita (reprogramar, cambiar estado, notas).

DELETE/api/v1/citas/:id

Cancela una cita. Equivale a cambiar el estado a CANCELADA.

Request body — POST /api/v1/citas

typescript

interface CrearCitaRequest {
  servicioId: string           // ID del servicio del catálogo (requerido)
  nombreCliente: string        // Nombre del cliente (requerido)
  telefono?: string            // Teléfono WhatsApp del cliente (opcional)
  email?: string               // Email del cliente (opcional)
  fechaInicio: string          // ISO 8601: "2026-07-15T10:00:00-06:00"
  notas?: string               // Notas adicionales para el negocio
  camposPersonalizados?: {      // Respuestas a campos personalizados del servicio
    [campo: string]: string
  }
}

Atención

fechaInicio debe incluir el offset de zona horaria del negocio. El sistema valida que el slot esté dentro del horario de atención configurado y que no haya conflicto con citas existentes.

Response

201 Created — Cita creada exitosamente:

json

{
  "id": "cit_a1b2c3d4e5",
  "negocioId": "neg_xyz",
  "servicio": {
    "id": "srv_abc",
    "nombre": "Corte de cabello",
    "duracion": 45,
    "precio": "250.00"
  },
  "cliente": {
    "nombre": "María García",
    "telefono": "+525512345678"
  },
  "fechaInicio": "2026-07-15T10:00:00-06:00",
  "fechaFin": "2026-07-15T10:45:00-06:00",
  "estado": "PENDIENTE",
  "notas": null,
  "creadoEn": "2026-06-25T18:30:00Z"
}

409 Conflict — El slot no está disponible:

json

{
  "error": {
    "code": "SLOT_UNAVAILABLE",
    "message": "El horario seleccionado no está disponible.",
    "status": 409,
    "slotsDisponibles": [
      "2026-07-15T11:00:00-06:00",
      "2026-07-15T12:00:00-06:00",
      "2026-07-15T14:00:00-06:00"
    ]
  }
}

Errores específicos de citas

Código	HTTP	Descripción
`SERVICIO_NOT_FOUND`	404	El servicioId no existe en el catálogo del negocio
`SLOT_UNAVAILABLE`	409	El slot no está disponible (overlap)
`OUTSIDE_BUSINESS_HOURS`	422	La fecha/hora está fuera del horario de atención
`INVALID_DATE`	422	La fecha está en el pasado o tiene formato inválido
`SERVICIO_INACTIVO`	422	El servicio está marcado como inactivo

Ejemplos completos

Crear una cita (JavaScript)

javascript

const response = await fetch('https://app.xambee.com/api/v1/citas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer xam_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    servicioId: 'srv_abc123',
    nombreCliente: 'María García',
    telefono: '+525512345678',
    fechaInicio: '2026-07-15T10:00:00-06:00',
    notas: 'Cliente nueva, prefiere pago en efectivo',
    camposPersonalizados: {
      'longitud_cabello': 'largo',
      'primera_visita': 'sí'
    }
  })
})

if (!response.ok) {
  const error = await response.json()
  if (error.error.code === 'SLOT_UNAVAILABLE') {
    console.log('Slots alternativos:', error.error.slotsDisponibles)
  }
  throw new Error(error.error.message)
}

const cita = await response.json()
console.log('Cita creada:', cita.id)

Listar citas del día (curl)

bash

curl "https://app.xambee.com/api/v1/citas?fecha=2026-07-15&estado=PENDIENTE" \
  -H "Authorization: Bearer xam_tu_api_key"

Cancelar una cita

bash

curl -X DELETE "https://app.xambee.com/api/v1/citas/cit_a1b2c3d4e5" \
  -H "Authorization: Bearer xam_tu_api_key"