Riferimento API
Agon espone un'API REST usata dall'app desktop, dall'app mobile e dal widget pubblico di prenotazione per il sito web. Se sei uno sviluppatore e vuoi integrarti con Agon o costruire qualcosa sopra di esso, questa pagina spiega le basi.
URL di base
L'API funziona localmente sul computer dello studio manager:
http://localhost:8000
Quando i clienti si collegano dall'esterno (tramite l'app mobile o il widget del sito web), usano l'URL del Cloudflare Tunnel nominato dello studio, che ha questa forma:
https://studio-<id>.tunnel.agon-studio.dev
Tutti gli endpoint sono versionati sotto /api/v1/. Per esempio:
http://localhost:8000/api/v1/clients
Questa pagina riguarda il backend, che funziona localmente sul computer di ogni studio. Non esiste un'API Agon centrale: il servizio di licenze e il proxy AI ospitato non esistono più, e l'Assistente AI chiama direttamente il provider AI configurato dallo studio (vedi Studio → Configurazione Assistente AI).
Autenticazione
Tutti gli endpoint protetti richiedono un token di accesso JWT valido nell'header Authorization:
Authorization: Bearer <your_access_token>
Per ottenere un token, invia una richiesta POST a /api/v1/auth/login con la tua email e password:
{
"email": "manager@mystudio.com",
"password": "your-password"
}
La risposta include un access_token (valido 8 ore per il desktop, 30 giorni per il mobile) e un refresh_token.
Quando l'access token scade, invia il refresh token a POST /api/v1/auth/refresh per ottenere un nuovo access token senza dover accedere di nuovo.
Formato della risposta
Tutti gli endpoint restituiscono JSON. Le risposte di successo restituiscono direttamente i dati richiesti.
Esempio di risposta di successo:
{
"id": 42,
"full_name": "Jane Smith",
"email": "jane@example.com",
"status": "active"
}
Formato degli errori
Tutte le risposte di errore seguono questa struttura:
{
"error": {
"code": "BOOKING_CLASS_FULL",
"message": "This class is full. Would you like to join the waitlist?",
"details": {}
}
}
Codici di errore comuni:
| Codice | Significato |
|---|---|
AUTH_INVALID_CREDENTIALS | Email o password errate |
AUTH_TOKEN_EXPIRED | L'access token è scaduto — rinnovalo |
AUTH_INSUFFICIENT_PERMISSIONS | Il tuo ruolo non consente questa azione |
BOOKING_CLASS_FULL | Nessun posto disponibile nella lezione |
BOOKING_ALREADY_EXISTS | Il cliente ha già una prenotazione per questa lezione |
BOOKING_NO_MEMBERSHIP | Il cliente non ha un abbonamento attivo o credits (usato anche per la prenotazione di appuntamenti) |
BOOKING_CANCELLATION_WINDOW_PASSED | Troppo vicino all'inizio della lezione per cancellare |
CHECKIN_NO_BOOKING | Nessuna prenotazione confermata trovata per questo cliente e questa lezione |
CHECKIN_OUTSIDE_WINDOW | Fuori dalla finestra temporale di check-in |
CHECKIN_ALREADY_CHECKED_IN | Il cliente ha già effettuato il check-in |
WAIVER_SIGNATURE_REQUIRED | Il cliente ha una liberatoria obbligatoria non firmata e non può prenotare |
APPOINTMENT_SERVICE_INACTIVE | Il servizio per appuntamenti richiesto è stato disattivato |
APPOINTMENT_INSTRUCTOR_INACTIVE | L'account dell'istruttore richiesto non è attivo |
APPOINTMENT_IN_PAST | L'orario di inizio dell'appuntamento richiesto è nel passato |
APPOINTMENT_OUTSIDE_AVAILABILITY | L'orario richiesto è fuori dalla disponibilità dell'istruttore |
APPOINTMENT_SLOT_CONFLICT | L'orario richiesto si sovrappone a un altro appuntamento confermato (incluso il tempo di buffer) |
APPOINTMENT_ALREADY_CANCELLED | L'appuntamento non è in uno stato confermato e non può essere cancellato di nuovo |
APPOINTMENT_NOT_CONFIRMED | L'appuntamento deve essere confermato per poter essere segnato come completato o no-show |
NOT_FOUND | La risorsa richiesta non esiste |
VALIDATION_ERROR | Il corpo della richiesta manca di campi obbligatori o contiene valori non validi |
Codici di errore dell'Assistente AI:
| Codice | Significato |
|---|---|
AI_NOT_CONFIGURED | (409) È stata proseguita un'azione AI ma nessun provider AI è configurato — l'assistente è in modalità base. Aggiungi una chiave del provider in Impostazioni → Assistente AI |
AI_RATE_LIMITED | (429) Il provider AI dello studio sta limitando le richieste. details.docs_url punta a Se prevedi un uso intenso |
AI_KEY_INVALID | (400) Il provider ha rifiutato la chiave API inviata a POST /studio/ai |
AI_INVALID_PROVIDER | (422) Il provider inviato a POST /studio/ai non è tra quelli di GET /studio/ai/providers |
Documentazione interattiva (Swagger UI)
L'API di Agon include una documentazione interattiva basata su Swagger UI. Quando Agon è in esecuzione, apri questo URL nel tuo browser:
http://localhost:8000/docs
La Swagger UI ti permette di esplorare tutti gli endpoint disponibili, vedere i loro parametri e formati di risposta, e fare richieste di prova direttamente dal browser.
È disponibile anche una vista OpenAPI alternativa (ReDoc) su:
http://localhost:8000/redoc
Versionamento dell'API
Tutti gli endpoint attuali sono sotto /api/v1/. Quando in una versione futura verranno introdotte modifiche non retrocompatibili, saranno disponibili sotto /api/v2/, mentre /api/v1/ resterà attivo per un periodo di transizione.