API e webhook

Arenile è API-first: il pannello del gestore e la pagina di prenotazione usano esclusivamente le stesse API documentate qui. Tutto ciò che vedi nel pannello si può fare anche da un’integrazione.

Il contratto è un solo file, api/openapi.yaml (OpenAPI 3.1), fonte di verità da cui sono generati il codice del server Go e il client TypeScript. Il riferimento API di questo sito è generato dallo stesso file a ogni build: non può essere disallineato.

Le superfici

Superficie	Prefisso	Chi la usa	Autenticazione
API del pannello	`/api/admin/v1`	pannello, integrazioni	cookie di sessione (+ CSRF) o chiave API
API pubblica	`/api/public/v1/{slug}`	pagina di prenotazione, widget	nessuna; token della sessione di checkout o del link magico
Webhook dei pagamenti	`/webhooks/payments/{provider}/{establishment_id}`	Stripe e altri provider	firma del provider
Tempo reale	`/api/admin/v1/stream`	pannello	sessione (Server-Sent Events)
Operatività	`/healthz`, `/readyz`	monitoraggio	nessuna

Convenzioni

JSON in richiesta e risposta, versione nel percorso (v1).
Errori application/problem+json (RFC 9457) con un type stabile: vedi Errori.
Paginazione a cursore: ?cursor=&limit= (default 50, massimo 200); la risposta contiene next_cursor.
Idempotency-Key sui POST che creano risorse o pagamenti: vedi Idempotenza.
Concorrenza ottimistica con ETag e If-Match su configurazione e mappe: vedi ETag e If-Match.
Date di calendario YYYY-MM-DD nel fuso dello stabilimento; istanti RFC 3339 in UTC.
Importi in centesimi interi (2500 = 25,00 €), IVA inclusa.
Ogni dato operativo è legato allo stabilimento: establishmentId nel percorso, verificato contro i permessi dell’utente.
Ogni risposta ha l’header X-Request-ID, ripetuto in request_id negli errori.

AutenticazioneSessione, CSRF, chiavi API, permessi.

API pubblica e checkoutIl flusso di prenotazione passo per passo.

Webhook dei pagamentiFirma, deduplica, conferma e riconciliazione.

Eventi e webhook in uscitaTipi di evento, formato, firma Arenile-Signature.

Erroriproblem+json e l'elenco dei type.

Riferimento APIOgni operazione, generata da openapi.yaml.