Démarrage rapide
Ce parcours guidé déroule tout le cycle de vie d'une réservation sur l'API en production, exactement le chemin que suit un moteur de réservation sur mesure ou une application client. À la fin, vous aurez cherché des disponibilités, tarifé un séjour, enregistré un client, bloqué une chambre, confirmé une réservation payée, lu la note et cumulé des points de fidélité.
Ce qu'il vous faut
Une clé d'API (voyez Authentification) avec ces portées : availability:read, guests:write, reservations:write, folio:write et loyalty:read. Définissez-la une fois pour votre terminal :
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"
}Trouvez les types de chambres réservables pour ces dates et ce nombre de personnes.
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 renvoie les tarifs visibles de chaque type de chambre avec un détail par nuit. Les règles de visibilité des tarifs (réservés aux résidents locaux, soumis à un code promo, liés à un niveau de fidélité) sont appliquées côté serveur ; passez guest_id ou promo_code pour débloquer les tarifs restreints.
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" }
]
}
]
}
]
}Une réservation appartient à un client. POST /guests retrouve un client existant par son e-mail ou en crée un. L'appel est idempotent sur l'e-mail, vous pouvez donc l'émettre sans risque à chaque réservation.
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 }Créez un blocage temporaire. Il retient les disponibilités pendant 15 minutes en créant une réservation provisoire, tarife le séjour (nuitées et taxes passées sur une note) et renvoie un reservation_id à confirmer.
Utilisez un en-tête Idempotency-Key
Envoyez toujours un Idempotency-Key sur les blocages et les confirmations, pour qu'une nouvelle tentative réseau ne crée jamais de doublon. Voyez Conventions.
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"
}Encaissez le paiement dans votre propre parcours, puis confirmez le blocage avec un payment_reference. Veridien passe la réservation en confirmed, enregistre le paiement sur la note et (pour les séjours en USD) attribue des points de fidélité.
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 confirmation est idempotente : rejouer le même payment_reference renvoie "already_confirmed": true sans facturer une deuxième fois.
Ajoutez ce que vous voulez sur la note du client pendant le séjour : un soin au spa, une commande au restaurant, un article de 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"Voilà la boucle complète. À partir de là, explorez les références de chaque ressource pour tous les champs et toutes les options :
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. Enregistrer le client
const { guest_id } = await api("/guests", {
method: "POST",
body: JSON.stringify({ email: "[email protected]", first_name: "Ada", last_name: "Lovelace" }),
});
// 2. Bloquer une chambre
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. Confirmer après paiement
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"