Reservations

Descripción

Las reservas Partners se crean en dos pasos:

Reserva temporal — crea la orden en Vulcano y bloquea cupos por 15 minutos.
Confirmar reserva — envía datos del customer y pasajeros.

Requiere el permiso reservations:write.

Flujo recomendado

GET /tours?zone=…&date_from=…&date_to=…&passengers=…
POST /reservations                 → HOLD (15 min)
GET /reservations/{id}             → consultar estado (opcional)
POST /reservations/confirm         → CONFIRMED
POST /reservations/cancel          → CANCELLED (hold o confirmada)

Si el hold expira antes del confirm → 409.

Paso 1 — Crear reservation (hold)

POST /reservations

curl -s -X POST "https://api-sandbox.vulcanopro.com/api/v1/reservations" \
  -H "X-API-KEY: TU_API_KEY" \
  -H "X-API-SECRET: TU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "tour_id": 3448,
    "date": "2026-08-12",
    "time": "15:30",
    "pax": {
      "adult": 2,
      "child": 1,
      "senior": 0,
      "infant": 1
    }
  }'

Body

Campo	Tipo	Requerido	Descripción
`tour_id`	integer	Sí	ID del tour (de `GET /tours`)
`date`	string	Sí	`YYYY-MM-DD`
`time`	string	Sí	`HH:mm` (horario de un `departure` disponible)
`pax.adult`	integer	No*	Adultos
`pax.child`	integer	No*	Niños
`pax.senior`	integer	No*	Adultos mayores
`pax.infant`	integer	No	Infantes (no restan cupo)

* Al menos 1 entre adult + child + senior.

Respuesta

{
  "status": "ok",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "HOLD",
    "tour_id": 3448,
    "sale_channel_id": 97,
    "date": "2026-08-12",
    "time": "15:30",
    "pax": { "adult": 2, "child": 1, "senior": 0, "infant": 1 },
    "seats": 3,
    "expires_at": "2026-08-12T15:45:00+00:00",
    "order_id": 9001,
    "external_reference": null,
    "customer": null,
    "passengers": null,
    "additional_activities": [],
    "created_at": "2026-08-12T15:30:00+00:00"
  },
  "timestamp": "2026-08-12T15:30:00.000Z"
}

Campo respuesta	Descripción
`id`	UUID de la reservation. Úsalo en confirm y en `GET /reservations/{id}`
`order_id`	ID interno de la orden en Vulcano (referencia; no se envía en confirm)
`seats`	Cupos bloqueados (`adult + child + senior`)
`expires_at`	Fin de vigencia del hold (ISO-8601)

Errores frecuentes del hold:

HTTP	Causa
`403`	Sin `reservations:write` o partner sin canal vinculado
`409`	Sin disponibilidad suficiente
`422`	Tour / fecha / hora no válidos para el canal

Paso 2 — Confirmar

POST /reservations/confirm

curl -s -X POST "https://api-sandbox.vulcanopro.com/api/v1/reservations/confirm" \
  -H "X-API-KEY: TU_API_KEY" \
  -H "X-API-SECRET: TU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "11111111-1111-1111-1111-111111111111",
    "customer": {
      "name": "Ana",
      "lastname": "Pérez",
      "email": "[email protected]",
      "phone": "99999999",
      "phone_code": "+56",
      "identification": "11.111.111-1",
      "birthday": "1990-05-10"
    },
    "passengers": [
      {
        "type": "adult",
        "name": "Ana",
        "lastname": "Pérez",
        "email": "[email protected]",
        "birthday": "1990-05-10",
        "identification": "11.111.111-1",
        "phone_cod": "+56",
        "phone": "99999999",
        "nationality": 44
      },
      {
        "type": "adult",
        "name": "Luis",
        "lastname": "Pérez",
        "email": "[email protected]",
        "birthday": "1988-03-02",
        "identification": "22.222.222-2",
        "phone_cod": "+56",
        "phone": "98888888",
        "nationality": 44
      },
      {
        "type": "infant",
        "name": "Baby",
        "lastname": "Pérez",
        "email": "[email protected]",
        "birthday": "2025-01-01",
        "identification": "N/A",
        "nationality": 44
      }
    ],
    "external_reference": "OTA-99",
    "additional_activities": [
      { "id": 12, "quantity": 2 }
    ]
  }'

Body — campos de primer nivel

Campo	Tipo	Requerido	Descripción
`id`	uuid	Sí	UUID de la reservation (status HOLD)
`customer`	object	Sí	Customer / comprador
`passengers`	array	Sí	Debe cuadrar con el `pax` del hold
`additional_activities`	array	No	Extras del tour (`id` + `quantity`), igual que en la ficha pública
`external_reference`	string	No	Tu referencia interna (OTA, etc.)

`customer`

Campo	Tipo	Requerido
`name`	string	Sí
`lastname`	string	Sí
`email`	string	Sí
`phone`	string	No
`phone_code`	string	No
`identification`	string	No
`birthday`	string (`YYYY-MM-DD`)	No

`passengers[]`

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`adult`, `child`, `senior` o `infant`
`name`	string	Sí	Nombre
`lastname`	string	Sí	Apellido
`email`	string	Sí	Email
`birthday`	string	Sí	`YYYY-MM-DD`
`identification`	string	Sí	Documento
`phone_cod`	string	No	Código país teléfono
`phone`	string	No	Teléfono
`nationality`	integer	No	ID de país (`GET /countries`)

La cantidad de pasajeros por type debe coincidir con el pax de la reserva temporal. Si no → 422.

`additional_activities[]`

Opcional. Los id salen de GET /tours → additional_activities. Cada extra se selecciona con cantidad.

Campo	Tipo	Requerido	Descripción
`id`	integer	Sí	ID de la actividad adicional del tour
`quantity`	integer	Sí	Cantidad (≥ 1)

Errores frecuentes del confirm:

HTTP	Causa
`403`	Reservation de otro partner / sin permiso
`404`	UUID inexistente
`409`	Hold expirado, cancelado, o sin cupo al confirmar
`422`	Validación (passengers incompletos, no cuadran con `pax`, o extras inválidos)

Si recibes 409 por hold expirado, no se puede “reactivar” el mismo hold. Debes crear uno nuevo.

Paso 3 — Consultar reservation

GET /reservations/{id} Devuelve la reserva por UUID (id del hold). El shape de data es el mismo que hold/confirm.

Requiere reservations:write. Solo puedes consultar reservas de tu canal.

curl -s "https://api-sandbox.vulcanopro.com/api/v1/reservations/11111111-1111-1111-1111-111111111111" \
  -H "X-API-KEY: TU_API_KEY" \
  -H "X-API-SECRET: TU_API_SECRET"

Path

Parámetro	Tipo	Requerido	Descripción
`id`	uuid	Sí	UUID de la reservation (el `id` de `POST /reservations`)

Respuesta

{
  "status": "ok",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "CONFIRMED",
    "tour_id": 3448,
    "sale_channel_id": 97,
    "date": "2026-08-12",
    "time": "15:30",
    "pax": { "adult": 2, "child": 1, "senior": 0, "infant": 1 },
    "seats": 3,
    "expires_at": null,
    "order_id": 9001,
    "external_reference": "OTA-99",
    "customer": {
      "name": "Ana",
      "lastname": "Pérez",
      "email": "[email protected]"
    },
    "passengers": [],
    "additional_activities": [
      {
        "id": 12,
        "name": "almuerzo",
        "quantity": 2,
        "amount": 10000,
        "amount_usd": 12
      }
    ],
    "created_at": "2026-08-12T15:30:00+00:00"
  },
  "timestamp": "2026-08-12T15:45:00.000Z"
}

Si el hold ya venció al consultarlo, Vulcano lo marca EXPIRED y la respuesta es 200 con "status": "EXPIRED". Errores frecuentes:

HTTP	Causa
`403`	Reservation de otro partner / sin permiso
`404`	UUID inexistente

Paso 4 — Anular reserva

POST /reservations/cancel Anula un hold o una reserva confirmada. Libera cupos de inmediato. En el calendario del operador la orden queda anulada (declined en los items).

curl -s -X POST "https://api-sandbox.vulcanopro.com/api/v1/reservations/cancel" \
  -H "X-API-KEY: TU_API_KEY" \
  -H "X-API-SECRET: TU_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "11111111-1111-1111-1111-111111111111",
    "reason": "guest cancelled"
  }'

Body

Campo	Tipo	Requerido	Descripción
`id`	uuid	Sí	UUID de la reservation
`reason`	string	No	Motivo (máx. 255)

Estado actual	Resultado
`HOLD`	`CANCELLED`. Libera el hold sin esperar `expires_at`.
`CONFIRMED`	`CANCELLED`. Deja de ocupar cupo.
`CANCELLED`	`200` (idempotente)
`EXPIRED`	`409`

Un confirm posterior a un cancel → 409. Errores frecuentes:

HTTP	Causa
`403`	Reservation de otro partner / sin permiso
`404`	UUID inexistente
`409`	Hold expirado
`422`	`id` inválido

Estados

Estado	Significado
`HOLD`	Cupos bloqueados mientras `expires_at` sea futuro
`EXPIRED`	Hold vencido sin confirmar
`CONFIRMED`	Reserva confirmada en Vulcano (sin pago asociado)
`CANCELLED`	Anulada por el partner (`POST /reservations/cancel`)

Checklist de integración

Partner con reservations:write.
Elegir tour_id + date + time con availability suficiente.
POST /reservations → guardar id y respetar expires_at.
GET /reservations/{id} para consultar estado (HOLD, CONFIRMED, EXPIRED, CANCELLED).
POST /reservations/confirm con id, customer, passengers y, si aplica, additional_activities.
POST /reservations/cancel para anular un hold o una reserva confirmada.
Persistir order_id / external_reference en tu sistema.

Introducción

Autenticación

Referencias

Tours

Reservas

Soporte

Descripción

Flujo recomendado

Paso 1 — Crear reservation (hold)

Body

Respuesta

Paso 2 — Confirmar

Body — campos de primer nivel

`customer`

`passengers[]`

`additional_activities[]`

Paso 3 — Consultar reservation

Path

Respuesta

Paso 4 — Anular reserva

Body

Estados

Checklist de integración

​Descripción

​Flujo recomendado

​Paso 1 — Crear reservation (hold)

​Body

​Respuesta

​Paso 2 — Confirmar

​Body — campos de primer nivel

​customer

​passengers[]

​additional_activities[]

​Paso 3 — Consultar reservation

​Path

​Respuesta

​Paso 4 — Anular reserva

​Body

​Estados

​Checklist de integración

Descripción

Flujo recomendado

Paso 1 — Crear reservation (hold)

Body

Respuesta

Paso 2 — Confirmar

Body — campos de primer nivel

`customer`

`passengers[]`

`additional_activities[]`

Paso 3 — Consultar reservation

Path

Respuesta

Paso 4 — Anular reserva

Body

Estados

Checklist de integración