Booking API di BcOk¶
Le Booking API permettono a un'applicazione esterna di cercare gli spazi disponibili (uffici, sale riunioni, postazioni) nelle sedi del network e di prenotarli, pagando:
- con un Carnet già acquistato dal cliente (le ore/giornate vengono scalate dal Carnet), oppure
- con carta di credito tramite Stripe (il cliente finale paga sul Checkout Stripe di BcOk).
Le API sono costruite sulle REST API di WordPress: tutto ciò che non è descritto qui (formato generale delle risposte e degli errori, parametri globali come _fields, ecc.) funziona come documentato nell'handbook di WordPress.
Indice¶
| Pagina | Contenuto |
|---|---|
| Booking API (questa pagina) | Concetti, autenticazione, convenzioni |
| Endpoint | Riferimento completo di ogni endpoint: parametri, risposte, esempi |
| Prenotare con Carnet | Guida passo-passo al flusso Carnet |
| Prenotare con Stripe | Guida passo-passo al flusso con pagamento Stripe: cosa deve fare l'app |
| Errori | Formato degli errori ed elenco dei codici |
Cosa si può fare (e cosa no)¶
| Operazione | Disponibile |
|---|---|
| Elencare le sedi prenotabili | ✅ |
| Leggere orari, tipologie di spazio e preavviso di una sede | ✅ |
| Verificare un Carnet e il suo residuo | ✅ |
| Cercare gli spazi liberi in una data/fascia oraria, con il prezzo | ✅ |
| Prenotare con Carnet | ✅ |
| Prenotare con pagamento Stripe | ✅ |
| Verificare l'esito di un pagamento Stripe | ✅ |
| Consultare una prenotazione già fatta | ❌ |
| Modificare o disdire una prenotazione | ❌ (si contatta la sede, vedi sotto) |
| Prenotare più giorni con una sola chiamata | ❌ (una prenotazione per giorno) |
Disdette e modifiche vengono gestite dagli operatori della sede: i recapiti della sede sono restituiti da GET /sedi e sono riportati nell'email di conferma che BcOk invia al cliente.
Concetti¶
| Termine | Significato |
|---|---|
| Sede | Un centro del network (es. "Milano Centro"). Identificata da sede_id. |
| Risorsa | Uno spazio prenotabile in una sede (un ufficio, una sala riunioni...). Identificata da risorsa_id. Ha una capienza (numero di persone) e un listino (prezzo orario, a mezza giornata, a giornata). |
| Tipo di spazio | La tipologia della risorsa (Ufficio, Sala Riunioni, ...). Identificata da un ID numerico (tipo_spazio), che si ottiene da GET /info_sede. |
| Carnet | Pacchetto prepagato acquistato da un cliente (azienda o privato). Identificato dal codice carnet (numerico) e legato alla Partita IVA o Codice Fiscale del cliente. Ha un'unità di misura (ore, mezze-giornate, giornate o euro), un residuo, una scadenza e un elenco di sedi in cui è utilizzabile. |
| Opzione orario | Come si prenota la giornata: intera_giornata, mezza_giornata_mattina, mezza_giornata_pomeriggio, orario_personalizzato. Vedi Orari e opzioni. |
| Preavviso | Numero minimo di ore lavorative di anticipo con cui si può prenotare una risorsa. Può essere 0. |
Ambienti¶
| Ambiente | Base URL |
|---|---|
| Produzione | https://bcok.it/wp-json/booking/v2 |
| Test | da concordare con Ottomedia |
In tutte le risposte il campo test_mode indica se i pagamenti Stripe sono in modalità test (true: si usano le carte di test Stripe, nessun addebito reale).
Autenticazione¶
Ottomedia fornisce un utente API dedicato (username e password). Ogni richiesta deve essere autenticata con HTTP Basic Authentication su HTTPS:
Authorization: Basic base64(username:password)
curl -u "UTENTE:PASSWORD" https://bcok.it/wp-json/booking/v2/sedi
L'utente API determina quali sedi sono visibili e prenotabili: solo quelle a cui l'utente è stato abilitato e che hanno il booking online attivo.
⚠️ Le chiamate devono partire dal vostro server, mai dal browser dell'utente. Le credenziali danno accesso alle prenotazioni di tutte le sedi abilitate: non vanno mai incluse in codice JavaScript, app mobile o pagine web. L'app esterna fa da intermediario tra il proprio frontend e BcOk.
Se l'autenticazione manca o è errata la risposta è 401 (o 403 se l'utente non ha i permessi per il booking), nel formato standard degli errori WordPress.
Convenzioni¶
Formato delle richieste¶
- GET: parametri in query string.
- POST: parametri nel corpo in JSON, con
Content-Type: application/json. (Come in tutte le REST API di WordPress sono accettati anche form-urlencoded o query string, ma consigliamo JSON.) - Le risposte sono sempre JSON in UTF-8.
- Alcune chiavi delle risposte contengono caratteri accentati (es.
unità_misura): il vostro parser JSON deve gestire chiavi UTF-8.
Date e orari¶
- Le date vanno inviate in formato RFC 3339 / ISO 8601 con fuso orario, es.
2026-11-20T09:00:00+01:00oppure2026-11-20T08:00:00Z. - Una data senza fuso orario viene interpretata come UTC:
2026-11-20T09:00:00significa le 10:00 a Roma in inverno. Inviate sempre l'offset. - BcOk lavora nel fuso Europe/Rome: gli orari di apertura delle sedi sono espressi in ora locale e le date nelle risposte sono in ora locale con offset (es.
2026-11-20T09:00:00+01:00).
Orari e opzioni orario¶
Ogni sede pubblica i propri orari prenotabili nel campo meta.orari_prenotabili di GET /info_sede. È una stringa JSON da decodificare:
{
"0": { "enabled": false },
"1": { "enabled": true, "morningStart": "09:00", "morningEnd": "13:00", "afternoonStart": "14:00", "afternoonEnd": "18:00" },
"2": { "enabled": true, "morningStart": "09:00", "morningEnd": "13:00", "afternoonStart": "14:00", "afternoonEnd": "18:00" },
"...": "...",
"6": { "enabled": false }
}
- Le chiavi sono i giorni della settimana:
"0"= domenica,"1"= lunedì, ..."6"= sabato. - Una fascia vuota (
"") significa che quella parte della giornata è chiusa. - Se
morningEndè uguale adafternoonStartla sede fa orario continuato (nessuna pausa pranzo). - Una singola risorsa può avere orari diversi da quelli della sede (eccezioni concordate con alcuni clienti): in quel caso la ricerca restituisce gli orari della risorsa in
eccezione_orari_prenotabili, nello stesso formato.
Come scegliere orario_opzione e quali orari inviare:
orario_opzione |
Orari da inviare | Comportamento |
|---|---|---|
intera_giornata |
Apertura mattina → chiusura pomeriggio del giorno scelto | Gli orari vengono riportati entro l'apertura della sede. La pausa pranzo è inclusa. Si applica il prezzo a giornata. |
mezza_giornata_mattina |
morningStart → morningEnd |
Gli orari vengono riportati entro la fascia mattina. Si applica il prezzo a mezza giornata. |
mezza_giornata_pomeriggio |
afternoonStart → afternoonEnd |
Gli orari vengono riportati entro la fascia pomeriggio. Si applica il prezzo a mezza giornata. |
orario_personalizzato |
Orari scelti dall'utente | Devono stare interamente nella fascia mattina oppure nella fascia pomeriggio (salvo orario continuato) e non possono attraversare la pausa pranzo. La durata viene arrotondata all'ora intera superiore. |
Regole sempre valide:
- una prenotazione è sempre nello stesso giorno (inizio e fine nella stessa data);
- l'inizio deve essere nel futuro e precedente alla fine;
- non si può prenotare nei giorni festivi o di chiusura della sede;
- va rispettato il preavviso della risorsa (vedi
GET /risorse/cerca).
Gli orari effettivamente registrati sono restituiti da POST /prenota nei campi prenotazione_inizio_effettiva e prenotazione_fine_effettiva: mostrate all'utente questi, non quelli inviati.
Prezzi¶
- Il prezzo viene calcolato da BcOk in base al listino della risorsa e all'opzione orario, ed è restituito dalla ricerca in
addebito_proposto. - Nel flusso Stripe l'importo è in euro:
importo_netto(arrotondato all'euro intero superiore) + IVA 22% =quanto, cioè il totale che il cliente pagherà. - Nel flusso Carnet l'importo è espresso nell'unità del Carnet (
ore,mezze-giornate,giornateoeuro) e non comprende IVA. - Con
orario_personalizzatoBcOk applica la tariffa più conveniente: se il costo orario supera il prezzo della mezza giornata o della giornata, si paga la mezza giornata o la giornata.
Disponibilità e concorrenza¶
La ricerca fotografa la disponibilità in quel momento ma non blocca lo spazio. La disponibilità viene ricontrollata al momento di POST /prenota: se nel frattempo qualcun altro ha prenotato, riceverete l'errore Prenotazione_Risorsa_prenotata e dovrete proporre all'utente una nuova ricerca.
Una prenotazione in attesa di pagamento Stripe blocca lo spazio finché il pagamento non viene completato o la sessione di pagamento non scade (vedi Prenotare con Stripe).
Email al cliente¶
Quando una prenotazione è confermata, BcOk invia automaticamente l'email di conferma (con allegato calendario .ics) all'indirizzo persona_email indicato nella prenotazione. L'app esterna non deve inviare conferme proprie, ma può mostrare un riepilogo a video.
Errori e codici HTTP¶
Gli errori seguono il formato WordPress (code, message, data.status). Attenzione: i codici HTTP delle Booking API non sono sempre quelli che vi aspettereste (molti errori di validazione rispondono 500, e "nessuno spazio disponibile" risponde 200). Basatevi sul campo code: i dettagli sono nella pagina Errori.
Esempio rapido¶
# 1. Sedi prenotabili
curl -u "UTENTE:PASSWORD" "https://bcok.it/wp-json/booking/v2/sedi"
# 2. Tipologie di spazio e orari della sede 580
curl -u "UTENTE:PASSWORD" "https://bcok.it/wp-json/booking/v2/info_sede?sede_id=580"
# 3. Sale riunioni (tipo 6) libere per 4 persone il 20/11/2026 dalle 10 alle 12
curl -u "UTENTE:PASSWORD" -G "https://bcok.it/wp-json/booking/v2/risorse/cerca" \
--data-urlencode "sede_id=580" \
--data-urlencode "tipo_spazio=6" \
--data-urlencode "capienza=4" \
--data-urlencode "orario_opzione=orario_personalizzato" \
--data-urlencode "data_inizio=2026-11-20T10:00:00+01:00" \
--data-urlencode "data_fine=2026-11-20T12:00:00+01:00"
Per prenotare proseguite con Prenotare con Carnet o Prenotare con Stripe.