Inicio rápido
Este recorrido ejecuta el ciclo de vida completo de una reserva contra la API en vivo, el mismo camino que sigue un motor de reservas a medida o una app para huéspedes. Al terminar habrás buscado disponibilidad, calculado el precio de una estancia, registrado un huésped, bloqueado una habitación, confirmado una reserva pagada, leído la cuenta y acumulado puntos de fidelidad.
Lo que necesitas
Una clave de API (consulta Autenticación) con estos ámbitos: availability:read, guests:write, reservations:write, folio:write y loyalty:read. Configúrala una sola vez en la shell:
export VRDN_KEY="vrdn_live_xxxxxxxxxxxxxxxxxxxx"
export VRDN_BASE="https://veridien.app/api/v1"curl "$VRDN_BASE/me" -H "Authorization: Bearer $VRDN_KEY"{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "guests:write", "reservations:write", "folio:write", "loyalty:read"],
"request_id": "req_a1b2c3d4e5"
}Averigua qué tipos de habitación se pueden reservar para esas fechas y ese número de personas.
curl "$VRDN_BASE/availability?check_in=2026-08-01&check_out=2026-08-04&adults=2&children=0" \
-H "Authorization: Bearer $VRDN_KEY"{
"check_in": "2026-08-01",
"check_out": "2026-08-04",
"data": [
{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"name": "Deluxe Ocean Villa",
"description": "A private villa over the lagoon.",
"max_occupancy": 3,
"available": 4,
"currency": "USD",
"amenities": ["Ocean view", "Private deck"],
"bed_configs": [{ "id": "bc_king", "label": "1 King" }],
"photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"]
}
]
}/rates devuelve las tarifas visibles de cada tipo de habitación con el desglose por noche. Las reglas de visibilidad de las tarifas (solo residentes locales, sujetas a código promocional, por nivel de fidelidad) se aplican en el servidor; pasa guest_id o promo_code para desbloquear las tarifas restringidas.
curl "$VRDN_BASE/rates?check_in=2026-08-01&check_out=2026-08-04&adults=2" \
-H "Authorization: Bearer $VRDN_KEY"{
"check_in": "2026-08-01",
"check_out": "2026-08-04",
"data": [
{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"name": "Deluxe Ocean Villa",
"max_occupancy": 3,
"base_occupancy": 2,
"amenities": ["Ocean view", "Private deck"],
"bed_configs": [{ "id": "bc_king", "label": "1 King" }],
"photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"],
"rate_plans": [
{
"rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
"name": "Flexible",
"currency": "USD",
"total": "1260.00",
"room_subtotal": "1260.00",
"base_occupancy": 2,
"extra_guest_charge": "0.00",
"single_occupancy_discount": "0.00",
"extra_guest_total": "0.00",
"taxes_total": "0.00",
"tax_breakdown": [],
"nightly_rates": [
{ "date": "2026-08-01", "day_of_week": 6, "rate": "420.00", "source": "base_price" },
{ "date": "2026-08-02", "day_of_week": 0, "rate": "420.00", "source": "base_price" },
{ "date": "2026-08-03", "day_of_week": 1, "rate": "420.00", "source": "base_price" }
]
}
]
}
]
}Las reservas pertenecen a un huésped. POST /guests busca un huésped existente por correo o crea uno. Es idempotente sobre el correo, así que puedes llamarlo con total seguridad en cada compra.
curl -X POST "$VRDN_BASE/guests" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "first_name": "Ada", "last_name": "Lovelace", "nationality": "GB" }'{ "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34", "created": true }Crea un bloqueo temporal. Reserva inventario durante 15 minutos creando una reserva provisional, calcula el precio de la estancia (noches de habitación e impuestos anotados en una cuenta) y devuelve un reservation_id para confirmar.
Usa una Idempotency-Key
Envía siempre una Idempotency-Key en los bloqueos y las confirmaciones para que un reintento de red no cree nunca un duplicado. Consulta Convenciones.
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"
}Cobra en tu propio flujo y después confirma el bloqueo con una payment_reference. Veridien marca la reserva como confirmed, registra el pago en la cuenta y (en las estancias en USD) concede puntos de fidelidad.
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" }'{
"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
}La confirmación es idempotente: repetir la misma payment_reference devuelve "already_confirmed": true sin volver a cobrar.
Añade cualquier cosa a la cuenta del huésped durante la estancia: un tratamiento de spa, una comanda de restaurante, un producto del minibar.
curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio/charges" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "description": "Spa treatment", "amount": "120.00", "category": "service" }'{ "line_item_id": "6d4f8b2a-9c1e-4f7d-b8a3-2e5c9f0a1d74", "folio_balance": "120.00", "balances": [{ "currency": "USD", "balance": "120.00" }] }curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio" -H "Authorization: Bearer $VRDN_KEY"
curl "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34/loyalty" -H "Authorization: Bearer $VRDN_KEY"Ese es el ciclo completo. A partir de aquí, explora las referencias de cada recurso para ver todos sus campos y opciones:
const BASE = "https://veridien.app/api/v1";
const headers = {
Authorization: `Bearer ${process.env.VRDN_KEY}`,
"Content-Type": "application/json",
};
async function api(path: string, init?: RequestInit) {
const res = await fetch(`${BASE}${path}`, { ...init, headers: { ...headers, ...init?.headers } });
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
return body;
}
// 1. Registra al huésped
const { guest_id } = await api("/guests", {
method: "POST",
body: JSON.stringify({ email: "[email protected]", first_name: "Ada", last_name: "Lovelace" }),
});
// 2. Bloquea una habitación
const hold = await api("/holds", {
method: "POST",
headers: { "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({
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,
adults: 2,
}),
});
// 3. Confirma después del pago
const reservation = await api(`/holds/${hold.reservation_id}/confirm`, {
method: "POST",
headers: { "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({ payment_reference: "pay_abc123" }),
});
console.log(reservation.status); // "confirmed"