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:00 oppure 2026-11-20T08:00:00Z.
  • Una data senza fuso orario viene interpretata come UTC: 2026-11-20T09:00:00 significa 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 ad afternoonStart la 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, giornate o euro) e non comprende IVA.
  • Con orario_personalizzato BcOk 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.