Booking API – Endpoint¶
Base URL di produzione: https://bcok.it/wp-json/booking/v2. Tutti gli endpoint richiedono l'autenticazione.
| Metodo | Endpoint | Uso | Flusso |
|---|---|---|---|
| GET | /sedi |
Sedi prenotabili dall'utente API | Stripe |
| GET | /carnet/{codice_carnet} |
Verifica un Carnet e restituisce le sedi in cui è utilizzabile | Carnet |
| GET | /info_sede |
Tipologie di spazio, orari e preavviso di una sede | Entrambi |
| GET | /risorse/cerca |
Spazi liberi, con prezzo | Entrambi |
| POST | /prenota/{risorsa_id} |
Crea la prenotazione | Entrambi |
| POST | /stripe-verify-payment |
Stato di una prenotazione pagata con Stripe | Stripe |
Nei parametri, Carnet indica i campi da usare solo nel flusso Carnet e Stripe quelli da usare solo nel flusso Stripe.
Gli esempi usano ID fittizi.
GET /sedi¶
Restituisce le sedi a cui l'utente API è abilitato e che hanno il booking online attivo.
Parametri: nessuno.
Risposta 200: array di sedi.
| Campo | Tipo | Descrizione |
|---|---|---|
id |
integer | ID della sede (sede_id) |
nome |
string | Nome della sede |
descrizione |
string | Descrizione (testo semplice) |
citta, indirizzo, cap, provincia |
string | Indirizzo |
telefono, email |
string | Recapiti della sede (da usare per disdette e modifiche) |
booking_con_stripe |
boolean | true se la sede accetta prenotazioni con pagamento Stripe |
[
{
"id": 580,
"nome": "Milano Centro",
"descrizione": "Business center nel cuore di Milano",
"citta": "Milano",
"indirizzo": "Via Esempio 1",
"cap": "20100",
"provincia": "MI",
"telefono": "+39 02 0000000",
"email": "milano@example.com",
"booking_con_stripe": true
}
]
Nel flusso Stripe proponete all'utente solo le sedi con
booking_con_stripe: true.
Errori principali: Error_Booking_sedi_not_found (404) se nessuna sede è disponibile.
GET /carnet/{codice_carnet}¶
Verifica che il Carnet esista, sia attivo e appartenga al cliente indicato. Restituisce i dati del Carnet, del cliente e le sedi in cui si può usare tramite la vostra applicazione.
Parametri
| Nome | Dove | Tipo | Obbl. | Descrizione |
|---|---|---|---|---|
codice_carnet |
path | integer | sì | Codice del Carnet (solo cifre) |
cliente_id |
query | string | sì | Partita IVA o Codice Fiscale del titolare del Carnet, senza prefisso nazionale (es. 01234567890, non IT01234567890) |
curl -u "UTENTE:PASSWORD" "https://bcok.it/wp-json/booking/v2/carnet/12345?cliente_id=01234567890"
Risposta 200
| Campo | Descrizione |
|---|---|
carnet.codice_carnet |
Codice del Carnet |
carnet.nome_carnet |
Nome commerciale |
carnet.data_scadenza |
Scadenza: non si può prenotare oltre questa data |
carnet.status |
publish (attivo) o in-scadenza |
carnet.tipo_carnet |
Tipi di spazio prenotabili con il Carnet (id, slug, name) |
carnet.unità_misura_nice |
Unità di misura leggibile (es. "Ore") |
carnet.unità_misura.slug |
Unità di misura: ore, mezze-giornate, giornate, euro |
carnet.max_utilizzi |
Quantità totale del Carnet |
carnet.n_utilizzi_disponibili |
Residuo disponibile |
carnet.utilizzi |
Storico degli utilizzi |
cliente |
Dati del titolare: ragione_sociale, p_iva, cod_fiscale, email, telefono, sdi, pec, indirizzo |
sedi_disponibili |
Sedi in cui il Carnet è utilizzabile tramite la vostra applicazione: sede_id, sede_name, sede_zona, sede_indirizzo, sede_telefono, sede_email |
test_mode |
Vedi Ambienti |
{
"carnet": {
"codice_carnet": 12345,
"nome_carnet": "Carnet Sala Riunioni 10 ore",
"data_scadenza": "2027-06-30",
"status": "publish",
"tipo_carnet": [ { "id": 6, "slug": "sala-riunioni", "name": "Sala Riunioni" } ],
"max_utilizzi": "10",
"unità_misura": { "term_id": 31, "name": "Ore", "slug": "ore" },
"unità_misura_nice": "Ore",
"n_utilizzi_disponibili": "6",
"attivato_presso": { "sede_id": 580, "sede_name": "Milano Centro" },
"utilizzabile_presso": [ { "sede_id": 580, "sede_name": "Milano Centro" } ],
"utilizzi": [ "..." ]
},
"cliente": {
"ragione_sociale": "Esempio S.r.l.",
"p_iva": "IT01234567890",
"email": "amministrazione@example.com",
"...": "..."
},
"sedi_disponibili": [
{ "sede_id": 580, "sede_name": "Milano Centro", "sede_zona": "Milano", "sede_indirizzo": "Via Esempio 1, 20100. Milano (MI)", "sede_telefono": "+39 02 0000000", "sede_email": "milano@example.com" }
],
"test_mode": false
}
Alcuni valori numerici (max_utilizzi, n_utilizzi_disponibili) sono restituiti come stringhe.
Errori principali: Carnet_non_Valido, Carnet_ID_non_Valido, Carnet_Valida_Cliente_ID_non_valido (il Carnet non appartiene a quella P.IVA/CF), Carnet_<STATO>, es. Carnet_CESSATO (Carnet non attivo), Sedi_non_disponibili (il Carnet non è utilizzabile in nessuna sede abilitata alla vostra applicazione). Vedi Errori.
GET /info_sede¶
Restituisce le informazioni necessarie per costruire il modulo di ricerca: tipologie di spazio prenotabili, orari di apertura e preavviso.
Parametri
| Nome | Tipo | Obbl. | Descrizione |
|---|---|---|---|
sede_id |
integer | sì | ID della sede |
codice_carnet |
integer | Carnet | Se presente, le tipologie sono filtrate su quelle ammesse dal Carnet e la sede deve essere tra quelle utilizzabili dal Carnet |
cliente_id |
string | Carnet | P.IVA/CF del titolare del Carnet (come in /carnet). Permette di applicare eventuali condizioni riservate al cliente |
Risposta 200
La risposta contiene i campi standard della sede in formato WordPress (vedi handbook) più alcuni campi specifici. Quelli che servono:
| Campo | Tipo | Descrizione |
|---|---|---|
id |
integer | ID della sede |
title.rendered |
string | Nome della sede |
meta.orari_prenotabili |
string (JSON) | Orari prenotabili per giorno della settimana. Vedi Orari e opzioni |
meta.booking_con_stripe |
boolean | La sede accetta pagamenti Stripe |
tipi_risorse |
array | Tipologie di spazio prenotabili: id (da usare come tipo_spazio nella ricerca), nome, slug |
ore_preavviso |
integer | Preavviso standard della sede in ore lavorative (le singole risorse possono avere un preavviso diverso, restituito dalla ricerca) |
test_mode |
boolean | Vedi Ambienti |
{
"id": 580,
"title": { "rendered": "Milano Centro" },
"meta": {
"orari_prenotabili": "{\"0\":{\"enabled\":false},\"1\":{\"enabled\":true,\"morningStart\":\"09:00\",\"morningEnd\":\"13:00\",\"afternoonStart\":\"14:00\",\"afternoonEnd\":\"18:00\"}, ... }",
"booking_con_stripe": true
},
"tipi_risorse": [
{ "id": 5, "nome": "Ufficio", "slug": "ufficio" },
{ "id": 6, "nome": "Sala Riunioni", "slug": "sala-riunioni" }
],
"ore_preavviso": 2,
"test_mode": false,
"...": "altri campi WordPress non necessari"
}
Errori principali: Sede_non_valida, Carnet_Risorse_non_trovate (nessuno spazio prenotabile online nella sede), Carnet_Risorse_non_accessibili (403, nessuno spazio accessibile a questo cliente), Carnet_Tipi_Risorse_non_trovati (nessuna tipologia compatibile con il Carnet).
GET /risorse/cerca¶
Cerca gli spazi liberi in una sede per una data e fascia oraria e ne calcola il prezzo.
Parametri
| Nome | Tipo | Obbl. | Descrizione |
|---|---|---|---|
sede_id |
integer | sì | ID della sede |
data_inizio |
string (date-time) | sì | Inizio, RFC 3339 con fuso orario. Vedi Date e orari |
data_fine |
string (date-time) | sì | Fine, stesso giorno dell'inizio |
orario_opzione |
enum | sì | intera_giornata, mezza_giornata_mattina, mezza_giornata_pomeriggio, orario_personalizzato. Vedi Orari e opzioni |
capienza |
integer | sì | Numero di persone: vengono restituiti solo spazi con capienza uguale o superiore |
tipo_spazio |
integer | no | ID della tipologia (da tipi_risorse[].id di /info_sede). Se omesso, tutte le tipologie |
codice_carnet |
integer | Carnet | Codice del Carnet. Se presente il prezzo è calcolato nell'unità del Carnet |
cliente_id |
string | Carnet | P.IVA/CF del titolare del Carnet |
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=mezza_giornata_mattina" \
--data-urlencode "data_inizio=2026-11-20T09:00:00+01:00" \
--data-urlencode "data_fine=2026-11-20T13:00:00+01:00"
Risposta 200 con risultati
| Campo | Descrizione |
|---|---|
ricerca |
I parametri della ricerca |
risorse_disponibili |
Array degli spazi liberi (vedi sotto) |
carnet |
Solo nel flusso Carnet: dati del Carnet come in /carnet |
cliente |
Solo nel flusso Carnet: dati del titolare |
test_mode |
Vedi Ambienti |
Ogni elemento di risorse_disponibili:
| Campo | Tipo | Descrizione |
|---|---|---|
id |
integer | ID della risorsa (risorsa_id per prenotare) |
nome |
string | Nome dello spazio |
descrizione |
string | Descrizione (testo semplice) |
capienza |
string | Numero massimo di persone |
tipo_spazio |
array di string | Nomi delle tipologie |
sede_id, sede_name |
Sede | |
listino |
array | Tariffe della risorsa: tipo (ore, mezze-giornate, giornate), prezzo (netto), name |
prezzo |
object | Le stesse tariffe indicizzate per tipo, es. {"ore": 25, "mezze-giornate": 80} |
addebito_proposto.quanto |
number | Quanto costerà la prenotazione: nel flusso Stripe è il totale in euro IVA inclusa; nel flusso Carnet è la quantità che verrà scalata dal Carnet |
addebito_proposto.importo_netto |
number | Importo senza IVA |
addebito_proposto.iva_percentuale |
number | 0.22 nel flusso Stripe, 0 nel flusso Carnet |
addebito_proposto.iva_importo |
number | Importo IVA |
addebito_proposto.unit_misura / unit_misura_nice |
string | euro/"Euro", oppure l'unità del Carnet |
eccezione_orari_prenotabili |
string (JSON) o null |
Se valorizzato, gli orari prenotabili di questo spazio sono diversi da quelli della sede (stesso formato di meta.orari_prenotabili) |
eccezione_ignora_pranzo |
boolean | Lo spazio è prenotabile anche durante la pausa pranzo |
eccezione_permetti_festivi |
boolean | Lo spazio è prenotabile anche nei giorni di chiusura |
ore_preavviso |
integer | Preavviso richiesto per questo spazio, in ore lavorative |
orario_preavviso_limite |
string (date-time) o null |
Ultimo momento utile per prenotare questo spazio per l'orario richiesto. null se non c'è preavviso |
orario_preavviso_limite_formattato |
string o null |
Lo stesso in formato gg/mm/aaaa hh:mm |
{
"ricerca": { "sede_id": "580", "tipo_spazio": "6", "capienza": "4", "orario_opzione": "mezza_giornata_mattina", "...": "..." },
"risorse_disponibili": [
{
"id": 1234,
"nome": "Sala Riunioni Verde",
"descrizione": "Sala con schermo e lavagna, 8 posti",
"capienza": "8",
"tipo_spazio": [ "Sala Riunioni" ],
"sede_id": 580,
"sede_name": "Milano Centro",
"listino": [
{ "tipo": "ore", "prezzo": 25, "name": "ore" },
{ "tipo": "mezze-giornate", "prezzo": 80, "name": "mezze giornate" }
],
"prezzo": { "ore": 25, "mezze-giornate": 80 },
"addebito_proposto": {
"importo_netto": 80,
"iva_percentuale": 0.22,
"iva_importo": 17.6,
"quanto": 97.6,
"unit_misura": "euro",
"unit_misura_nice": "Euro"
},
"eccezione_orari_prenotabili": null,
"eccezione_ignora_pranzo": false,
"eccezione_permetti_festivi": false,
"ore_preavviso": 2,
"orario_preavviso_limite": "2026-11-19T16:00:00+01:00",
"orario_preavviso_limite_formattato": "19/11/2026 16:00"
}
],
"test_mode": false
}
Preavviso: la ricerca restituisce lo spazio anche se il preavviso non è più rispettabile. Se l'ora attuale è successiva a
orario_preavviso_limite, non proponete lo spazio: la prenotazione verrebbe rifiutata.
Nessun risultato – risposta 200 con un errore nel corpo. Quando non ci sono spazi liberi la risposta ha status HTTP 200 ma il corpo è un errore:
{
"code": "CercaRisorse_nessuna",
"message": "Non sono state trovate risorse disponibili. Prova a cambiare data o orario di prenotazione",
"data": { "status": 200 }
}
Distinguete i due casi controllando la presenza di risorse_disponibili (risultati) o di code (nessun risultato). I codici possibili sono CercaRisorse_nessuna, CercaRisorse_non_permesse, CercaRisorse_accesso_negato. Se gli orari richiesti cadono fuori dall'apertura, in un festivo o a cavallo della pausa pranzo, la ricerca risponde con uno di questi codici senza indicare il motivo: per dare all'utente un messaggio chiaro, validate gli orari lato vostro usando meta.orari_prenotabili.
Altri errori: Carnet_Risorse_non_trovate (500: nessuno spazio di quella tipologia e capienza nella sede), errori sulle date (Prenotazione_data_inizio_passata, Prenotazione_per_piu_giorni, ...), errori sul Carnet. Vedi Errori.
POST /prenota/{risorsa_id}¶
Crea la prenotazione. La disponibilità, gli orari, il preavviso e il prezzo vengono ricontrollati e ricalcolati da BcOk: non vanno inviati prezzi.
- Flusso Carnet (con
codice_carnet): la prenotazione è confermata subito e il Carnet viene scalato. - Flusso Stripe (senza
codice_carnet, consuccess_urlecancel_url): la prenotazione viene creata in attesa di pagamento e la risposta contiene l'URL del Checkout Stripe a cui mandare l'utente. Vedi Prenotare con Stripe.
⚠️ Una richiesta senza
codice_carnete senzasuccess_url/cancel_urlcrea una prenotazione in attesa di un pagamento che non potrà mai avvenire: la risposta sembra positiva, ma BcOk la cancella automaticamente dopo circa 10 minuti. Inviate sempre i parametri di uno dei due flussi.
Parametri comuni
| Nome | Dove | Tipo | Obbl. | Descrizione |
|---|---|---|---|---|
risorsa_id |
path | integer | sì | ID dello spazio (da risorse_disponibili[].id) |
sede_id |
body | integer | sì | ID della sede |
prenotazione_inizio |
body | string (date-time) | sì | Inizio, RFC 3339 con fuso orario |
prenotazione_fine |
body | string (date-time) | sì | Fine, stesso giorno |
orario_opzione |
body | enum | sì | Come nella ricerca |
n_persone |
body | integer | sì | Numero di partecipanti |
persona_nome |
body | string | sì | Nome del referente della prenotazione |
persona_cognome |
body | string | sì | Cognome del referente |
persona_email |
body | string (email) | sì | Email del referente: riceve la conferma |
persona_telefono |
body | string | no | Telefono del referente |
prenotazione_note |
body | string | no | Note per la sede |
booking_source_domain |
body | string | no | Dominio del vostro sito/app (es. www.example.com). Consigliato: ci aiuta a riconoscere le vostre prenotazioni |
booking_source_page_path |
body | string | no | Pagina da cui è partita la prenotazione |
booking_source_server_ip |
body | string | no | IP del vostro server |
Parametri del flusso Carnet
| Nome | Tipo | Obbl. | Descrizione |
|---|---|---|---|
codice_carnet |
integer | sì | Codice del Carnet |
cliente_id |
string | sì | P.IVA/CF del titolare, senza prefisso nazionale |
Parametri del flusso Stripe
| Nome | Tipo | Obbl. | Descrizione |
|---|---|---|---|
success_url |
string | sì | URL a cui Stripe rimanda l'utente dopo il pagamento. Deve contenere già una query string (?): BcOk vi aggiunge &session_id={CHECKOUT_SESSION_ID}. Vedi Prenotare con Stripe |
cancel_url |
string | sì | URL a cui Stripe rimanda l'utente se annulla il pagamento |
cliente_partita_iva_country |
string | sì | Tipo di identificativo fiscale del cliente da fatturare. Vedi Dati di fatturazione |
cliente_partita_iva |
string | sì, salvo Non EU |
Partita IVA (senza prefisso nazionale) o Codice Fiscale |
cliente_codice_fiscale |
string | no | Codice fiscale |
cliente_azienda_privato |
enum | no | azienda o privato |
cliente_ragione_sociale |
string | per le aziende | Ragione sociale |
cliente_indirizzo, cliente_cap, cliente_citta, cliente_provincia, cliente_paese |
string | consigliati | Indirizzo di fatturazione |
cliente_sdi |
string | no | Codice destinatario SDI (fattura elettronica, solo Italia) |
cliente_pec |
string (email) | no | PEC (fattura elettronica, solo Italia) |
Risposta 200 – flusso Carnet
| Campo | Descrizione |
|---|---|
addebito_eseguito |
Quantità scalata dal Carnet, es. "4 Ore" |
prenotazione.id |
Codice della prenotazione |
prenotazione.status |
publish = confermata |
prenotazione.prenotazione_inizio_effettiva / prenotazione_fine_effettiva |
Orari effettivamente prenotati (vedi Orari e opzioni) |
prenotazione.* |
Gli altri campi riportano i parametri inviati |
utilizzo |
Movimento registrato sul Carnet (id, quantita, messaggio, ...) |
carnet.n_utilizzi_disponibili |
Nuovo residuo del Carnet |
cliente |
Dati del titolare |
test_mode |
Vedi Ambienti |
{
"addebito_eseguito": "4 Ore",
"prenotazione": {
"id": 9876,
"status": "publish",
"sede_id": 580,
"risorsa_id": 1234,
"prenotazione_inizio": "2026-11-20T09:00:00+01:00",
"prenotazione_fine": "2026-11-20T13:00:00+01:00",
"prenotazione_inizio_effettiva": "2026-11-20T09:00:00+01:00",
"prenotazione_fine_effettiva": "2026-11-20T13:00:00+01:00",
"persona_nome": "Mario",
"persona_cognome": "Rossi",
"persona_email": "mario.rossi@example.com",
"...": "..."
},
"utilizzo": { "id": 5432, "acquisto_id": 12345, "quantita": 4, "messaggio": "Codice prenotazione: 9876. Spazio: \"Sala Riunioni Verde\" ...", "...": "..." },
"carnet": { "codice_carnet": 12345, "nome_carnet": "Carnet Sala Riunioni 10 ore", "n_utilizzi_disponibili": 2, "...": "..." },
"cliente": { "ragione_sociale": "Esempio S.r.l.", "...": "..." },
"test_mode": false
}
Risposta 200 – flusso Stripe
| Campo | Descrizione |
|---|---|
addebito_eseguito |
Importo netto (senza IVA), es. "80 Euro". Il totale pagato dal cliente è addebito_proposto.quanto della ricerca |
prenotazione.id |
Codice della prenotazione |
prenotazione.status |
in_attesa = in attesa di pagamento |
prenotazione.prenotazione_inizio_effettiva / prenotazione_fine_effettiva |
Orari effettivamente prenotati |
stripe.checkout_url |
URL del Checkout Stripe a cui reindirizzare l'utente |
stripe.session_id |
ID della sessione di pagamento, da usare con /stripe-verify-payment |
stripe.test_mode |
Pagamenti in modalità test |
{
"addebito_eseguito": "80 Euro",
"prenotazione": {
"id": 9877,
"status": "in_attesa",
"sede_id": 580,
"risorsa_id": 1234,
"prenotazione_inizio_effettiva": "2026-11-20T09:00:00+01:00",
"prenotazione_fine_effettiva": "2026-11-20T13:00:00+01:00",
"...": "..."
},
"stripe": {
"session_id": "cs_test_a1B2c3D4...",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4...",
"test_mode": true
}
}
Errori principali: Prenotazione_Risorsa_prenotata (lo spazio è stato occupato nel frattempo), Prenotazione_Preavviso_scaduto (400), errori su orari e festivi (Booking_*), errori sul Carnet (residuo insufficiente, scadenza), errori sui dati fiscali (Prenotazione_Cliente_*, REST_check_VAT-*). Vedi Errori.
POST /stripe-verify-payment¶
Restituisce lo stato di una prenotazione pagata con Stripe, dato l'ID della sessione di pagamento. Si usa quando l'utente torna sul vostro sito dopo il pagamento.
Parametri
| Nome | Tipo | Obbl. | Descrizione |
|---|---|---|---|
session_id |
string | sì | ID della sessione Stripe (stripe.session_id della prenotazione, oppure il parametro session_id ricevuto sul success_url) |
curl -u "UTENTE:PASSWORD" -X POST "https://bcok.it/wp-json/booking/v2/stripe-verify-payment" \
-H "Content-Type: application/json" \
-d '{"session_id":"cs_test_a1B2c3D4..."}'
Risposta 200
| Campo | Descrizione |
|---|---|
success |
Sempre true quando la prenotazione è trovata |
prenotazione.id |
Codice della prenotazione |
prenotazione.status |
confirmed: pagamento ricevuto, prenotazione confermata. pending: pagamento non ancora confermato |
prenotazione.stripe_payment_status |
Stato del pagamento su Stripe (es. paid); vuoto finché non arriva la conferma |
prenotazione.importo |
Importo netto (senza IVA) |
prenotazione.descrizione |
Descrizione della prenotazione |
prenotazione.inizio, prenotazione.fine |
Orari prenotati |
prenotazione.persona_nome, persona_cognome, persona_email |
Referente |
test_mode |
Vedi Ambienti |
{
"test_mode": true,
"success": true,
"prenotazione": {
"id": 9877,
"status": "confirmed",
"importo": "80",
"descrizione": "Mario Rossi - 2026-11-20 ...",
"stripe_session_id": "cs_test_a1B2c3D4...",
"stripe_payment_status": "paid",
"persona_email": "mario.rossi@example.com",
"persona_nome": "Mario",
"persona_cognome": "Rossi",
"inizio": "2026-11-20T09:00:00+01:00",
"fine": "2026-11-20T13:00:00+01:00"
}
}
Errori: Stripe_Prenotazione_Non_Trovata (404): non esiste una prenotazione attiva per quella sessione. Succede quando il pagamento è fallito o la sessione è scaduta (la prenotazione è stata annullata) o quando il session_id è errato.