Zimun: Appointment Scheduling & Booking Software: Guida API

L’API di Zimun: Appointment Scheduling & Booking Software è pensata per i team che vogliono una prenotazione fluida nei propri strumenti. Usala per mostrare disponibilità in tempo reale, mettere hold temporanei e confermare appuntamenti senza conflitti.

Per chi è questa API

Se gestisci un’app clienti, un portale staff o uno strumento interno, l’API ti consente di tenere la logica di pianificazione sincronizzata con Zimun: Appointment Scheduling & Booking Software mantenendo l’esperienza.

Pensalo come un motore di pianificazione che puoi integrare ovunque: sul tuo sito, nella tua app mobile o in uno strumento amministrativo interno.

Protocollo e formato

• HTTPS + risposte JSON (UTF‑8).
• Autenticazione OAuth2 Client Credentials (RFC 6749 §4.4).
• POST/PATCH idempotenti con Idempotency‑Key per retry sicuri.
• Paginazione tramite page_size/page_token con { items, next_page_token }.
• Timestamp ISO‑8601 con offset di fuso orario.

Come funziona l’autenticazione

1. Crea un client API in Impostazioni → API Clients per ottenere client_id e client_secret.
2. Richiedi un token da /oauth/token usando il grant client credentials.
3. Chiama l’API con Authorization: Bearer <token>.

I token sono di breve durata e limitati alla tua organizzazione.

Scope in breve

• org:read - metadati dell’organizzazione
• availability:read - slot e mappa festività
• appointments:read - elencare/visualizzare appuntamenti
• appointments:write - hold, confermare, riprogrammare, annullare, webhooks

URL di base

https://api.zimun.online/api/v1

Flusso di prenotazione tipico

1. Mostrare la disponibilità per un servizio o un membro del team.
2. Crea un hold di 10 minuti quando un utente sceglie uno slot.
3. Conferma l’appuntamento con i dati del cliente - oppure rilascia l’hold se annullano.

Questo flusso rispecchia quello della pagina di prenotazione pubblica, quindi ottieni lo stesso comportamento senza conflitti.

Esempio rapido (cURL)

Usa questo esempio per recuperare la disponibilità dei prossimi 7 giorni. Sostituisci service_id e il tuo access token.

curl -X GET \
  "https://api.zimun.online/api/v1/availability?service_id=s_123&days_ahead=7" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Per esempi end‑to‑end in Python, Node.js, Go e Rust, vedi la pagina di Riferimento API.

Casi d’uso tipici

• Prenotazione integrata - Usa l’API per alimentare un’interfaccia di pianificazione personalizzata nella tua app.
• Sincronizzazione CRM / POS - Invia gli appuntamenti confermati ai tuoi strumenti interni o allo stack di analytics.
• Dashboard operativo - Interroga servizi, staff e risorse per una vista del calendario in tempo reale.

User story

• Un'app clinica mostra i terapisti disponibili per servizio, mette un hold mentre il paziente compila un modulo e poi conferma l'appuntamento.
• Uno studio sincronizza gli appuntamenti nel suo dashboard BI con un pull notturno.
• Un marketplace SaaS integra un modal di prenotazione che usa la disponibilità e le regole di conflitto di Zimun: Appointment Scheduling & Booking Software.