← Torna alla home

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
L'accesso API è disponibile dal piano Pro.
Tutti gli endpoint sotto /api/embed/ e /api/partner/ richiedono una chiave. Le chiavi bloccate o revocate sono trattate come sconosciute (401). Usa le chiavi solo sul tuo server: l’API non invia header CORS, quindi le chiamate dal browser di un altro dominio falliscono.

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.

Anche from e to dell’elenco delle prenotazioni sono letti come ora locale. Inviali senza fuso orario, ad es. 2026-10-01 o 2026-10-01T09:00:00.

Gestione degli errori

Tutti gli errori vengono restituiti come JSON con un campo `error`:

{
  "error": "Ungültiger API-Key"
}

Codici di stato HTTP

{
  "error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}

{ "error": "rate_limited", "retryAfter": 42 }

Flusso di prenotazione

Il flusso tipico di una prenotazione tramite API:

  1. 1. Recupera calendario → Ottieni membri e tipi di appuntamento
  2. 2. Recupera slot → Carica le fasce orarie disponibili per un giorno
  3. 3. Riserva slot → Crea una riserva di 10 minuti
  4. 4. Completa prenotazione → Invia i dati del cliente, viene inviata l'e-mail di conferma
  5. 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.

GET/api/embed/calendars/:id
curl -H "x-api-key: your_api_key" \
  https://termine.lol/api/embed/calendars/CALENDAR_ID

Parametri del percorso

ParameterDescription
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": ["..."]
      }
    ]
  }
}
Entrambi gli endpoint del calendario restituiscono anche confirmationMode («instant» o «double_opt_in») e, per tipo di appuntamento, priceCents (prezzo in centesimi o null), currency e category.

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).

GET/api/embed/calendars/:id/slots
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

ParameterDescription
id*L'ID del calendario (string)
date*Data nel formato YYYY-MM-DD (string)
appointmentTypeId*ID del tipo di appuntamento (string)
personUserIdID 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).

POST/api/public/bookings/reserve
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)

ParameterDescription
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)
personUserIdID del membro (string, opzionale — senza indicazione, assegnazione automatica)
appointmentModeModalità 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 }
    ]
  }
}
I `fields` contengono i campi del modulo che devono essere compilati durante la prenotazione. Usa i valori `key` come chiavi nell'oggetto `customerData` durante l'invio.
Facoltativo: extraAppointmentTypeIds (fino a 4 altri tipi di appuntamento nello stesso appuntamento). calendarId può essere anche lo slug del calendario.

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).

POST/api/public/bookings/submit
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)

ParameterDescription
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"
  }
}
La risposta contiene confirmed: nei calendari con confirmationMode «instant» la prenotazione è confermata subito (confirmed: true, nessuna e-mail di conferma necessaria); altrimenti il cliente conferma dal link nell’e-mail (confirmed: false).

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:


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`.

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write non include bookings:read. I permessi si scelgono creando la chiave nella dashboard.

Quale permesso serve a quale endpoint


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"]
  }
}
Entrambi gli endpoint del calendario restituiscono anche confirmationMode («instant» o «double_opt_in») e, per tipo di appuntamento, priceCents (prezzo in centesimi o null), currency e category.

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

{
  "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
  }
}
Le prenotazioni anonimizzate tornano senza dati dei clienti (anonymized: true).

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 } }

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" } }
kind è «confirmed» (conferma con link di cancellazione) oppure «confirmation_request» (nuovo link di conferma).
Limite per chiave: 120 richieste di lettura e 30 di scrittura al minuto.

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. 1. Generare code_verifier (43–128 caratteri) e state; code_challenge = base64url(sha256(code_verifier))
  2. 2. Inviare l'utente a /connect con client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 e scope
  3. 3. L'utente vede il dominio di destinazione e i permessi, sceglie un calendario e approva. Torna ?code=…&state=… (oppure ?error=access_denied).
  4. 4. Riscattare il codice lato server: POST /api/connect/token con client_id, code, code_verifier e redirect_uri. Risposta: calendarId, apiKey, scopes.
  5. 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": "…" }
I codici valgono 10 minuti e si riscattano una sola volta. Per i client pubblici redirect_uri deve usare https (http solo per localhost). I partner registrati con un segreto inviano client_secret al posto di code_verifier.