Booking API – Prenotare con Carnet

← Booking API

Il cliente ha acquistato un Carnet (un pacchetto di ore, mezze giornate, giornate o di credito in euro) e lo usa per prenotare. Per identificarsi gli bastano due dati, che trova sul proprio Carnet:

  • il codice carnet (numerico);
  • la Partita IVA o il Codice Fiscale dell'intestatario, senza prefisso nazionale.

Non c'è nessun pagamento: la prenotazione è confermata subito e la quantità corrispondente viene scalata dal Carnet.

Il flusso in sintesi

App esterna (server)                               BcOk
        |                                            |
   1    |-- GET /carnet/{codice}?cliente_id=... ---->|  verifica Carnet e cliente
        |<----------- carnet, cliente, sedi ---------|
   2    |-- GET /info_sede?sede_id&codice_carnet --->|  tipologie e orari
        |<---------- tipi_risorse, orari ------------|
   3    |-- GET /risorse/cerca?...&codice_carnet --->|  spazi liberi e quantità da scalare
        |<------------ risorse_disponibili ----------|
   4    |-- POST /prenota/{risorsa_id} ------------->|  prenota e scala il Carnet
        |<---- prenotazione confermata, residuo -----|
        |                                            |--> email di conferma al referente

1. Verificare il Carnet

curl -u "UTENTE:PASSWORD" "https://bcok.it/wp-json/booking/v2/carnet/12345?cliente_id=01234567890"

Dalla risposta (dettagli) servono:

  • carnet.n_utilizzi_disponibili e carnet.unità_misura_nice: il residuo da mostrare all'utente (es. "6 Ore");
  • carnet.data_scadenza: non si può prenotare oltre questa data;
  • carnet.tipo_carnet: i tipi di spazio prenotabili con questo Carnet;
  • sedi_disponibili: le sedi tra cui l'utente può scegliere.

Se il codice è errato, il Carnet non è attivo o non appartiene a quella P.IVA/CF, ricevete un errore (vedi Errori – Carnet). Per sicurezza i messaggi non distinguono troppo tra i casi: chiedete all'utente di ricontrollare i dati.

2. Leggere le informazioni della sede

curl -u "UTENTE:PASSWORD" "https://bcok.it/wp-json/booking/v2/info_sede?sede_id=580&codice_carnet=12345&cliente_id=01234567890"

Con codice_carnet, tipi_risorse contiene solo le tipologie ammesse dal Carnet e presenti nella sede. Usate meta.orari_prenotabili per proporre all'utente solo giorni e orari validi (vedi Orari e opzioni).

3. Cercare gli spazi liberi

curl -u "UTENTE:PASSWORD" -G "https://bcok.it/wp-json/booking/v2/risorse/cerca" \
  --data-urlencode "sede_id=580" \
  --data-urlencode "codice_carnet=12345" \
  --data-urlencode "cliente_id=01234567890" \
  --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"

Per ogni spazio, addebito_proposto.quanto è la quantità che verrà scalata dal Carnet, nell'unità indicata da addebito_proposto.unit_misura_nice. Confrontatela con il residuo per avvisare subito l'utente se il Carnet non basta.

Come viene calcolata la quantità, in base all'unità del Carnet:

Unità del Carnet Quantità scalata
ore Ore prenotate, arrotondate all'ora superiore. Per mezza giornata o giornata intera, le ore di apertura della fascia o della giornata
mezze-giornate 1 per mattina o pomeriggio, 2 per la giornata intera
giornate 1
euro Il prezzo dello spazio da listino (senza IVA)

Ricordate di escludere gli spazi il cui orario_preavviso_limite è già passato.

4. Prenotare

curl -u "UTENTE:PASSWORD" -X POST "https://bcok.it/wp-json/booking/v2/prenota/1234" \
  -H "Content-Type: application/json" \
  -d '{
    "codice_carnet": 12345,
    "cliente_id": "01234567890",
    "sede_id": 580,
    "prenotazione_inizio": "2026-11-20T09:00:00+01:00",
    "prenotazione_fine": "2026-11-20T13:00:00+01:00",
    "orario_opzione": "mezza_giornata_mattina",
    "n_persone": 4,
    "persona_nome": "Mario",
    "persona_cognome": "Rossi",
    "persona_email": "[email protected]",
    "persona_telefono": "+39 333 0000000",
    "prenotazione_note": "Serve il proiettore",
    "booking_source_domain": "www.example.com"
  }'

Se la risposta è 200, la prenotazione è confermata (prenotazione.status = publish). Mostrate all'utente:

  • il codice prenotazione prenotazione.id;
  • gli orari effettivi prenotazione.prenotazione_inizio_effettiva / prenotazione_fine_effettiva;
  • la quantità scalata addebito_eseguito e il nuovo residuo carnet.n_utilizzi_disponibili.

BcOk invia l'email di conferma a persona_email e all'email del titolare del Carnet.

In caso di errore la prenotazione non viene creata e il Carnet non viene scalato. Gli errori più comuni a questo punto:

code Cosa fare
Prenotazione_Risorsa_prenotata Lo spazio è stato occupato nel frattempo: rifate la ricerca
Prenotazione_Preavviso_scaduto Troppo tardi per quell'orario: il messaggio indica fino a quando si poteva prenotare
Acquisti_residuo_inadeguato, Acquisti_disponibilità_terminata Il residuo del Carnet non basta: il messaggio riporta residuo e quantità richiesta
Carnet_data_successiva_scadenza La data è oltre la scadenza del Carnet

Timeout e ripetizione della richiesta

POST /prenota non è idempotente. Se la richiesta va in timeout non sapete se la prenotazione è stata creata: ripetendola, nel caso sia andata a buon fine, riceverete Prenotazione_Risorsa_prenotata, perché lo spazio è ormai occupato dalla prenotazione stessa. In questo caso:

  • rileggete il Carnet con GET /carnet/...: se il residuo è diminuito, la prenotazione è stata registrata (la trovate anche in carnet.utilizzi);
  • in alternativa l'utente avrà ricevuto l'email di conferma.

Usate un timeout lato client generoso (almeno 30 secondi).

Disdette

Le prenotazioni non si possono annullare via API: l'utente deve contattare la sede (recapiti in sedi_disponibili e nell'email di conferma). In caso di disdetta l'operatore della sede può riaccreditare il Carnet.