API di prenotazione: ricevere prenotazioni sul proprio sito web
Una piccola API JSON sicura per il campeggio: leggere tipi di piazzola, extra, disponibilità e prezzi, e creare prenotazioni. Tutto il resto si gestisce nel pannello di controllo di Campiamo.
Ultimo aggiornamento: 9 novembre 2026
L'API di prenotazione permette al proprio sito web di inserire prenotazioni in Campiamo. Fa due cose: indica cosa si può prenotare (tipi di piazzola, extra, disponibilità e prezzi) e crea prenotazioni. Modifiche, cancellazioni, incasso dei saldi e check-in degli ospiti avvengono tutti nel pannello di controllo di Campiamo, come per ogni altra prenotazione.
L'API di prenotazione fa parte del piano Growth e superiori.
Se serve soltanto un modulo di prenotazione sul proprio sito web, l'API non è necessaria: il widget di prenotazione lo fa con una sola riga di codice. L'API è pensata per chi vuole costruire da sé il modulo di prenotazione.
Prima di iniziare
- Nel pannello di controllo andare su Impostazioni → API.
- Scegliere Crea chiave, assegnarle un nome riconoscibile ("Sito web", "Modulo di prenotazione") e confermare con la propria password.
- Copiare la chiave. Viene mostrata una sola volta. Ne conserviamo soltanto un'impronta, quindi nessuno, noi compresi, può mostrarla di nuovo. Se va persa, revocarla e crearne un'altra.
Una chiave appartiene a un solo campeggio. Se ne possono avere fino a cinque, e ciascuna può essere revocata in qualsiasi momento; una chiave revocata smette subito di funzionare.
Tenere la chiave sul proprio server
La chiave è una password per creare prenotazioni nel campeggio. Va trattata come tale:
- Chiamare l'API solo dal proprio server, mai da JavaScript in una pagina web o da un'app mobile, dove chiunque può leggerla. L'API rifiuta le chiamate provenienti dai browser su altri siti.
- Non inserirla in un indirizzo web, in un'email o in un repository di codice pubblico.
- Se si conosce l'indirizzo da cui chiama il proprio server, vincolare la chiave a quell'indirizzo in Indirizzi IP consentiti.
- Se si sospetta che una chiave sia trapelata, revocarla. Arriva un'email ogni volta che una chiave viene creata o revocata nell'account.
Effettuare una richiesta
L'indirizzo di base è:
https://campiamo.com/api/v1
Inviare la chiave nell'intestazione Authorization a ogni richiesta, tramite HTTPS:
curl https://campiamo.com/api/v1/campsite \
-H "Authorization: Bearer cmp_live_YOUR_KEY" \
-H "Accept: application/json"
Richieste e risposte sono in JSON. Le date sono nel formato YYYY-MM-DD, e check_out è la mattina in cui l'ospite parte. I prezzi sono numeri nella valuta del campeggio.
Cosa si può prenotare
Il campeggio
GET /campsite restituisce ciò che un modulo di prenotazione deve sapere sul campeggio.
{
"name": "Meadow Fields Campsite",
"currency": "GBP",
"timezone": "Europe/London",
"language": "en",
"check_in_time": "14:00",
"check_out_time": "11:00",
"open_season": "1 March to 31 October",
"guest_fields": { "phone_required": false },
"age_bands": { "enabled": true, "child_min": 2, "child_max": 15, "adult_from": 16, "infants": true, "infant_under": 2, "infants_take_space": false },
"booking_questions": [],
"club_memberships": [],
"discount_codes": false,
"gift_vouchers": false,
"payment": {
"online_payment": true,
"provider": "Stripe",
"terms": "A deposit of 25% is paid at checkout; the balance is due 14 days before arrival."
}
}
booking_questions sono i campi di prenotazione personalizzati. Le risposte vanno rimandate in answers quando si crea una prenotazione, usando come chiave l'id di ciascuna domanda.
Tipi di piazzola
GET /pitch-types elenca i tipi di piazzola e le sistemazioni che gli ospiti possono prenotare.
{
"pitch_types": [
{
"id": "01kwz3mjx2abcdef0123456789",
"name": "Grass pitch with electric",
"type": "pitch",
"description": "Level grass pitches with a 16A hook-up.",
"photos": ["https://campiamo.com/img/01kx.../1280"],
"base_price": 28.0,
"pricing": "per_night",
"included_adults": 2,
"included_children": 0,
"extra_adult_price": 5.0,
"extra_child_price": 3.0,
"max_persons": 6,
"adults_only": false,
"dogs_allowed": true,
"max_dogs": 2,
"extra_dog_price": 2.0,
"min_nights": 1,
"max_nights": null,
"units": 12
}
]
}
base_price è il prezzo di partenza. Stagioni, soggiorni minimi e composizione del gruppo modificano il costo di un soggiorno, quindi il prezzo per date reali va sempre preso dalla disponibilità o da un preventivo.
Extra
GET /extras elenca gli extra che un ospite può aggiungere. pitch_type_ids è vuoto quando un extra è offerto con ogni tipo di piazzola.
{
"extras": [
{
"id": "01kx0a...",
"name": "Firewood bundle",
"description": "A net of seasoned logs.",
"price": 8.0,
"child_price": null,
"price_type": "fixed",
"max_quantity": 5,
"choice_label": null,
"choices": [],
"pitch_type_ids": []
}
]
}
Disponibilità
GET /availability risponde alla domanda "cosa è libero per queste date e questo gruppo, e quanto costa?"
| Parametro | ||
|---|---|---|
check_in |
obbligatorio | Data di arrivo |
check_out |
obbligatorio | Data di partenza |
adults |
facoltativo | Predefinito 2 |
children |
facoltativo | Predefinito 0 |
infants |
facoltativo | Predefinito 0 |
dogs |
facoltativo | Predefinito 0 |
curl "https://campiamo.com/api/v1/availability?check_in=2027-06-12&check_out=2027-06-15&adults=2&children=1" \
-H "Authorization: Bearer cmp_live_YOUR_KEY"
{
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"nights": 3,
"party": { "adults": 2, "children": 1, "infants": 0, "dogs": 0 },
"currency": "GBP",
"available": [
{
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"name": "Grass pitch with electric",
"units_free": 4,
"max_persons": 6,
"dogs_allowed": true,
"total_price": 93.0,
"due_now": 23.25
}
],
"unavailable": [
{ "pitch_type_id": "01kwz3mjx9...", "name": "Bell tent", "reason": "minimum_stay", "detail": "minimum stay 4 nights for those dates" }
]
}
due_now è ciò che l'ospite pagherebbe al momento del pagamento in base alle regole sull'acconto. Il reason di un tipo di piazzola non disponibile è uno tra closed, adults_only, too_many_people, no_dogs, too_many_dogs, maximum_stay, not_offered, minimum_stay, fully_booked o no_price.
Un preventivo
POST /quotes calcola il prezzo di un tipo di piazzola con extra e codici, senza prenotare nulla. Accetta gli stessi campi relativi al soggiorno di una prenotazione.
curl https://campiamo.com/api/v1/quotes \
-H "Authorization: Bearer cmp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"adults": 2,
"children": 1,
"extras": [{ "extra_id": "01kx0a...", "quantity": 2 }]
}'
{
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"name": "Grass pitch with electric",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"nights": 3,
"party": { "adults": 2, "children": 1, "infants": 0, "dogs": 0 },
"currency": "GBP",
"accommodation_total": 84.0,
"guest_extras": [{ "name": "Extra child", "total": 9.0 }],
"extras": [{ "extra_id": "01kx0a...", "name": "Firewood bundle", "quantity": 2, "choice": null, "total": 16.0 }],
"club_membership": null,
"tourist_tax": null,
"discount": null,
"voucher": null,
"total": 109.0,
"due_now": 27.25
}
guest_extras sono i supplementi per le persone o i cani oltre a quelli inclusi nel prezzo della piazzola. tourist_tax viene compilato quando il campeggio riscuote un'imposta di soggiorno; quando viene riscossa con la prenotazione è già compresa in total.
Creare una prenotazione
POST /bookings crea una prenotazione. Viene verificata con le stesse regole del widget di prenotazione: stagione, disponibilità, soggiorni minimi, composizione del gruppo, cani, domande obbligatorie ed extra. Se un ospite non potrebbe effettuare la prenotazione sulla pagina di prenotazione, non la effettuerà nemmeno l'API.
| Campo | ||
|---|---|---|
pitch_type_id |
obbligatorio | Dai tipi di piazzola o dalla disponibilità |
check_in, check_out |
obbligatorio | Oggi o una data successiva |
adults |
obbligatorio | Almeno 1 |
children, infants, dogs |
facoltativo | Predefinito 0 |
child_ages |
obbligatorio se ci sono bambini | Un'età per bambino, ad es. [4, 9] |
guest.name, guest.email |
obbligatorio | |
guest.phone |
facoltativo | Obbligatorio se il campeggio richiede un numero di telefono |
guest.address |
facoltativo | line_1, line_2, city, county, postcode |
extras |
facoltativo | [{ "extra_id": "...", "quantity": 1, "choice": "..." }] |
answers |
facoltativo | Risposte alle domande di prenotazione, con l'id della domanda come chiave |
discount_code, voucher_code |
facoltativo | |
notes |
facoltativo | Fino a 1.000 caratteri |
payment |
obbligatorio | checkout oppure on_arrival, vedere più sotto |
send_guest_emails |
facoltativo | Solo con on_arrival. Predefinito true |
price |
facoltativo | Solo con on_arrival. Il proprio totale per questa prenotazione, al posto di quello calcolato |
L'ospite paga online: "payment": "checkout"
Da usare quando un ospite prenota sul proprio sito web. Si riceve in risposta un link a una pagina di pagamento sicura ospitata dal fornitore di pagamenti. Indirizzarvi il browser dell'ospite.
curl https://campiamo.com/api/v1/bookings \
-H "Authorization: Bearer cmp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7f1c2c0e-2f0b-4c59-9a3b-6f0d1f5b8a11" \
-d '{
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"adults": 2,
"children": 1,
"child_ages": [9],
"guest": { "name": "Sam Carter", "email": "sam@example.com", "phone": "07700 900123" },
"payment": "checkout"
}'
{
"status": "payment_required",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
"expires_at": "2026-11-10T10:42:00+00:00",
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"nights": 3,
"currency": "GBP",
"total": 93.0,
"due_now": 23.25
}
La prenotazione viene creata quando l'ospite paga. La piazzola resta riservata mentre l'ospite è sulla pagina di pagamento. Una volta effettuato il pagamento, la prenotazione compare nel pannello di controllo, l'ospite arriva su una pagina di conferma e riceve l'email di conferma con il riferimento della prenotazione. Se se ne va senza pagare, non viene prenotato nulla e la piazzola viene liberata.
Per questo il campeggio deve accettare pagamenti online (collegare Stripe o PayPal). Se al momento del pagamento non è dovuto nulla, per esempio perché un buono regalo copre l'importo, la prenotazione viene confermata subito e la risposta è quella confirmed riportata più sotto, con un confirmation_url per l'ospite.
Nessun pagamento online: "payment": "on_arrival"
Da usare per una prenotazione che non richiede una pagina di pagamento: un ospite che pagherà all'arrivo, o una prenotazione presa per telefono. La prenotazione viene confermata immediatamente.
curl https://campiamo.com/api/v1/bookings \
-H "Authorization: Bearer cmp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: phone-2027-0142" \
-d '{
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"adults": 2,
"guest": { "name": "Sam Carter", "email": "sam@example.com" },
"payment": "on_arrival",
"send_guest_emails": false,
"price": 80
}'
{
"status": "confirmed",
"booking": {
"reference": "BK-7QK2MD",
"pitch_type_id": "01kwz3mjx2abcdef0123456789",
"pitch_type": "Grass pitch with electric",
"check_in": "2027-06-12",
"check_out": "2027-06-15",
"nights": 3,
"adults": 2,
"children": 0,
"infants": 0,
"dogs": 0,
"currency": "GBP",
"total": 80.0,
"payment_status": "pay_on_arrival"
},
"dashboard_url": "https://campiamo.com/dashboard/bookings/01m7..."
}
- Lasciando attivo
send_guest_emails, l'ospite riceve la consueta email di conferma. Va disattivato quando l'ospite è già al corrente della prenotazione. L'avviso di nuova prenotazione al campeggio arriva in ogni caso. priceimposta un prezzo proprio per il soggiorno, come la casella del prezzo personalizzato in una prenotazione creata dal pannello di controllo. Un'imposta di soggiorno riscossa con la prenotazione viene aggiunta in più. Omettendoprice, è Campiamo a calcolare il prezzo.- Quanto pagato dall'ospite va registrato dalla pagina della prenotazione nel pannello di controllo.
Inviare ogni prenotazione una sola volta
Le reti possono non funzionare. Se non arriva una risposta, non si può sapere se la prenotazione è stata creata. Inviare un'intestazione Idempotency-Key con ogni POST /bookings: un qualsiasi testo univoco di propria scelta, come il numero d'ordine. Ripetendo una richiesta con la stessa chiave e lo stesso contenuto si riceve la risposta originale e non viene creata una seconda prenotazione.
Quando qualcosa non va
Gli errori vengono restituiti in JSON con il corrispondente stato HTTP. code è stabile e può essere usato nei controlli; message è destinato alle persone.
{
"error": { "code": "validation_failed", "message": "The booking could not be made." },
"errors": { "check_out": ["This accommodation requires a minimum stay of 2 nights for the selected dates."] }
}
| Stato | code |
Cosa significa |
|---|---|---|
| 401 | invalid_key |
La chiave manca, è errata o è stata revocata |
| 403 | browser_request |
La chiamata proviene da una pagina web. Chiamare l'API dal proprio server |
| 403 | key_in_url |
La chiave è stata inviata nell'indirizzo web. Inviarla nell'intestazione e revocare quella chiave |
| 403 | ip_not_allowed |
La chiamata proviene da un indirizzo a cui la chiave non è vincolata |
| 403 | plan_required |
Il piano non include più l'API |
| 403 | api_disabled |
L'API è disattivata per l'account. Contattare l'assistenza |
| 404 | not_found |
L'indirizzo non esiste, oppure l'id non appartiene al campeggio |
| 409 | request_in_progress |
Una richiesta con questa Idempotency-Key è ancora in corso |
| 422 | validation_failed |
Un campo manca o non è consentito. errors indica quale |
| 422 | not_available |
Il tipo di piazzola non può essere prenotato per quelle date |
| 422 | online_payment_unavailable |
È stato richiesto checkout ma il campeggio non accetta pagamenti online |
| 422 | booking_refused |
La prenotazione non può essere accettata online. Gestirla dal pannello di controllo |
| 422 | idempotency_key_reused |
La Idempotency-Key è già stata usata per una richiesta diversa |
| 429 | rate_limited |
Troppe richieste. Retry-After indica quanto attendere |
| 503 | bookings_paused |
Le prenotazioni sono brevemente sospese per manutenzione. Riprovare a breve |
| 503 | api_disabled |
L'API è disattivata per tutti per un breve periodo. Riprovare più tardi |
Limiti
- 120 richieste al minuto per chiave per le consultazioni.
- 30 prenotazioni all'ora e 200 al giorno per chiave.
Se una chiave raggiunge il limite giornaliero di prenotazioni inviamo un'email, perché di solito significa che uno script non funziona correttamente o che una chiave è trapelata. Se c'è una reale necessità di limiti più alti, basta comunicarcelo.
Cosa non fa l'API
Per scelta progettuale, l'API non può leggere, modificare o annullare le prenotazioni esistenti, leggere l'elenco degli ospiti, registrare pagamenti o vedere i dati di registrazione dei viaggiatori. In questo modo le informazioni degli ospiti restano fuori dalla portata di una chiave trapelata, e un solo posto, il pannello di controllo, resta il registro di ogni prenotazione.
Ha ancora dubbi?
Se questa pagina non ha risposto alla sua domanda, è la nostra pagina a dover essere corretta. Ce lo faccia sapere.
Contattaci