Booking API – Endpoint

← Booking API

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": "[email protected]",
    "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": "[email protected]",
    "...": "..."
  },
  "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": "[email protected]" }
  ],
  "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, con success_url e cancel_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_carnet e senza success_url/cancel_url crea 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": "[email protected]",
    "...": "..."
  },
  "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": "[email protected]",
    "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.