CustomerApp Booking API
Dopo l'accesso con le credenziali del salone, questa API permette di leggere il catalogo servizi e gli operatori di un salone, consultare le disponibilità dell'agenda e registrare un appuntamento direttamente nel gestionale del salone.
- Base URL
https://www.customerapp.it/api/- Formato
- JSON in UTF-8
- Autenticazione
- Token Bearer ottenuto da
login.php - Limite richieste
- 30 ogni 10 secondi per IP
Autenticazione
Tutti gli endpoint tranne login.php richiedono un token. Il token si ottiene con login.php usando cellulare e password dell'account Negozio del salone, vale 30 giorni e va inviato in ogni chiamata nell'intestazione:
Authorization: Bearer <token>
Se un proxy della vostra infrastruttura rimuove l'intestazione Authorization, si può usare in alternativa X-Auth-Token: <token>.
Il token è legato al salone dell'account: shop_id è ricavato dal token e nelle richieste si può omettere. Se viene indicato uno shop_id diverso, la chiamata risponde 403. Quando il token scade la risposta è 401: basta ripetere il login e riprovare.
Flusso di prenotazione
Ogni chiamata riguarda il salone del token. Una prenotazione completa segue di solito questi passi:
- login.phpOttenere il token, da riusare fino alla scadenza.
- services.phpScegliere i servizi e la durata totale.
- operators.phpFacoltativo: scegliere l'operatore per ogni servizio.
- availability.phpMostrare i giorni prenotabili del mese.
- search-slots.phpTrovare gli orari liberi nel giorno scelto.
- appointments.phpConfermare l'appuntamento.
Gli ID di servizi e operatori sono numeri interi e sono gli stessi in tutte le chiamate. Usare quelli ricevuti da services.php e operators.php, senza conservarli a lungo: il salone può modificare il catalogo dal gestionale.
Convenzioni ed errori
Le chiamate GET ricevono i parametri nella query string. Le chiamate POST ricevono un corpo JSON con intestazione Content-Type: application/json. Le date sono nel formato YYYY-MM-DD, gli orari nel formato HH:MM e il fuso orario è Europe/Rome.
| Caso | HTTP | Corpo della risposta |
|---|---|---|
| Token mancante, non valido o scaduto | 401 | {"status":false,"code":401,"message":"Token non valido o scaduto"} |
shop_id diverso dal salone del token | 403 | {"status":false,"code":403,"message":"Il token non è abilitato per questo shop_id"} |
Parametro shop_id mancante (solo token non legati a un salone) | 200 | {"success":0,"message":"Required field(s) is missing"} |
| Errore del gestionale (salone non attivo, orario non più libero…) | 200 | {"status":false,"message":"…"}. Alcune risposte usano la chiave messagge al posto di message: leggere entrambe. |
| Troppe richieste dallo stesso IP | 429 | {"status":false,"code":429,"message":"Too Many Requests"} |
Molti errori arrivano con stato HTTP 200. Per capire se la chiamata è andata a buon fine bisogna controllare il corpo: una lista è un successo, mentre un oggetto con status: false o success: 0 è un errore.
Superato il limite di 30 richieste in 10 secondi, l'IP viene bloccato per 10 minuti. Il catalogo servizi e la lista operatori cambiano di rado: conviene tenerli in cache per qualche minuto.