Struttura e catalogo

Gli endpoint di catalogo sono di sola lettura e descrivono ciò che puoi vendere: la struttura stessa, i suoi tipi di camera, la disponibilità in tempo reale e i piani tariffari che un ospite può prenotare.

GET /property

Restituisce i metadati della struttura a cui è legata la chiave. Può chiamarlo qualsiasi chiave autenticata.

curl "$VRDN_BASE/property" -H "Authorization: Bearer $VRDN_KEY"

{
  "id": "p_8f2a1c",
  "slug": "sunrise-bay",
  "name": "Sunrise Bay Resort",
  "currency": "USD",
  "timezone": "Pacific/Fiji",
  "child_max_age": 12,
  "infant_max_age": 2
}

Campo	Tipo	Note
`id`	string	Identificativo della struttura.
`slug`	string	Slug dell'URL.
`name`	string	Nome visualizzato.
`currency`	string	La valuta base della struttura (ISO 4217).
`timezone`	string	Fuso orario IANA, usato per definire “oggi” nelle finestre tariffarie.
`child_max_age`	integer	Gli ospiti di questa età o più giovani vengono tariffati come bambini.
`infant_max_age`	integer	Gli ospiti di questa età o più giovani vengono tariffati come neonati.

GET /room-types

Ambito: availability:read

Ogni tipo di camera con i suoi dati di presentazione: descrizione, occupazione, dotazioni, configurazioni letto e foto (prima la foto principale).

curl "$VRDN_BASE/room-types" -H "Authorization: Bearer $VRDN_KEY"

{
  "data": [
    {
      "id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "name": "Deluxe Ocean Villa",
      "description": "A private villa over the lagoon.",
      "max_occupancy": 3,
      "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"]
    }
  ]
}

GET /availability

Ambito: availability:read

Il numero minimo di camere disponibili su ogni notte dell'intervallo, per tipo di camera. Vengono restituiti solo i tipi di camera il cui max_occupancy basta per il gruppo.

Parametro di query	Obbligatorio	Note
`check_in`	sì	`YYYY-MM-DD`.
`check_out`	sì	`YYYY-MM-DD`, successivo a `check_in`. I soggiorni sono limitati a 30 notti.
`adults`	sì	Intero ≥ 1.
`children`	no	Intero ≥ 0, predefinito `0`.
`child_ages`	no	Età dei bambini separate da virgole (per esempio `5,7`).

curl "$VRDN_BASE/availability?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",
      "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"]
    }
  ]
}

available è il numero di camere che puoi ancora prenotare. 0 significa esaurito per almeno una notte dell'intervallo.

GET /rates

Ambito: availability:read

Ogni tipo di camera con i suoi piani tariffari visibili e il dettaglio del prezzo per notte sull'intervallo. È l'endpoint che un motore di prenotazione mostra a schermo.

Parametro di query	Obbligatorio	Note
`check_in`	sì	`YYYY-MM-DD`.
`check_out`	sì	`YYYY-MM-DD`, successivo a `check_in`.
`adults`	sì	Intero ≥ 1.
`children`	no	Intero ≥ 0, predefinito `0`.
`child_ages`	no	Età dei bambini separate da virgole (per esempio `5,7`). Quando è presente fa fede sul numero di bambini e determina il prezzo per fascia d'età.
`guest_id`	no	Sblocca le tariffe riservate a un ospite (residente verificato, livello fedeltà).
`promo_code`	no	Sblocca le tariffe protette da un codice promozionale.

La visibilità è applicata lato server

I piani tariffari possono portare delle regole: solo residenti, richiede un codice promozionale, soggiorno minimo, finestra di acquisto anticipato oppure un livello fedeltà. L'API le valuta rispetto al contesto della richiesta e restituisce solo i piani per cui l'ospite è idoneo. Le stesse regole vengono ricontrollate quando crei un blocco, quindi un piano mai mostrato non può essere prenotato per identificativo.

curl "$VRDN_BASE/rates?check_in=2026-08-01&check_out=2026-08-04&adults=2&promo_code=SUMMER" \
  -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,
      "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": [
            { "title": "GST", "amount": "135.00", "is_inclusive": true, "rate": "12", "kind": "percent" }
          ],
          "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" }
          ]
        }
      ]
    }
  ]
}

Ogni tariffa per notte riporta la sua source: interval quando è stato un intervallo stagionale a fissare il prezzo di quel giorno, oppure base_price quando si è tornati al prezzo base del piano.

Il tipo di camera porta base_occupancy (il numero di ospiti inclusi prima che si applichi il prezzo per ospite aggiuntivo) e le sue bed_configs. Ogni piano tariffario riporta un dettaglio completo del prezzo:

Campo	Tipo	Note
`total`	string	Il totale del soggiorno interamente tariffato, comprese le imposte non incluse nel prezzo. Coincide con il totale del blocco.
`room_subtotal`	string	Somma delle tariffe per notte, prima degli aggiustamenti per occupazione e delle imposte.
`base_occupancy`	integer	Ospiti compresi nella tariffa base, oltre i quali si applica il prezzo per ospite aggiuntivo.
`extra_guest_charge`	string	L'addebito per notte del piano per ogni ospite oltre `base_occupancy`.
`single_occupancy_discount`	string	Sconto totale applicato quando il gruppo è composto da un solo occupante.
`extra_guest_total`	string	Supplemento totale per ospiti aggiuntivi sull'intero soggiorno.
`taxes_total`	string	Totale delle imposte non incluse nel prezzo, aggiunte a `total`. Le imposte incluse nel prezzo non vengono conteggiate qui.
`tax_breakdown`	array	Righe per singolo addebito: `title`, `amount`, `is_inclusive`, `rate`, `kind`. Le righe incluse nel prezzo sono mostrate per trasparenza e non si sommano a `total`.

Poiché è lo stesso motore di addebito a tariffare il blocco, questo total coincide sempre con il totale che ricevi da POST /holds.

GET /services

Ambito: availability:read

Extra prenotabili dall'ospite (per esempio un transfer dall'aeroporto) per il passaggio “Aggiungi alla tua camera” di un motore di prenotazione. Restituisce solo i servizi attivi e prenotabili dall'ospite, con i loro modifiers (le opzioni e i campi di raccolta dati che l'ospite compila). Passa ?category= per filtrare per categoria.

Parametro di query	Obbligatorio	Note
`category`	no	Restituisce solo i servizi di questa categoria (per esempio, `transport`).

curl "$VRDN_BASE/services?category=transport" -H "Authorization: Bearer $VRDN_KEY"

{
  "data": [
    {
      "id": "f1c8e5a3-6b2d-4c9f-8a7e-3d0b5c2f6e94",
      "name": "Airport transfer",
      "category": "transport",
      "provider_name": "Harbour Transfers",
      "image_url": "https://cdn.veridien.app/p_8f2a1c/transfer.jpg",
      "short_description": "Private speedboat from the international airport.",
      "currency": "USD",
      "is_taxable": true,
      "modifiers": []
    }
  ]
}

Campo	Tipo	Note
`id`	string	Identificativo del servizio, richiamato come `service_id` negli `add_ons` di un blocco.
`name`	string	Nome visualizzato.
`category`	string \| null	Etichetta di categoria usata dal filtro `?category=`.
`provider_name`	string \| null	Il fornitore che eroga il servizio.
`image_url`	string \| null	Immagine di presentazione.
`short_description`	string \| null	Descrizione di una riga.
`currency`	string	Valuta del prezzo, per impostazione predefinita la valuta base della struttura.
`is_taxable`	boolean	Se all'extra si applicano le imposte.
`modifiers`	array	Le opzioni e i campi di raccolta dati (selezioni con prezzo, campi data/ora e di testo) che l'ospite compila quando lo aggiunge a un blocco.

Collega un servizio scelto a una prenotazione tramite il campo add_ons di POST /holds.

Prenotazioni: trasforma una tariffa in un blocco e in una prenotazione confermata.
Piani tariffari: come si configurano i piani tariffari e gli intervalli stagionali.

Consulta la struttura

Elenca i tipi di camera

Cerca la disponibilità

Cerca le tariffe

Elenca i servizi

Pagine correlate

In questa pagina