Vai al contenuto

Calendar

Il tuo programma, le pagine di prenotazione e i servizi.

Apri Calendar
Verificato rispetto alla dashboard il 19 novembre 2026

Calendar ha metodi pubblici per i due lati di una prenotazione. Alcuni agiscono per te, il proprietario, e richiedono la tua chiave API: leggono la tua configurazione e le tue prenotazioni, configurano risorse, servizi e pagine, bloccano e confermano un orario, annullano e cambiano il piano. Altri sono quelli che una pagina di prenotazione fa per un visitatore. Non richiedono una chiave, solo la chiave della pagina.

La condivisione dei calendari con altre persone, le viste, le attività, gli eventi del giorno e le Impostazioni di Calendario si gestiscono nella dashboard. Oggi non hanno un metodo pubblico.

Invia una richiesta a un metodo con la tua chiave:

curl -s https://xuda.ai/cpi/get_calendar_setup \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID"}'
const res = await fetch('https://xuda.ai/cpi/get_calendar_setup', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/get_calendar_setup',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
    },
)

Una risposta valida ha code 1. Una modifica che il tuo piano non include viene rifiutata con code -62 e una frase in data, per esempio che le sessioni di gruppo richiedono Growth o che il tuo piano contiene un certo numero di pagine di prenotazione. Per agire sul calendario di un account che lo ha condiviso con te con livello di modifica, passa il suo share_id ai metodi che ne accettano uno.

Leggi la tua configurazione e le prenotazioni

  • get_calendar_setup risponde in una sola chiamata a tutto ciò che disegnano le schermate di Calendar: le persone e le stanze prenotabili con i loro orari, i servizi e le pagine di prenotazione pubblicate con i loro indirizzi pubblici.
  • get_calendar_bookings elenca le prenotazioni, per impostazione predefinita quelle future. Passa past impostato su true per quelle già avvenute, le più recenti per prime, e limit per quante. Ogni riga porta l'orario nel fuso della risorsa, i dati dell'ospite e tutto ciò che ha detto prenotando.
  • get_calendar_slots elenca gli orari prenotabili di un servizio su una risorsa tra from_ts e to_ts (millisecondi epoch), escludendo tutto ciò che è già occupato.

Configura ciò che si può prenotare

  • save_calendar_resource crea o aggiorna qualcosa che si può prenotare: una persona, una stanza, una poltrona o un dispositivo. Richiede un timezone, un fuso IANA come Asia/Jerusalem, e i suoi orari vengono letti in quel fuso. Ometti resource_id per crearne una nuova.
  • save_calendar_service crea o aggiorna ciò che le persone possono prenotare: la sua durata, i margini, il preavviso, con quanto anticipo si può prenotare, i posti, dove si svolge (meeting_kind) e, con price_cents, currency e checkout, quanto costa e se si paga al momento della prenotazione. Più di un posto richiede un piano che includa le sessioni di gruppo, e incassare pagamenti richiede un piano che includa i pagamenti.
  • save_calendar_page crea o aggiorna una pagina di prenotazione: il suo title, intro, gli service_ids che offre, se è enabled, il suo colore accent, show_host, se i visitatori possono modificare la loro prenotazione (visitor_changes, change_hours, refund_percent) e il conto Finance su cui viene pagata (finance_account_id). Creare una pagina oltre il limite di pagine del tuo piano viene rifiutato.
  • delete_calendar_item rimuove una risorsa, un servizio o una pagina tramite item_id. Le prenotazioni non vengono mai eliminate in questo modo: vengono annullate.

Prenota tu un orario

Prenotare dal tuo codice richiede due passaggi, così un orario non viene mai venduto due volte.

Blocca l'orario

hold_calendar_slot riserva un orario per alcuni minuti. Passa resource_id, service_id e start_utc (millisecondi epoch). Una risposta valida ha data con occ_id, hold_token e expires_at. Invia un idem_key così una ripetizione della chiamata restituisce lo stesso blocco invece di prendere un secondo posto.

Confermalo

confirm_calendar_booking trasforma il blocco in una prenotazione. Passa occ_id e hold_token dal blocco, e name, email, phone e note dell'ospite. Un blocco che non esiste più ha perso l'orario e viene rifiutato.

curl -s https://xuda.ai/cpi/hold_calendar_slot \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID","resource_id":"RESOURCE_ID","service_id":"SERVICE_ID","start_utc":1793000000000}'
const res = await fetch('https://xuda.ai/cpi/hold_calendar_slot', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
    resource_id: 'RESOURCE_ID',
    service_id: 'SERVICE_ID',
    start_utc: 1793000000000,
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/hold_calendar_slot',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
        'resource_id': 'RESOURCE_ID',
        'service_id': 'SERVICE_ID',
        'start_utc': 1793000000000,
    },
)

Modifica una prenotazione

  • cancel_calendar_booking annulla tramite booking_id e rimette l'orario nella griglia pubblica. È sicuro chiamarlo due volte. Libera soltanto l'orario: non invia email all'ospite né rimborsa un pagamento, cosa che fa invece Annulla appuntamento della dashboard per un ospite che ha prenotato tramite la tua pagina.
  • notify_calendar_guests invia un'email a tutti gli invitati a una prenotazione, un messaggio ciascuno, con l'invito del calendario allegato e un message facoltativo fino a 2000 caratteri. kind è invite per un nuovo appuntamento e update per una modifica, che è il valore predefinito. L'email parte dalla tua casella di posta in un piano che la include, e dall'indirizzo di prenotazione di Xuda altrimenti, con il tuo indirizzo come reply-to.
  • create_booking_room crea la stanza Xuda Meet di una prenotazione video confermata che non ne ha, e invia a ogni ospite il link.

Che cosa chiama una pagina di prenotazione

Una pagina di prenotazione funziona con la sua chiave di pagina, <uid>.<page_id>, e senza account.

  • get_booking_bootstrap risponde con ciò che serve a una pagina per disegnarsi: il suo titolo, i suoi servizi e un token anti-bot recente.
  • get_public_booking_slots elenca gli orari che un visitatore può scegliere, ciascuno con un inizio, una fine e un numero di posti. Non dice mai chi occupa gli altri posti.
  • public_book_slot accetta una prenotazione da un visitatore. Passa page_key, service_id, start_utc, il token, e name ed email del visitatore. Aggiungi un idem_key così una doppia pressione non prenota due volte. company_website è una trappola per i bot: lascialo vuoto.
  • Per un servizio che si paga al momento della prenotazione, public_start_paid_booking blocca l'orario e avvia il pagamento, start_booking_payment invia a Stripe un orario bloccato, e public_confirm_paid_booking e confirm_paid_booking lo prenotano una volta che il pagamento è andato a buon fine. Il pagamento viene riletto da Stripe prima che venga prenotato qualcosa.
  • Un visitatore gestisce una prenotazione dal link privato nella sua email. get_public_booking, public_cancel_booking e public_reschedule_booking prendono la chiave della pagina e il valore manage di quel link. Seguono le regole della pagina: se i visitatori possono modificare una prenotazione e fino a quante ore prima che inizi. Una prenotazione pagata viene prima rimborsata, secondo la percentuale di rimborso della pagina.

Il piano

get_calendar_plans risponde con i quattro livelli con i loro prezzi e ciò che ciascuno include, il piano in cui sei e se Calendar è attivo. calendar_set_plan lo attiva, cambia il livello o lo disattiva: passa plan_id come calendar_free, calendar_starter, calendar_growth o calendar_business, oppure imposta deactivate su true. Vedi Piani e fatturazione.

Tutti i metodi

Come ti sembra questa guida?

Ultimo aggiornamento il 16 novembre 2026