Documentazione API
Integra termine.lol nella tua applicazione.
Autenticazione
Gli endpoint embed (Calendario & Slot) richiedono una chiave API nell'header. Le chiavi API vengono create per calendario e possono essere gestite nella dashboard sotto la scheda "Chiavi API". Gli endpoint di prenotazione (Riservare & Completare) sono pubblici e non richiedono chiave API — sono protetti dalla limitazione della frequenza.
Invia la tua chiave API nell’header x-api-key:
x-api-key: your_api_key
URL di base
Tutti gli endpoint utilizzano il seguente URL di base:
https://termine.lol
Date e orari
startAt ed endAt di un appuntamento sono l’ora locale sul posto, nel fuso orario del calendario (campo timezone). Sono scritti in formato ISO con una Z finale, ma non sono UTC: «2026-10-01T09:00:00.000Z» significa le 9:00 nel calendario, ovunque si trovi il server. Lo stesso vale per time e slotIndex degli slot liberi (slotIndex conta i quarti d’ora da mezzanotte, 36 = 09:00).
Sono invece istanti reali in UTC createdAt, submittedAt, confirmedAt e reservationExpiresAt.
Gestione degli errori
Tutti gli errori vengono restituiti come JSON con un campo `error`:
{
"error": "Ungültiger API-Key"
}Codici di stato HTTP
- 400 — Richiesta non valida (parametri mancanti)
- 401 — Chiave API non valida o mancante
- 403 — Chiave API non autorizzata per questo calendario / limite raggiunto
- 404 — Risorsa non trovata
- 409 — Conflitto (slot già occupato)
- 410 — prenotazione scaduta (al completamento)
- 429 — Troppe richieste (limite di frequenza)
- 500 — Errore interno del server
- Con dati non validi (400), error è un oggetto con un elenco di messaggi per campo, non un testo.
- 429 contiene inoltre retryAfter (secondi) e l’header Retry-After.
- I messaggi di errore sono in tedesco. La riserva e il completamento rispondono nella lingua indicata da Accept-Language o ?lang= (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Flusso di prenotazione
Il flusso tipico di una prenotazione tramite API:
- 1. Recupera calendario → Ottieni membri e tipi di appuntamento
- 2. Recupera slot → Carica le fasce orarie disponibili per un giorno
- 3. Riserva slot → Crea una riserva di 10 minuti
- 4. Completa prenotazione → Invia i dati del cliente, viene inviata l'e-mail di conferma
- 5. Il cliente conferma → Cliccando sul link nell'e-mail, la prenotazione viene confermata
Recupera calendario
Restituisce le informazioni di base di un calendario, inclusi i membri attivi e i tipi di appuntamento.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Parametri del percorso
| Parameter | Description |
|---|---|
id* | L'ID del calendario |
Risposta
{
"data": {
"id": "...",
"title": "My Calendar",
"timezone": "Europe/Berlin",
"members": [
{ "id": "...", "name": "Max Mustermann" }
],
"appointmentTypes": [
{
"id": "...",
"name": "Beratung",
"description": "30-Minuten-Beratungsgespräch",
"durationMin": 30,
"mode": "online",
"memberIds": ["..."]
}
]
}
}Recupera slot disponibili
Restituisce le fasce orarie disponibili per un giorno specifico e un tipo di appuntamento. Senza `personUserId`, vengono interrogati tutti i membri e i risultati vengono uniti (`byPerson` contiene il dettaglio).
curl -H "x-api-key: your_api_key" \ "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2026-03-15&appointmentTypeId=TYPE_ID"
Parametri di query
| Parameter | Description |
|---|---|
id* | L'ID del calendario (string) |
date* | Data nel formato YYYY-MM-DD (string) |
appointmentTypeId* | ID del tipo di appuntamento (string) |
personUserId | ID del membro (string, opzionale — predefinito: "any" = tutti i membri) |
Risposta
{
"data": {
"date": "2026-03-15",
"personUserId": "any",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 37, "time": "09:15" },
{ "slotIndex": 38, "time": "09:30" }
],
"byPerson": [
{
"date": "2026-03-15",
"personUserId": "member_id_1",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 37, "time": "09:15" }
]
}
]
}
}Riservare uno slot
Riserva una fascia oraria per 10 minuti. La prenotazione deve essere completata entro questo tempo. Questo endpoint non richiede chiave API — è pubblico e protetto dalla limitazione della frequenza (20 richieste/min).
curl -X POST https://termine.lol/api/public/bookings/reserve \
-H "Content-Type: application/json" \
-d '{
"calendarId": "CALENDAR_ID",
"appointmentTypeId": "TYPE_ID",
"date": "2026-03-15",
"startSlot": 36
}'Corpo della richiesta (JSON)
| Parameter | Description |
|---|---|
calendarId* | ID del calendario (string) |
appointmentTypeId* | ID del tipo di appuntamento (string) |
date* | Data nel formato YYYY-MM-DD (string) |
startSlot* | Indice dello slot 0–95, ogni 15 min (number) |
personUserId | ID del membro (string, opzionale — senza indicazione, assegnazione automatica) |
appointmentMode | Modalità appuntamento: "online" o "in_person" (string, opzionale — solo per tipi ibridi) |
Risposta (201 Created)
{
"data": {
"bookingId": "abc123...",
"reservationExpiresAt": "2026-03-15T10:10:00.000Z",
"fields": [
{ "key": "email", "label": "E-Mail", "type": "email", "required": true },
{ "key": "name", "label": "Name", "type": "text", "required": true },
{ "key": "phone", "label": "Telefon", "type": "tel", "required": false }
]
}
}Completare la prenotazione
Invia i dati del cliente per una prenotazione riservata. Il cliente riceverà un'e-mail di conferma con un link di conferma. Questo endpoint non richiede chiave API — è pubblico e protetto dalla limitazione della frequenza (5 richieste/min).
curl -X POST https://termine.lol/api/public/bookings/submit \
-H "Content-Type: application/json" \
-d '{
"bookingId": "abc123...",
"customerEmail": "kunde@beispiel.de",
"customerData": {
"email": "kunde@beispiel.de",
"name": "Max Mustermann",
"phone": "+49 170 1234567"
}
}'Corpo della richiesta (JSON)
| Parameter | Description |
|---|---|
bookingId* | ID della prenotazione dalla riserva (string) |
customerEmail* | E-mail del cliente (string) |
customerData* | Dati del cliente come oggetto — le chiavi corrispondono ai valori `key` dei `fields` dalla riserva (object) |
Risposta (200 OK)
{
"data": {
"success": true,
"message": "Bestätigungs-E-Mail gesendet"
}
}POST /api/public/bookings/abandon
Libera subito una prenotazione quando il cliente rinuncia. Body: { "bookingId": "…" }. Senza questa chiamata scade da sola dopo 10 minuti.
Limitazione della frequenza
Gli endpoint API hanno limiti di frequenza. I limiti variano per endpoint:
- 120 richieste / minuto per chiave (calendario e slot)
- 20 riserve e 5 prenotazioni completate / minuto per indirizzo IP
Permessi (scope)
Ogni chiave API porta dei permessi. Le chiavi senza permessi salvati (tutte quelle create prima degli scope) valgono come "embed". Se a una chiave manca il permesso necessario, l'API risponde 403 con `insufficient_scope`.
- embed — calendario, tipi di appuntamento e slot liberi (endpoint di incorporamento)
- bookings:read — elencare e leggere le prenotazioni, inclusi i dati dei clienti
- bookings:write — annullare, spostare, impostare stato e nota, reinviare la conferma
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Quale permesso serve a quale endpoint
- embed — GET /api/embed/calendars/:id, …/slots e GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings e GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots e POST …/email
API partner
Endpoint per integrazioni che mostrano e gestiscono appuntamenti (ad es. il plugin WordPress). Tutti si trovano sotto /api/partner/, richiedono la chiave API nell'header x-api-key e si riferiscono sempre al calendario della chiave — non c'è un ID calendario nel percorso.
GET /api/partner/calendar
Il calendario della chiave: titolo, fuso orario, membri, tipi di appuntamento, campi del modulo e permessi della chiave.
curl -H "x-api-key: your_api_key" https://termine.lol/api/partner/calendar
{
"data": {
"id": "665f1c2e9b1d4a0012345678",
"title": "Salon Demo",
"slug": "salon-demo",
"timezone": "Europe/Berlin",
"confirmationMode": "double_opt_in",
"members": [{ "id": "…", "name": "Alice" }],
"appointmentTypes": [
{ "id": "…", "name": "Beratung", "description": "", "durationMin": 30, "mode": "online",
"priceCents": 4200, "currency": "EUR", "category": "", "memberIds": [] }
],
"fields": [{ "key": "name", "label": "Name", "type": "text", "required": true, "options": null }],
"scopes": ["embed", "bookings:read"]
}
}GET /api/partner/bookings
Elencare le prenotazioni. Predefinito: tutti gli stati tranne reserved ed expired, 25 per pagina.
curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"
Parametri di query
- from, to — data ISO, intervallo su startAt
- status — ripetibile: reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past o future
- limit (1–100, predefinito 25), offset (predefinito 0)
- q — ricerca su indirizzo e-mail e nome
{
"data": {
"bookings": [
{
"id": "665f1c2e9b1d4a0012345678",
"startAt": "2026-10-01T09:00:00.000Z",
"endAt": "2026-10-01T09:30:00.000Z",
"status": "confirmed",
"appointmentType": { "id": "…", "name": "Beratung" },
"member": { "id": "…", "name": "Alice" },
"customer": { "email": "kunde@example.com", "name": "Max", "fields": { "phone": "…" } },
"appointmentMode": "online",
"meetLink": null,
"internalNote": null,
"anonymized": false,
"createdAt": "2026-09-20T10:12:00.000Z",
"submittedAt": "2026-09-20T10:13:10.000Z",
"confirmedAt": "2026-09-20T10:15:42.000Z"
}
],
"total": 1,
"limit": 25,
"offset": 0
}
}GET /api/partner/bookings/:id
Una prenotazione con tutti i dettagli. Se non appartiene al calendario della chiave, l'API risponde 404.
PATCH /api/partner/bookings/:id
Modificare una prenotazione, con lo stesso payload della dashboard.
{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }- Per ogni richiesta viene eseguita esattamente una modifica, con questa priorità: status, reschedule, internalNote, message. La risposta è la prenotazione modificata.
- completed e no_show sono possibili solo da confirmed (e tra loro); cancelled funziona da qualsiasi stato. Uno spostamento su un orario non libero risponde 400.
GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD
Slot liberi per spostare una prenotazione in un giorno (?date=YYYY-MM-DD).
{
"data": {
"date": "2026-10-02",
"availableSlots": [
{ "slotIndex": 36, "time": "09:00" },
{ "slotIndex": 38, "time": "09:30" }
]
}
}POST /api/partner/bookings/:id/email
Reinviare l'e-mail di conferma: per prenotazioni confermate con un nuovo link di annullamento, per quelle in sospeso con un nuovo link di conferma.
{ "data": { "sent": true, "kind": "confirmed" } }Flusso di connessione (OAuth con PKCE)
Invece di copiare una chiave a mano, un'app partner può collegare l'utente con un clic. I client pubblici (ad es. un plugin su domini altrui) non hanno bisogno di un segreto; proteggono il flusso con PKCE (S256).
- 1. Generare code_verifier (43–128 caratteri) e state; code_challenge = base64url(sha256(code_verifier))
- 2. Inviare l'utente a /connect con client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 e scope
- 3. L'utente vede il dominio di destinazione e i permessi, sceglie un calendario e approva. Torna ?code=…&state=… (oppure ?error=access_denied).
- 4. Riscattare il codice lato server: POST /api/connect/token con client_id, code, code_verifier e redirect_uri. Risposta: calendarId, apiKey, scopes.
- 5. Alla disconnessione chiamare POST /api/connect/revoke con client_id e apiKey, così nessuna chiave resta attiva.
https://termine.lol/it/connect?client_id=wordpress&redirect_uri=https%3A%2F%2Fexample.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dtermine-lol&state=…&code_challenge=…&code_challenge_method=S256&scope=embed+bookings%3Aread+bookings%3Awrite
POST /api/connect/token
{
"client_id": "wordpress",
"code": "…",
"code_verifier": "…",
"redirect_uri": "https://example.com/wp-admin/admin.php?page=termine-lol"
}
→ { "data": { "calendarId": "…", "apiKey": "…", "scopes": ["embed", "bookings:read", "bookings:write"] } }POST /api/connect/revoke
{ "client_id": "wordpress", "apiKey": "…" }