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. Para registrar consumos, además
envía el token de tu socio de consumo en el header X-Api-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, listar/filtrar las reservas de su
  establecimiento y crear reservas nuevas.
• Consultar un hotel por su número de documento y las reservas activas de un
  huésped, y registrar consumos externos (ej. restaurante/bar) sobre esa reserva,
  para integraciones de punto de venta.
• Registrar y actualizar los socios de consumo (ej. un restaurante o bar)
  autorizados a cargar consumos a las reservas de un hotel.
• 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 (X-Api-Key) — integraciones externas (Consumos Externos y Socios
  de Consumo).
  • Al registrar un consumo (POST /api/v1/external_consumptions) se envía además
    el header X-Api-Token con el Token del socio de consumo, que retorna el
    registro del socio.

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. Cualquier cambio que rompa compatibilidad se
comunicará con anticipación antes de aplicarse y queda marcado como
incompatible en el changelog.

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.