PMS · Sistema de Gestión de Propiedades Hoteleras

API REST · V1 — OpenAPI 3.0 — Bearer Token (operadores de hotel) — API Key (integraciones externas)

Toda esta API vive bajo /api/v1, y expone dos formas de autenticación según quién
consume el endpoint. Si eres un operador de hotel, autentícate con OTP para obtener
un Bearer token. Si eres una integración externa, autentícate con una API Key en el
header X-Api-Key — no necesitas Bearer token. El detalle completo de ambos
mecanismos está en el documento de Autenticación y Sesiones.

Visión general

Hoy la API permite:

• Autenticarse como operador de hotel y listar/filtrar las reservas de su
  establecimiento.
• Registrar y consultar consumos externos (ej. restaurante/bar) asociados a la
  reserva de un huésped, para integraciones de punto de venta.
• Recibir eventos de reserva desde channel managers/OTAs y notificaciones de
  facturación electrónica (integraciones entrantes).

Glosario del dominio

Autenticación

Dos mecanismos, según quién consume la API:

• Bearer token (OTP) — operadores de hotel.
• API Key — integraciones externas (Consumos Externos).

El flujo completo, ejemplos de request/response y límites de cada uno están en el
documento Autenticación y Sesiones.

Entornos y URLs base

Convenciones

Estándar de respuestas Index (paginación)

Todos los endpoints de listado retornan la paginación en los headers de la
respuesta y los datos en el body bajo la llave data. Los filtros aplicados
se reflejan en filters.

Headers de respuesta:

Current-Page: 1
Page-Limit:   20
Total-Count:  150
Total-Pages:  8

Body de respuesta:

{
  "data": [
    { "id": 1001, "status": "active" }
  ],
  "filters": {
    "stage": "checkin_registered",
    "pre_reservations": false,
    "post_reservations": false
  }
}

Fechas

Formato YYYY-MM-DD para fechas, ISO 8601 (2024-03-15T14:30:00.000Z) para
timestamps.

Filtrado

Los parámetros de filtro se envían como query params planos (ej. stage,
pre_reservations) o anidados con la notación campo[subcampo] para rangos (ej.
search_all_date_fields[start_date]). Los filtros aplicados se reflejan de vuelta
en la llave filters de la respuesta — ver ejemplo de paginación arriba.

Moneda

Cada hotel tiene su propia moneda configurada (ej. COP, MXN, PEN — el PMS opera
hoteles en varios países). Los montos numéricos (ej. amount en Consumos
Externos) no incluyen un código de moneda en la respuesta ni en el request —
se asume la moneda configurada del hotel correspondiente, que hoy no se expone vía
API. Si integras con hoteles en más de un país, confirma la moneda de cada hotel
por fuera de la API con tu contacto de integración.

Manejo de errores

Los endpoints de error retornan un objeto errors con la misma estructura. El
campo details es opcional y solo aparece cuando hay información adicional
relevante.

Sin detalles adicionales:

{ "errors": { "code": "unauthorized", "title": "Phone is blocked" } }

Con detalles adicionales:

{
  "errors": {
    "code": "too_many_requests",
    "title": "Login attempt limit exceeded",
    "details": "Maximum 5 attempts per hour. Try again later."
  }
}

Catálogo de códigos

Versionado y changelog

La API está en v1, estable. No hay cambios incompatibles anunciados — cualquier
cambio que rompa compatibilidad se comunicará con anticipación antes de aplicarse.

Changelog:

Referencia de API (consumible)

Próximamente: Huéspedes, Habitaciones y Disponibilidad, Tarifas, Housekeeping.

Integraciones entrantes (webhooks)

Estos endpoints los invoca el sistema externo, no el integrador — la plataforma los
expone para recibir sus eventos.