API Reference
Agon espone una REST API usata sia dall'app desktop che dall'app mobile. Se sei uno sviluppatore e vuoi integrarti con Agon o costruirci sopra, questa pagina spiega le basi.
URL base
L'API gira localmente sulla macchina dello studio manager:
http://localhost:8000
Quando i clienti si connettono dall'esterno (tramite l'app mobile), usano l'URL del Cloudflare Tunnel dello studio, che ha questa forma:
https://your-studio.trycloudflare.com
Tutti gli endpoint sono versionati sotto /api/v1/. Ad esempio:
http://localhost:8000/api/v1/clients
Autenticazione
Tutti gli endpoint protetti richiedono un token JWT di accesso 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 effettuare di nuovo l'accesso.
Formato delle risposte
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 o crediti attivi (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 un modulo di consenso obbligatorio non firmato e non può prenotare |
APPOINTMENT_SERVICE_INACTIVE | Il servizio di appuntamento 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 cuscinetto) |
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 essere segnato come completato o mancata presentazione |
NOT_FOUND | La risorsa richiesta non esiste |
VALIDATION_ERROR | Il corpo della richiesta manca di campi obbligatori o contiene valori non validi |
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 sfogliare tutti gli endpoint disponibili, vederne i parametri e i formati di risposta, e fare richieste di prova direttamente dal browser.
È disponibile anche una vista OpenAPI alternativa (ReDoc):
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.