API de Resorts: comprensión de los estados y políticas de las reservas

Este artículo cubre el ciclo de vida de la reserva, las transiciones de estado, las políticas de propiedad, las tarifas obligatorias y los escenarios de error comunes en Resorts API v2. Comprender estos conceptos es esencial para construir una integración sólida.

Ciclo de vida del estado de la reserva

Cada reserva de resort pasa por una serie de estados. El siguiente diagrama muestra las posibles transiciones:

                  ┌──────────┐
                  │   HOLD   │
                  └────┬─────┘
                       │
            ┌──────────┼──────────┐
            ▼                     ▼
    ┌──────────────┐      ┌──────────────┐
    │  CONFIRMED   │      │   RELEASED   │
    └──────────────┘      └──────────────┘

Definiciones de estado

Detalles de estado

MANTENER

• Creado cuando llamas al punto final POST /itineraries.
• La habitación queda reservada temporalmente para el huésped.
• Debes confirmar o liberar la retención dentro del plazo permitido.
• Si no se actúa sobre una retención, ésta puede caducar automáticamente.

CONFIRMADO

• La reserva está finalizada y activa.
• Una reserva entra en este estado:

• Este es un estado terminal: las reservas confirmadas no se pueden liberar a través del punto final de los itinerarios.

LANZADO

• La retención se liberó explícitamente a través de PUT /itineraries?status=RELEASE.
• La habitación ya no está reservada y queda a disposición de otros huéspedes.
• Este es un estado terminal: las reservas liberadas no se pueden restablecer.
• Para volver a reservar, el huésped debe volver a realizar todo el flujo de búsqueda hasta reserva.

Importante: Confirmación Inmediata

No todas las reservas pasan por un estado de retención. Algunas reservas se confirman inmediatamente cuando llamas a POST /itineraries. Su integración debe marcar el campo status en la respuesta y manejar ambos escenarios:

// Scenario 1: Hold created
{ "reference_number": "XRN-001", "status": "HOLD" }
// Scenario 2: Immediately confirmed
{ "reference_number": "XRN-002", "status": "CONFIRMED" }

Si el estado es CONFIRMED, no intente llamar al punto final de confirmación: la reserva ya está finalizada.

Políticas de propiedad y tarifas obligatorias

Cuando recupera los detalles de la reserva, la respuesta incluye una sección urgentinfo en propertydetails. Contiene información crítica sobre políticas que debe comunicarse al huésped.

Tarifas obligatorias

Las tarifas obligatorias son cargos que se cobran en el establecimiento y que no están incluidos en el precio de la reserva. Estos son adicionales a los total_rate pagados al momento de la reserva.

"mandatory_fees": [
  {
    "description": "Resort fee",
    "amount": 25.00,
    "currency": "USD",
    "frequency": "per night"
  },
  {
    "description": "Parking fee",
    "amount": 15.00,
    "currency": "USD",
    "frequency": "per night"
  }
]

Mejores prácticas: Calcule y muestre las tarifas obligatorias totales para la estadía completa junto con la tarifa de reserva para que los huéspedes comprendan el costo completo. Por ejemplo: "Tarifa del complejo: $25,00/noche x 6 noches = $150,00 a pagar al momento del check-in".

Restricciones de política

Las restricciones de política definen las reglas y requisitos de la propiedad.

"policy_restrictions": {
  "pets": "No pets allowed.",
  "smoking": "Non-smoking property. Smoking is prohibited in all rooms and common areas.",
  "minimum_age": 21,
  "resort_fees": "A mandatory resort fee of $25.00 per night is charged at check-in. This fee covers pool access, Wi-Fi, and fitness center."
}

Práctica recomendada: Muestra las restricciones de las políticas en dos puntos clave:

1. Antes de reservar: muestra las políticas en los detalles de la propiedad o en la página de confirmación de la reserva para que los huéspedes puedan tomar una decisión informada.
2. Después de la reserva: incluya las políticas en el correo electrónico de confirmación de la reserva y en las comunicaciones previas a la llegada.

Referencia de errores

A continuación se muestra un resumen de los errores comunes que puede encontrar a lo largo del ciclo de vida de la reserva.

400 — Solicitud incorrecta

{
  "message": "Total rate does not match the confirmed price",
  "status": 400
}

404 - No encontrado

{
  "message": "No results found",
  "status": 404
}

417 — Expectativa fallida| Escenario | Descripción |

{
  "message": "Booking is not in HOLD state",
  "status": 417
}

Lista de verificación de integración

Utilice esta lista de verificación para verificar que la integración de su API de Resorts maneje todos los escenarios clave:

• [ ] Autocompletar devuelve resultados y códigos de región se almacenan correctamente.
• [ ] Búsqueda de propiedad envía el código de región, fechas y coordenadas.
• [] Los filtros y la clasificación se aplican correctamente y manejan conjuntos de resultados vacíos.
• [ ] Los detalles de la propiedad y los datos de las instalaciones se recuperan y almacenan en caché de forma adecuada.
• [ ] Verificación de disponibilidad almacena la habitación token para la habitación seleccionada.
• [ ] Confirmación de precio utiliza el totalRate (camelCase) confirmado para la reserva.
• [ ] Creación de retención pasa los totalrate, token y recommendationid correctos.
• [ ] Ambos estados de reserva (HOLD y CONFIRMED) se manejan desde el punto final de retención.
• [ ] Confirmar retención se llama solo cuando el estado inicial es HOLD.
• [ ] Retención de liberación está disponible para reservas en el estado HOLD.
• [ ] Recuperación de reservas muestra todos los detalles, incluido urgent_info.
• [ ] Las tarifas obligatorias se calculan y se muestran claramente al huésped.
• [ ] Las restricciones de la política aparecen antes y después de la reserva.
• [ ] Respuestas de error (400, 404, 417) se manejan elegantemente con mensajes fáciles de usar.

Este es el artículo final de la serie Resorts API. Si tiene preguntas o necesita ayuda, comuníquese con customersupport@xeni.com.