API Reference
Panoramica
Il Carrubo espone una REST API composta da 46 endpoint per la gestione completa delle strutture ricettive: prenotazioni, ospiti, documenti, comunicazioni con la Questura e molto altro.
Base URL:
https://carrubo.cristianobleve.com
Tutte le richieste e le risposte utilizzano il formato JSON (Content-Type: application/json), salvo dove diversamente specificato (es. download PDF, upload immagini).
Autenticazione
L’API supporta due metodi di autenticazione, utilizzabili in alternativa:
1. API Key
Passa la chiave API tramite header o query parameter:
GET /api/v1/prenotazioni HTTP/1.1
Host: carrubo.cristianobleve.com
x-api-key: la-tua-api-key
Oppure come query parameter:
GET /api/v1/prenotazioni?api_key=la-tua-api-key
2. Supabase Bearer Token
Utilizza un token JWT ottenuto tramite autenticazione Supabase:
GET /api/v1/prenotazioni HTTP/1.1
Host: carrubo.cristianobleve.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Endpoint Pubblici
I seguenti endpoint non richiedono autenticazione:
| Endpoint | Descrizione |
|---|---|
GET /api/config |
Configurazione Supabase (URL e chiave pubblica) |
GET /api/version |
Versione dell’applicazione |
GET /api/settings/features |
Feature flag attive |
Formato delle Risposte
Tutte le risposte sono in formato JSON. Una risposta di successo tipica:
{
"data": { ... },
"status": 200
}
Una risposta di errore:
{
"error": "Messaggio di errore descrittivo",
"status": 400
}
Gestione Errori
L’API utilizza i codici di stato HTTP standard:
| Codice | Significato |
|---|---|
200 |
Successo |
201 |
Risorsa creata con successo |
400 |
Richiesta non valida — parametri mancanti o errati |
401 |
Non autenticato — API key o token mancante/non valido |
403 |
Non autorizzato — permessi insufficienti |
404 |
Risorsa non trovata |
429 |
Troppe richieste — rate limit superato |
500 |
Errore interno del server |
Rate Limiting
Le API applicano limiti di frequenza per garantire la stabilità del servizio. In caso di superamento del limite, riceverai una risposta 429 Too Many Requests. Riprova dopo il tempo indicato nell’header Retry-After.
Tabella Riepilogativa degli Endpoint
Prenotazioni
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
GET |
/api/prenotazioni |
✅ | Lista prenotazioni (formato calendario) |
GET |
/api/v1/prenotazioni |
✅ | Lista prenotazioni (RESTful) |
GET |
/api/v1/prenotazioni/:id |
✅ | Dettaglio prenotazione |
POST |
/api/v1/prenotazioni |
✅ | Crea prenotazione |
PUT |
/api/v1/prenotazioni/:id |
✅ | Aggiorna prenotazione |
POST |
/api/v1/prenotazioni/delete-bulk |
✅ | Elimina prenotazioni in blocco |
POST |
/api/saveOspiti |
✅ | Salva dati ospiti |
Alloggiati Web (Questura)
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
GET |
/api/alloggiati/check |
✅ | Test connessione SOAP |
POST |
/api/alloggiati/valida |
✅ | Valida schedine alloggiati |
POST |
/api/alloggiati/invio |
✅ | Invio schedine alla Questura |
GET |
/api/alloggiati/ricevute |
✅ | Scarica ricevute (PDF) |
GET |
/api/alloggiati/verifica-ricevute |
✅ | Verifica incrociata prenotazioni/ricevute |
GET |
/api/alloggiati/codici |
✅ | Codici di riferimento |
Documenti & PDF
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
POST |
/api/documents/upload |
✅ | Carica immagine documento su GitHub |
GET |
/api/documents/:booking_id/:guest_idx/:side |
✅ | Recupera immagine documento |
POST |
/api/generate-pdf |
✅ | Genera PDF tramite Template Engine |
POST |
/api/generate-apitemplate |
✅ | Genera report finanziario PDF da CSV (alias Template Engine) |
GET |
/api/csv-pdf-list |
✅ | Lista PDF generati |
GET |
/api/csv-pdf-download/:id |
✅ | Download PDF |
GET |
/api/history |
✅ | Storico generazione PDF |
Lettere di Benvenuto
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
GET |
/api/lettere-benvenuto |
✅ | Lista lettere di benvenuto |
GET |
/api/lettere-benvenuto/:prenotazioneId |
✅ | Verifica esistenza lettera |
POST |
/api/lettere-benvenuto/genera |
✅ | Genera lettera di benvenuto |
DELETE |
/api/lettere-benvenuto/:prenotazioneId |
✅ | Elimina lettera (per rigenerazione) |
OCR & MRZ (Scanner Documenti)
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
POST |
/api/ocr |
✅ | Elaborazione OCR immagine |
POST |
/api/mrz/parse |
✅ | Parsing righe MRZ |
POST |
/api/save-scan |
✅ | Salva risultato scansione |
Admin & Utenti
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
POST |
/api/operators |
✅ 🔒 | Crea operatore |
GET |
/api/operators |
✅ 🔒 | Lista operatori |
POST |
/api/operators/pfp |
✅ 🔒 | Imposta foto profilo |
GET |
/api/users |
✅ 🔒 | Lista utenti con metadati |
POST |
/api/send-email |
✅ 🔒 | Invia email |
POST |
/api/admin/grant-cookie |
✅ 🔒 | Concedi cookie admin |
POST |
/api/auth/unlink |
✅ | Scollega provider OAuth |
GET |
/api/sessions |
✅ | Lista sessioni attive |
POST |
/api/sessions/revoke-all |
✅ | Revoca tutte le sessioni |
Sistema & Storage
| Metodo | Endpoint | Auth | Descrizione |
|---|---|---|---|
GET |
/api/config |
❌ | Configurazione Supabase |
GET |
/api/version |
❌ | Versione e info deploy |
GET |
/api/settings/features |
❌ | Feature flag |
POST |
/api/settings/features |
✅ 🔒 | Attiva/disattiva feature |
GET |
/api/settings/maintenance |
✅ | Stato manutenzione |
POST |
/api/settings/maintenance |
✅ 🔒 | Attiva/disattiva manutenzione |
GET |
/api/storage/signed-url |
✅ | URL firmato per storage |
GET |
/api/storage/:bucket/:filename |
✅ | Proxy Supabase Storage |
POST |
/api/querysql |
✅ 🔒 | Esegui query SQL |
GET |
/api/widget/data |
✅ | Dati widget dashboard |
GET |
/api/map/top-countries |
✅ | Paesi più frequenti |
GET |
/api/cli/auth/key |
✅ | Chiave autenticazione CLI |
GET |
/sitemap.xml |
❌ | Sitemap XML dinamica |
[!NOTE]
🔒 = Richiede privilegi di amministratore oltre all’autenticazione standard.