Reservas
Una reserva se crea en dos pasos: bloquear el inventario mientras el huésped paga y después confirmar el bloqueo para convertirlo en reserva. Separarlo así hace que el inventario quede retenido en el momento en que el huésped se compromete, y que la reserva solo se cierre cuando el pago sale bien.
El ciclo de vida de una reserva
POST /holds crea una reserva provisional que retiene una habitación durante 15 minutos. POST /holds/{id}/confirm la convierte en una reserva confirmada y registra el pago. Los bloqueos sin confirmar simplemente caducan y liberan su inventario.
POST /holdsÁmbito: reservations:write · admite Idempotency-Key
Crea una reserva provisional que retiene un tipo de habitación con una tarifa para el rango de fechas. Se calcula el precio de la estancia (noches de habitación e impuestos aplicables) en una cuenta nueva. El bloqueo descuenta disponibilidad hasta que se confirma o hasta que vence su ventana de 15 minutos.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
room_type_id | sí | Debe pertenecer a este establecimiento. |
rate_plan_id | sí | Tarifa activa para el tipo de habitación; sus reglas de visibilidad se vuelven a comprobar. |
check_in | sí | YYYY-MM-DD. |
check_out | sí | YYYY-MM-DD, posterior a check_in; máximo 30 noches. |
guest_id | sí | El huésped para el que es el bloqueo. |
adults | sí | Entero 1–20; el grupo debe caber en max_occupancy. |
children | no | Entero 0–20, por defecto 0. |
child_ages | no | Array de edades de los niños (enteros ≥ 0). Cuando está presente manda sobre el número de niños y determina el precio por huésped adicional según el tramo de edad. |
bed_config | no | La configuración de cama elegida por el huésped; debe ser una de las que ofrece el tipo de habitación. Se registra en la reserva para limpieza. |
add_ons | no | Array de extras elegidos por el huésped (hasta 10), cada uno tarificado en la cuenta en el momento del bloqueo para que queden dentro del total cobrado. Consulta los campos más abajo. |
promo_code | no | Obligatorio si la tarifa elegida está protegida por un código promocional. |
Cada entrada de add_ons referencia un servicio reservable por el huésped:
| Campo del extra | Obligatorio | Notas |
|---|---|---|
service_id | sí | El servicio que se añade. |
modifier_values | no | Objeto { modifier_key: value } para los campos de datos del servicio. Por defecto, {}. |
quantity | no | Unidades del extra (entero 1–99). Por defecto, 1. |
curl -X POST "$VRDN_BASE/holds" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d2c9a-8b3e-4a17-9c2f-1e5b7d0a4c83" \
-d '{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
"check_in": "2026-08-01",
"check_out": "2026-08-04",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"adults": 2
}'{
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"hold_expires_at": "2026-06-19T08:45:00.000Z",
"total": "1260.00",
"currency": "USD",
"status": "tentative"
}| Error | Cuándo |
|---|---|
409 no_availability | El tipo de habitación está agotado para el rango. |
404 rate_plan_not_found | La tarifa está inactiva, o sus reglas de visibilidad excluyen a este huésped o a este contexto. |
400 party_too_large | adults + children supera la max_occupancy del tipo de habitación. |
POST /holds/{id}/confirmÁmbito: reservations:write · admite Idempotency-Key
Cobra en tu propio flujo y después confirma el bloqueo con una payment_reference. Veridien vuelve a comprobar la disponibilidad (sin contar el propio bloqueo), marca la reserva y su alojamiento como confirmed, registra el pago en la cuenta y, en las estancias en USD, concede puntos de fidelidad por los ingresos de habitación.
El Método 1 es un modelo de afirmación de confianza: léelo
Este endpoint se basa en la confianza. Tu payment_reference es una afirmación de que has cobrado el dinero: una declaración, nunca una prueba. Veridien no verifica que el pago se haya movido: el comercio registrado es tu hotel, y los fondos, las disputas y los reembolsos son cosa tuya. Por eso:
- Envía una referencia real y única en cada reserva. Nunca reutilices ni modifiques un identificador de pago entre reservas.
- Cada confirmación queda registrada en el registro de auditoría como una afirmación de pago (quién la hizo, la referencia y el importe).
- Las comprobaciones al confirmar rechazan los datos claramente erróneos, pero no pueden validar que el dinero haya cambiado de manos de verdad.
Si quieres que Veridien verifique el pago por su cuenta (cobro alojado en Stripe y verificado por la plataforma), eso es el motor de reservas alojado (Método 2), no esta API.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
payment_reference | sí | Tu identificador de pago: una afirmación sin verificar de que has cobrado. La confirmación es idempotente sobre este valor. |
payment_currency | no | Moneda ISO 4217 opcional que afirmas haber cobrado. Se rechaza si difiere de la moneda de la reserva. |
payment_amount | no | Importe opcional que afirmas haber cobrado. Se rechaza si difiere del total de la cuenta. |
curl -X POST "$VRDN_BASE/holds/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/confirm" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9a2e7c10-4b3f-4d28-8c1f-2e6b8d0a5d94" \
-d '{ "payment_reference": "pay_abc123", "payment_currency": "USD", "payment_amount": 1260.00 }'{
"reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"currency": "USD",
"folio_balance": "0.00",
"already_confirmed": false
}| Error | Cuándo |
|---|---|
409 hold_expired | La ventana de pago de 15 minutos del bloqueo venció antes de que confirmaras. Crea un bloqueo nuevo. |
409 no_availability | El bloqueo perdió su inventario entre el bloqueo y la confirmación. |
409 not_confirmable | La reserva no es un bloqueo provisional confirmable (por ejemplo, ya se canceló). |
400 currency_mismatch | payment_currency difiere de la moneda de la reserva. |
400 amount_mismatch | payment_amount difiere del total de la cuenta. |
Idempotente por partida doble
Volver a confirmar una reserva ya confirmada, o repetir la misma payment_reference, devuelve el resultado confirmado existente con "already_confirmed": true, sin un segundo pago ni una segunda reserva (un índice único (folio, reference) lo hace seguro frente a condiciones de carrera). Junto con una Idempotency-Key, la confirmación se puede reintentar sin riesgo.
La fidelidad se denomina en USD
Los puntos de fidelidad se acumulan sobre los ingresos de habitación en USD. Una estancia en otra moneda no acumula cero en silencio; la acumulación omitida se registra para su conciliación hasta que llegue la acumulación multidivisa.
GET /reservationsÁmbito: reservations:read
Las reservas del establecimiento, ordenadas por fecha de check-in, de la más próxima a la más lejana, cada una con el saldo pendiente de su cuenta.
| Parámetro de consulta | Notas |
|---|---|
guest_id | Filtra por un huésped. |
status | Filtra por estado: tentative, confirmed, checked_in, checked_out, cancelled, no_show. |
limit | Tamaño de página, por defecto 25, máximo 100. |
offset | Registros que saltar. |
curl "$VRDN_BASE/reservations?guest_id=3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34&limit=10" -H "Authorization: Bearer $VRDN_KEY"{
"has_more": false,
"data": [
{
"id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"room_type_name": "Deluxe Ocean Villa",
"nightly_rate": "420.00",
"currency": "USD",
"folio_balance": "0.00",
"balances": []
}
]
}Consulta Convenciones para paginar los resultados.
GET /reservations/{id}Ámbito: reservations:read
Una sola reserva con sus alojamientos (los tramos por habitación de la estancia) y el saldo de su cuenta.
curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27" -H "Authorization: Bearer $VRDN_KEY"{
"id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
"status": "confirmed",
"guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"room_type_name": "Deluxe Ocean Villa",
"nightly_rate": "420.00",
"currency": "USD",
"adults": 2,
"children": 0,
"number_of_guests": 2,
"booking_source": "direct_web",
"special_notes": null,
"folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
"folio_balance": "0.00",
"balances": [{ "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }],
"accommodations": [
{
"id": "2b9e6f4d-8a3c-4e1b-9d5f-7a0c4e8b2d63",
"room_id": null,
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"check_in_date": "2026-08-01",
"check_out_date": "2026-08-04",
"status": "confirmed",
"nightly_rate": "420.00"
}
]
}POST /reservations/{id}/cancelÁmbito: reservations:write
Cancela una reserva tentative o confirmed y libera su inventario. Las reservas que ya han hecho el check-in, el check-out o que ya están canceladas no se pueden cancelar por la API (409 not_cancellable). La cuenta y las facturas que hubiera se anulan (se conservan para auditoría) y, si la reserva estaba pagada, se emite un reembolso según la política antes de liberar el inventario.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
reason | no | Se guarda como el motivo de la cancelación. |
curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/cancel" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "Guest changed plans" }'{ "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27", "status": "cancelled", "refund_minor": 0, "refund_provider": null }| Campo | Tipo | Notas |
|---|---|---|
refund_minor | integer | Importe reembolsado, en unidades menores (céntimos). 0 cuando la reserva no estaba pagada o la política no reembolsa nada. |
refund_provider | string | null | El proveedor que procesó el reembolso, o null si no se emitió ninguno. |
- Cuentas: leer la cuenta y anotar cargos.
- Huéspedes y fidelidad: el huésped al que pertenece una reserva.