Riferimento API

L’API CampOne consente di collegare sistemi esterni — channel manager, software contabile, strumenti di marketing o soluzioni interne — direttamente al Suo campeggio. L’API riflette il modello dati visibile nella dashboard admin: ciò che gestisce dall’interfaccia, può anche automatizzarlo.

Il riferimento pubblico completo è attualmente in beta privata e viene aperto ai partner di integrazione su richiesta. Le sezioni seguenti descrivono architettura, modello di autenticazione e schemi di integrazione già supportati, così da pianificare un’integrazione prima della pubblicazione del riferimento pubblico.

Architettura

L’API CampOne è un’API REST su HTTPS con body JSON in richiesta e risposta. Gli endpoint sono versionati nell’URL (/api/v1/…) e tutti i timestamp sono in ISO 8601 UTC. L’API è multi-tenant; ogni richiesta è limitata a un singolo tenant identificato da token API o token OAuth.

Gli endpoint pubblici sono su https://api.campone.ch. Una sandbox distinta è disponibile su https://sandbox.api.campone.ch con un set di dati isolato per sviluppare senza toccare la produzione.

Autenticazione

Sono supportati due modelli:

Modello	Caso d’uso
Token di accesso personale	Script interni, export contabili, integrazioni mono-tenant
OAuth 2.0 (authorisation code)	Applicazioni terze che agiscono per più tenant

I token di accesso personali si generano in Impostazioni → API → Token con durata configurabile (1–365 giorni). Ogni token porta uno scope che restringe dati e azioni accessibili — es. sola lettura per un export contabile, scrittura completa per uno strumento di dispatch interno.

OAuth 2.0 è la scelta standard per i prodotti partner: l’applicazione è registrata presso CampOne, il tenant approva tramite una schermata di consenso familiare, il partner riceve token di accesso a vita breve più token di refresh.

Scopes

Il sistema segue il principio del minimo privilegio:

bookings:read / bookings:write
guests:read / guests:write
invoices:read / invoices:write
pitches:read / pitches:write
analytics:read
compliance:read (export HESTA, audit trail)

Un token può combinare liberamente scope; gli scope mancanti danno 403 Forbidden.

Limiti di richiesta

Limiti per tenant:

600 richieste/minuto per gli endpoint in lettura
120 richieste/minuto per gli endpoint in scrittura
30 richieste/minuto per gli endpoint analytics (per le aggregazioni)

Ogni risposta porta gli header X-RateLimit-Remaining e X-RateLimit-Reset per ritmare le richieste. Oltre, 429 Too Many Requests con Retry-After.

Webhook

Molte integrazioni non hanno bisogno di fare polling — si abbonano ai webhook. CampOne emette webhook ai cambi di stato chiave:

booking.created, booking.updated, booking.cancelled
invoice.issued, invoice.paid
guest.created, guest.updated, guest.deleted
payment.received, payment.refunded
availability.changed (usato dai channel manager)

I payload webhook sono firmati HMAC-SHA256 nell’header CampOne-Signature, permettendo ai destinatari di verificare origine e integrità. Le consegne fallite sono ritentate in backoff esponenziale fino a 24 ore.

Integrazioni esistenti

Le seguenti integrazioni sono in produzione sulla stessa API:

Channel manager (Booking.com, ACSI, Pincamp, Camping.info, ANWB, Hipcamp)
TWINT (pagamenti)
Swiss QR-Bill (import camt.054 per la riconciliazione)
HESTA (statistiche mensili)
Export contabili (Bexio, Abacus, Sage, DATEV)
Casse (Sumup, Worldline, Vectron, Lightspeed, Toast, Square)
Colonnine di ricarica OCPP (eCarUp, Plugsurfing, EVPass)
Contatori intelligenti (Landis+Gyr, Iskra)

Se il Suo strumento rientra in queste categorie, ne parli al Suo referente CampOne — la connessione esiste probabilmente già, o richiede solo una mappatura leggera.

Schemi di integrazione comuni

Obiettivo	Approccio raccomandato
Spingere prenotazioni in contabilità	Polling REST quotidiano o webhook, mappatura sul Suo piano dei conti
Sostituire il widget online	`pitches:read` + `bookings:write` e funnel proprio
Sincronizzare un canale personalizzato	Webhook `availability.changed` + REST `bookings:read`
Visualizzazione di occupazione in tempo reale	`analytics:read` con cache
CRM ospiti proprio	`guests:read/write` con campi di consenso e ID di audit

Stabilità e versioning

Una volta integrato in /api/v1, facciamo solo modifiche non breaking (campi opzionali, nuovi endpoint). I cambi breaking vanno in /api/v2 con rollout parallelo e almeno 12 mesi di sovrapposizione.

Un changelog vive per ora nella console API (beta privata) e apparirà qui all’apertura pubblica.

Sicurezza

Tutto il traffico è in TLS 1.3
I token sono memorizzati con hash (Argon2id) — mostrati una sola volta alla creazione
Le chiavi ruotate propagano in pochi secondi
Un token revocato cessa di funzionare immediatamente
Una voce di audit viene creata per ogni chiamata autenticata, con IP e user agent

Come ottenere l’accesso

Prima della pubblicazione del riferimento, i partner ottengono l’accesso tramite un processo guidato:

Contatto col Suo referente CampOne e una pagina sul caso d’uso.
Predisposizione di un tenant sandbox con dati sintetici.
Condivisione della specifica OpenAPI 3.1 attuale (importabile in Postman / Insomnia / OpenAPI Generator).
Revisione congiunta dell’integrazione prima della messa in produzione.

Se è un tenant che vuole scrivere automatismi interni (es. export contabile notturno), basta un token di accesso personale — non serve un processo separato.