Gestione delle tariffe
Gli endpoint di catalogo e di offerta sono di sola lettura. Questi endpoint permettono a un'integrazione di gestire l'impianto tariffario: creare piani tariffari, sovrapporre prezzi stagionali, raggruppare inclusioni e crediti e lanciare promozioni con codici. Sono il modo in cui un hotel guida i propri prezzi Veridien dal proprio sito o dal proprio back office.
Ogni endpoint di questa pagina richiede l'ambito rates:write, tranne le letture di gestione (GET), che richiedono rates:read.
Una promozione è un piano tariffario
Una promozione è un piano tariffario con kind: "promotion" e una derivazione da un
piano base. Non esiste un endpoint separato per le promozioni: la crei e la modifichi con
gli stessi endpoint /rate-plans, impostando kind, derived_from_id, derivation_type
e derivation_value.
Idempotenza
Ogni scrittura qui è una richiesta che modifica i dati. Invia un'intestazione Idempotency-Key
per rendere sicuri i nuovi tentativi, come descritto in Convenzioni.
POST /rate-plans| Campo | Obbligatorio | Note |
|---|---|---|
room_type_id | sì | Il tipo di camera che questo piano tariffa. |
name | sì | Nome interno (da 1 a 100 caratteri). |
base_price | sì | Prezzo per notte come stringa decimale, per esempio "120.00". |
currency | no | Deve essere la valuta base della struttura o una valuta configurata. Per impostazione predefinita è quella base. |
public_name | no | Nome mostrato all'ospite. |
description | no | Testo di presentazione per l'ospite. |
image_url | no | URL assoluto. |
extra_guest_charge | no | Addebito per notte per ogni ospite oltre l'occupazione base. Predefinito "0.00". |
single_guest_discount | no | Predefinito "0.00". |
single_guest_discount_type | no | fixed o percent. Predefinito fixed. |
min_los / max_los | no | Limiti di durata del soggiorno in notti. |
booking_window_start / _end | no | Quando il piano può essere prenotato (YYYY-MM-DD). |
stay_window_start / _end | no | Quando il piano può essere usato per il soggiorno. |
active_for_booking_engine | no | Predefinito false. |
active_for_channels | no | Predefinito false. |
kind | no | standard (predefinito) o promotion. |
derived_from_id | no | Per una promozione: il piano base da cui deriva. |
derivation_type | no | percent, fixed o perPerson. Obbligatorio insieme a derived_from_id. |
derivation_value | no | Stringa decimale con segno. Un valore negativo è uno sconto, per esempio "-20.00". Obbligatorio insieme a derived_from_id. |
curl -X POST "$VRDN_BASE/rate-plans" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"name": "Bed & Breakfast",
"base_price": "120.00",
"public_name": "Bed & Breakfast",
"description": "A full breakfast for two each morning.",
"active_for_booking_engine": true
}'{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02" }Imposta kind, il piano padre e una derivazione negativa. Proteggila con un codice aggiungendone uno (vedi più sotto) e impostando requires_promo_code: true.
curl -X POST "$VRDN_BASE/rate-plans" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{
"room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
"name": "Advance Purchase, save 20%",
"base_price": "120.00",
"kind": "promotion",
"derived_from_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
"derivation_type": "percent",
"derivation_value": "-20.00",
"active_for_booking_engine": true
}'Un piano derivato richiede sia derivation_type sia derivation_value, altrimenti la richiesta viene rifiutata. Il suo prezzo è sempre il prezzo corrente del piano padre con la derivazione applicata, quindi segue automaticamente i prezzi stagionali del padre.
PATCH /rate-plans/{id}Invia solo i campi che vuoi cambiare. Accetta gli stessi campi della creazione (tranne room_type_id), più is_active.
{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "updated": true }DELETE /rate-plans/{id}Il piano tariffario predefinito non può essere eliminato (403). Le prenotazioni già effettuate su un piano eliminato mantengono il prezzo che era stato loro quotato.
{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "deleted": true }Gli intervalli sovrappongono al prezzo base di un piano dei prezzi e delle regole di soggiorno legati alle date. Gli intervalli sullo stesso piano non devono sovrapporsi, e un intervallo che si sovrappone restituisce 409.
GET /rate-plans/{id}/intervalsRichiede rates:read.
POST /rate-plans/{id}/intervals| Campo | Obbligatorio | Note |
|---|---|---|
name | sì | Per esempio “Alta stagione”. |
start_date / end_date | sì | YYYY-MM-DD. L'inizio deve precedere la fine. |
price_mon … price_sun | no | Prezzo per giorno della settimana. Un giorno lasciato vuoto ricade sul prezzo base. |
min_stay / max_stay | no | Regole di durata del soggiorno per questo intervallo. |
closed_to_arrival / closed_to_departure / stop_sell | no | Indicatori di disponibilità. Predefinito false. |
extra_guest_charge / single_guest_discount | no | Valori specifici della stagione. Predefinito "0.00". |
curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/intervals" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "High Season",
"start_date": "2026-12-01",
"end_date": "2027-03-31",
"price_mon": "180.00", "price_fri": "210.00",
"min_stay": 3
}'{ "interval_id": "d8a4c2f6-5e9b-4d7a-8f1c-3b6e0a9d5c28" }PATCH /intervals/{id}
DELETE /intervals/{id}PATCH accetta qualsiasi campo dell'intervallo e ricontrolla la regola di non sovrapposizione.
Un'inclusione è un beneficio (una voce inclusa fissa) o un credito (un importo spendibile su una categoria, per esempio un credito spa). Le inclusioni si impostano come elenco completo: un POST sostituisce l'intero insieme di inclusioni del piano.
GET /rate-plans/{id}/inclusionsRichiede rates:read.
POST /rate-plans/{id}/inclusions| Campo | Obbligatorio | Note |
|---|---|---|
label | sì | Etichetta mostrata all'ospite, per esempio “Credito spa”. |
allocated_amount | sì | Valore come stringa decimale. "0.00" per un beneficio gratuito. |
frequency | sì | perStay, perNight, perGuest o perGuestPerNight. |
inclusion_kind | no | perk (predefinito) o credit. |
revenue_category | sì | room, fnb, spa, excursions, activities o other. Per un credito è la categoria a cui si applica. |
service_item_id | no | Collegamento a una voce di servizio del catalogo. |
currency | no | Per impostazione predefinita, la valuta del piano. |
included_quantity | no | Predefinito 1. |
curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/inclusions" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{
"inclusions": [
{ "label": "Daily breakfast for two", "allocated_amount": "20.00", "frequency": "perGuestPerNight", "revenue_category": "fnb" },
{ "label": "Spa credit", "allocated_amount": "150.00", "frequency": "perStay", "inclusion_kind": "credit", "revenue_category": "spa" }
]
}'{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "count": 2 }Un codice sblocca una promozione. Lo sconto sta nella promozione, quindi un codice non porta mai un risparmio proprio. Collega i codici al piano che sbloccano.
GET /rate-plans/{id}/promo-codesRichiede rates:read.
POST /rate-plans/{id}/promo-codes| Campo | Obbligatorio | Note |
|---|---|---|
code | sì | Da 3 a 40 caratteri. Salvato e confrontato in maiuscolo. |
valid_from / valid_to | no | Finestra YYYY-MM-DD. |
max_redemptions | no | Limite di utilizzi totali. Omettilo per un numero illimitato. |
max_per_guest | no | Limite per ospite. |
curl -X POST "$VRDN_BASE/rate-plans/e2a9d7c4-3f6b-4c1e-9a8d-7b5f0c2e4a19/promo-codes" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "EARLYBIRD25", "max_redemptions": 100 }'{ "promo_code_id": "a5e2c8f1-7d4b-4a6e-b9c3-0f8d2a5e7c41", "code": "EARLYBIRD25" }PATCH /promo-codes/{id}
DELETE /promo-codes/{id}PATCH accetta valid_from, valid_to, max_redemptions, max_per_guest e is_active. La stringa del codice non può essere modificata, perché le prenotazioni congelano il codice con cui sono state fatte, quindi eliminalo e creane uno nuovo. Eliminare un codice non ha effetto sulle prenotazioni già effettuate con esso.