Booking API – Prenotare con Carnet¶
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_disponibiliecarnet.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_eseguitoe il nuovo residuocarnet.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 incarnet.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.