Inicio rápido

Cinco llamadas llevan de una key a una reserva. Todo lo de acá corre contra el
sandbox, así que se puede pegar tal cual.

Hace falta una API key emitida por el hotel desde su cuenta de Axis Pro — ver
Emitir API keys si uno es el hotel.

export AXIS_KEY="axis_live_…"
export AXIS="https://api.sandbox.axispro.travel/api/external/v1"   # sandbox
# export AXIS="https://api.axispro.travel/api/external/v1"         # producción

Hay que usar el host al que pertenece la key. Una key sirve en un solo
ambiente: a una key de sandbox producción la rechaza, y al revés igual, las dos
con el mismo 401. Una reserva creada contra producción es una reserva real en
un hotel real.

1. Revisar la key

curl "$AXIS/health" -H "X-API-Key: $AXIS_KEY"

{ "status": "ok", "version": "v1" }

Cualquier otra respuesta y nada de lo de abajo va a funcionar. Un 401 significa
que la key es desconocida, expiró, fue revocada o está desactivada —
todas se responden igual.

2. Encontrar la propiedad

curl "$AXIS/properties" -H "X-API-Key: $AXIS_KEY"

{ "data": [ {
  "id": "01a06051-69f0-72f8-8ad6-b46960495eb2",
  "name": "Hotel Casa Antigua",
  "timezone": "America/Guatemala",
  "default_currency": "USD",
  "api_rate_plans_configured": true
} ] }

Dos cosas que leer acá:

• Si vuelve más de una propiedad, toda llamada de aquí en adelante necesita
  un header X-Property con el id. Si vuelve exactamente una, no hay que
  mandar el header — ver
  Alcances y el header X-Property.
• api_rate_plans_configured: false significa que el hotel no tiene ningún
  plan tarifario en el canal api. Los pasos 3 a 5 van a volver vacíos,
  correctamente, y solo el hotel puede arreglarlo.

3. Ver qué está libre

curl -G "$AXIS/availability" \
  -H "X-API-Key: $AXIS_KEY" \
  -d start=2027-03-01 -d end=2027-03-04

{ "data": [ {
  "unit_id": "01a06051-69f2-724a-bfe0-57b5b5dab318",
  "name": "Deluxe Double",
  "available": true,
  "remaining_capacity": 1
} ] }

start es la primera noche, end es el día de salida. /rates usa from y
to en su lugar — los dos no son intercambiables.

4. Cotizar la estadía

Primero, los planes tarifarios y sus precios por noche:

curl -G "$AXIS/rates" \
  -H "X-API-Key: $AXIS_KEY" \
  -d from=2027-03-01 -d to=2027-03-03

Cada unidad vuelve con sus planes del canal api, cada uno con su propio
rate_plan_id y una grilla noche por noche. Después se cotiza una estadía
concreta:

curl -X POST "$AXIS/quote" \
  -H "X-API-Key: $AXIS_KEY" -H "Content-Type: application/json" \
  -d '{
    "unit_id": "01a06051-69f2-724a-bfe0-57b5b5dab318",
    "rate_plan_id": "01a06051-69f4-7072-b4da-9bb17cb00e73",
    "start_date": "2027-03-01",
    "end_date": "2027-03-04",
    "adults": 2
  }'

{ "data": {
  "nights": 3,
  "currency": "USD",
  "subtotal": "450.00",
  "total_price": "450.00",
  "tax_amount": "0.00",
  "total_with_tax": "450.00",
  "available": true
} }

Hay que mostrar total_with_tax. Eso es lo que debe el huésped. Y ojo con
que el dinero es un string — parsear "450.00" como float pierde centavos en
silencio.

Una cotización no retiene nada. Los precios se pueden mover entre acá y el paso
5, y el que cuenta es el total de la propia reserva.

5. Reservar

curl -X POST "$AXIS/bookings" \
  -H "X-API-Key: $AXIS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-ada-2027-03-01" \
  -d '{
    "unit_id": "01a06051-69f2-724a-bfe0-57b5b5dab318",
    "rate_plan_id": "01a06051-69f4-7072-b4da-9bb17cb00e73",
    "start_date": "2027-03-01",
    "end_date": "2027-03-04",
    "adults": 2,
    "guest": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "[email protected]"
    }
  }'

{ "data": {
  "code": "P8963-000001",
  "status": "pending",
  "total_price": "450.00",
  "balance_due": "450.00"
} }

El header Idempotency-Key es obligatorio. Hay que reusar el mismo valor al
reintentar: un timeout no es prueba de que la reserva falló, y repetir la key
devuelve la reserva original en vez de crear una segunda. Ver
Idempotencia.

La reserva se crea pending y sin pagar. Esta API no toma pagos.

Qué leer después

• Idempotencia — antes de poner en producción algo que
  reintente.
• Errores — hay que comparar contra error_code, y ojo que
  los errores de validación no traen uno.
• Límites de uso — antes de escribir un bucle.
• Reservas —
  en particular por qué no hay que calcular un saldo como
  total_price − paid_amount.

Dos cosas que si no muerden

Una habitación que se ve en el sistema propio del hotel puede estar ausente
acá. Una unidad solo aparece si está publicada, es vendible y tiene un plan
tarifario activo en el canal de venta api. Esa es decisión del hotel, y es
lo primero que hay que revisar cuando faltan habitaciones esperadas.

Un 404 esconde tres situaciones distintas — el recurso no existe,
pertenece a otra propiedad, o no está expuesto a esta API. Se responden igual
para que nadie pueda mapear una cuenta sondeando ids.