APIActualizado: Junio 2026

API — Reservas

Crea y gestiona reservas de hospedaje desde tu motor de reservas externo o sistema de gestión hotelera.

Endpoints

POST/api/v1/reservas

Crea una nueva reserva. Verifica disponibilidad de la habitación y aplica la restricción de no solapamiento (EXCLUDE constraint).

GET/api/v1/reservas

Lista reservas con filtros por habitación, estado y rango de fechas.

GET/api/v1/reservas/:id

Obtiene detalles de una reserva específica.

PATCH/api/v1/reservas/:id

Actualiza una reserva: mover fechas, cambiar habitación, actualizar estado o agregar notas.

DELETE/api/v1/reservas/:id

Cancela una reserva. El huésped es notificado por WhatsApp si tiene teléfono registrado.

Request body — POST /api/v1/reservas

typescript

interface CrearReservaRequest {
  habitacionId: string    // ID de la habitación del catálogo (requerido)
  checkIn: string         // Fecha de llegada — YYYY-MM-DD (requerido)
  checkOut: string        // Fecha de salida — YYYY-MM-DD (requerido)
  huesped: {
    nombre: string        // Nombre completo del huésped (requerido)
    telefono?: string     // WhatsApp para notificaciones
    email?: string        // Email para confirmación
  }
  adultos?: number        // Número de adultos (default: 1)
  menores?: number        // Número de menores de edad (default: 0)
  modalidad?: 'COMPLETA' | 'ANTICIPO'  // Modalidad de pago
  montoAnticipo?: number  // Si modalidad es ANTICIPO, monto a cobrar
  notas?: string          // Peticiones especiales del huésped
}

Manejo de fechas

Las fechas de reserva son inclusivas en ambos extremos y representan días completos en UTC:

checkIn: "2026-07-15" → El huésped llega el 15 de julio (a cualquier hora)
checkOut: "2026-07-18" → El huésped sale el 18 de julio (antes del horario de checkout)
Número de noches: checkOut − checkIn = 3 noches

El sistema verifica que no exista otra reserva confirmada en la misma habitación para el mismo rango de fechas usando una restricción EXCLUDE a nivel de base de datos.

Atención

Las fechas son solo el día (YYYY-MM-DD), sin hora. La hora de check-in y check-out la define el negocio en sus políticas — no se especifica en la API.

Response

201 Created:

json

{
  "id": "res_p1q2r3s4",
  "negocioId": "neg_xyz",
  "habitacion": {
    "id": "hab_standard",
    "nombre": "Habitación Estándar",
    "precioNoche": "850.00"
  },
  "huesped": {
    "nombre": "Roberto Torres",
    "telefono": "+525534567890",
    "email": "roberto@email.com"
  },
  "checkIn": "2026-07-15",
  "checkOut": "2026-07-18",
  "noches": 3,
  "adultos": 2,
  "menores": 0,
  "modalidad": "ANTICIPO",
  "montoAnticipo": "500.00",
  "totalEstancia": "2550.00",
  "estado": "PENDIENTE_CONFIRMACION",
  "notas": "Cuna para bebé si es posible",
  "creadoEn": "2026-06-25T20:00:00Z"
}

409 Conflict — Habitación no disponible:

json

{
  "error": {
    "code": "HABITACION_NO_DISPONIBLE",
    "message": "La habitación no está disponible para las fechas solicitadas.",
    "status": 409,
    "habitacionesAlternativas": [
      {
        "id": "hab_superior",
        "nombre": "Habitación Superior",
        "precioNoche": "1200.00",
        "capacidad": 3
      }
    ]
  }
}

Ciclo de estados

Estado	Descripción	Transición
`PENDIENTE_CONFIRMACION`	Reserva recibida, pendiente de aprobación del gerente	Estado inicial
`CONFIRMADA`	Reserva aprobada por el negocio	Manager o API → CONFIRMADA
`PAGADA`	Anticipo o total cobrado con éxito	Pago recibido → PAGADA
`CHECKIN`	Huésped hizo check-in	API o panel → CHECKIN
`CHECKOUT`	Huésped hizo check-out, estancia completada	API o panel → CHECKOUT
`CANCELADA`	Reserva cancelada	Cualquier estado previo a CHECKIN

Errores específicos de reservas

Código	HTTP	Descripción
`HABITACION_NOT_FOUND`	404	El habitacionId no existe
`HABITACION_NO_DISPONIBLE`	409	La habitación está reservada en esas fechas
`FECHAS_INVALIDAS`	422	checkIn ≥ checkOut, o fechas en el pasado
`CAPACIDAD_EXCEDIDA`	422	adultos + menores exceden la capacidad de la habitación
`ANTICIPO_REQUERIDO`	422	modalidad ANTICIPO sin montoAnticipo

Ejemplos

Crear reserva con anticipo

javascript

const reserva = await fetch('https://app.xambee.com/api/v1/reservas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer xam_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    habitacionId: 'hab_standard_101',
    checkIn: '2026-07-15',
    checkOut: '2026-07-18',
    huesped: {
      nombre: 'Roberto Torres',
      telefono: '+525534567890',
      email: 'roberto@email.com'
    },
    adultos: 2,
    modalidad: 'ANTICIPO',
    montoAnticipo: 500,
    notas: 'Llegamos tarde, aproximadamente 11pm'
  })
}).then(r => r.json())

Consultar disponibilidad (GET con filtros)

bash

# Listar habitaciones disponibles para un rango de fechas
curl "https://app.xambee.com/api/v1/reservas/disponibilidad?checkIn=2026-07-15&checkOut=2026-07-18" \
  -H "Authorization: Bearer xam_tu_api_key"

Registrar check-in

bash

curl -X PATCH "https://app.xambee.com/api/v1/reservas/res_p1q2r3s4" \
  -H "Authorization: Bearer xam_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"estado": "CHECKIN"}'