Documentation API
Intégrez termine.lol dans votre propre application.
Authentification
Les endpoints embed (Calendrier & Créneaux) nécessitent une clé API dans le header. Les clés API sont créées par calendrier et peuvent être gérées dans le tableau de bord sous l'onglet « Clés API ». Les endpoints de réservation (Réserver & Finaliser) sont publics et ne nécessitent pas de clé API — ils sont protégés par une limitation de débit.
Envoyez votre clé API dans le header x-api-key :
x-api-key: your_api_key
URL de base
Tous les endpoints utilisent l'URL de base suivante :
https://termine.lol
Heures et dates
startAt et endAt d’un rendez-vous sont l’heure locale sur place — dans le fuseau horaire du calendrier (champ timezone). Ils sont écrits au format ISO avec un Z final, mais ce n’est pas de l’UTC : « 2026-10-01T09:00:00.000Z » signifie 9 h dans le calendrier, où que se trouve le serveur. Il en va de même pour time et slotIndex des créneaux libres (slotIndex compte les quarts d’heure depuis minuit, 36 = 09:00).
Les vrais instants en UTC sont en revanche createdAt, submittedAt, confirmedAt et reservationExpiresAt.
Gestion des erreurs
Toutes les erreurs sont renvoyées en JSON avec un champ `error` :
{
"error": "Ungültiger API-Key"
}Codes de statut HTTP
- 400 — Requête invalide (paramètres manquants)
- 401 — Clé API invalide ou manquante
- 403 — Clé API non autorisée pour ce calendrier / limite atteinte
- 404 — Ressource non trouvée
- 409 — Conflit (créneau déjà occupé)
- 410 — réservation expirée (lors de la finalisation)
- 429 — Trop de requêtes (limite de débit)
- 500 — Erreur interne du serveur
- En cas de saisie invalide (400), error est un objet contenant une liste de messages par champ, et non un texte.
- 429 contient en plus retryAfter (secondes) et l’en-tête Retry-After.
- Les messages d’erreur sont en allemand. La réservation et la finalisation répondent dans la langue donnée par Accept-Language ou ?lang= (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Flux de réservation
Le flux typique d'une réservation via l'API :
- 1. Récupérer le calendrier → Obtenir les membres et types de rendez-vous
- 2. Récupérer les créneaux → Charger les créneaux disponibles pour un jour
- 3. Réserver un créneau → Créer une réservation de 10 minutes
- 4. Finaliser la réservation → Envoyer les données client, l'e-mail de confirmation est envoyé
- 5. Le client confirme → En cliquant sur le lien dans l'e-mail, la réservation est confirmée
Récupérer le calendrier
Renvoie les informations de base d'un calendrier, y compris les membres actifs et les types de rendez-vous.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Paramètres de chemin
| Parameter | Description |
|---|---|
id* | L'ID du calendrier |
Réponse
{
"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": ["..."]
}
]
}
}Récupérer les créneaux disponibles
Renvoie les créneaux horaires disponibles pour un jour et un type de rendez-vous donnés. Sans `personUserId`, tous les membres sont interrogés et les résultats fusionnés (`byPerson` contient le détail).
curl -H "x-api-key: your_api_key" \ "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2026-03-15&appointmentTypeId=TYPE_ID"
Paramètres de requête
| Parameter | Description |
|---|---|
id* | L'ID du calendrier (string) |
date* | Date au format YYYY-MM-DD (string) |
appointmentTypeId* | ID du type de rendez-vous (string) |
personUserId | ID du membre (string, optionnel — par défaut : « any » = tous les membres) |
Réponse
{
"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" }
]
}
]
}
}Réserver un créneau
Réserve un créneau horaire pour 10 minutes. La réservation doit être finalisée dans ce délai. Ce endpoint ne nécessite pas de clé API — il est public et protégé par limitation de débit (20 requêtes/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
}'Corps de la requête (JSON)
| Parameter | Description |
|---|---|
calendarId* | ID du calendrier (string) |
appointmentTypeId* | ID du type de rendez-vous (string) |
date* | Date au format YYYY-MM-DD (string) |
startSlot* | Index du créneau 0–95, chaque 15 min (number) |
personUserId | ID du membre (string, optionnel — sans indication, attribution automatique) |
appointmentMode | Mode de rendez-vous : « online » ou « in_person » (string, optionnel — uniquement pour les types hybrides) |
Réponse (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 }
]
}
}Finaliser la réservation
Envoie les données du client pour une réservation réservée. Le client recevra un e-mail de confirmation avec un lien de confirmation. Ce endpoint ne nécessite pas de clé API — il est public et protégé par limitation de débit (5 requêtes/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"
}
}'Corps de la requête (JSON)
| Parameter | Description |
|---|---|
bookingId* | ID de la réservation issu de la réservation (string) |
customerEmail* | E-mail du client (string) |
customerData* | Données du client en tant qu'objet — les clés correspondent aux valeurs `key` des `fields` de la réservation (object) |
Réponse (200 OK)
{
"data": {
"success": true,
"message": "Bestätigungs-E-Mail gesendet"
}
}POST /api/public/bookings/abandon
Libère immédiatement une réservation lorsque le client abandonne. Corps : { "bookingId": "…" }. Sans cet appel, elle expire d’elle-même après 10 minutes.
Limitation de débit
Les endpoints API sont soumis à des limites de débit. Les limites varient selon l'endpoint :
- 120 requêtes / minute par clé (calendrier et créneaux)
- 20 réservations et 5 finalisations / minute par adresse IP
Autorisations (scopes)
Chaque clé API porte des autorisations. Les clés sans autorisations enregistrées (toutes celles créées avant les scopes) comptent comme « embed ». Si une clé n'a pas l'autorisation requise, l'API répond 403 avec `insufficient_scope`.
- embed — calendrier, types de rendez-vous et créneaux libres (endpoints d'intégration)
- bookings:read — lister et lire les réservations, données clients incluses
- bookings:write — annuler, déplacer, définir le statut et la note, renvoyer la confirmation
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Quelle autorisation pour quel endpoint
- embed — GET /api/embed/calendars/:id, …/slots et GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings et GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots et POST …/email
API partenaires
Endpoints pour les intégrations qui affichent et gèrent les rendez-vous (p. ex. le plugin WordPress). Tous se trouvent sous /api/partner/, attendent la clé API dans l'en-tête x-api-key et se réfèrent toujours au calendrier de la clé — il n'y a pas d'ID de calendrier dans le chemin.
GET /api/partner/calendar
Le calendrier de la clé : titre, fuseau horaire, membres, types de rendez-vous, champs du formulaire et autorisations de la clé.
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
Lister les réservations. Par défaut : tous les statuts sauf reserved et expired, 25 par page.
curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"
Paramètres de requête
- from, to — date ISO, plage sur startAt
- status — répétable : reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past ou future
- limit (1–100, 25 par défaut), offset (0 par défaut)
- q — recherche sur l'adresse e-mail et le nom
{
"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
Une réservation avec tous les détails. Si elle n'appartient pas au calendrier de la clé, l'API répond 404.
PATCH /api/partner/bookings/:id
Modifier une réservation, avec la même charge utile que le tableau de bord.
{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }- Une seule modification est effectuée par requête, dans cet ordre de priorité : status, reschedule, internalNote, message. La réponse est la réservation modifiée.
- completed et no_show ne sont possibles qu’à partir de confirmed (et l’un vers l’autre) ; cancelled fonctionne depuis n’importe quel statut. Un déplacement vers un créneau non libre répond 400.
GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD
Créneaux libres pour déplacer une réservation un jour donné (?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
Renvoyer l'e-mail de confirmation : pour les réservations confirmées avec un nouveau lien d'annulation, pour celles en attente avec un nouveau lien de confirmation.
{ "data": { "sent": true, "kind": "confirmed" } }Flux de connexion (OAuth avec PKCE)
Au lieu de copier une clé à la main, une application partenaire peut connecter l'utilisateur d'un clic. Les clients publics (p. ex. un plugin sur des domaines tiers) n'ont pas besoin de secret ; ils sécurisent le flux avec PKCE (S256).
- 1. Générer code_verifier (43–128 caractères) et state ; code_challenge = base64url(sha256(code_verifier))
- 2. Envoyer l'utilisateur vers /connect avec client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 et scope
- 3. L'utilisateur voit le domaine cible et les autorisations, choisit un calendrier et approuve. Retour : ?code=…&state=… (ou ?error=access_denied).
- 4. Échanger le code côté serveur : POST /api/connect/token avec client_id, code, code_verifier et redirect_uri. Réponse : calendarId, apiKey, scopes.
- 5. À la déconnexion, appeler POST /api/connect/revoke avec client_id et apiKey pour ne laisser aucune clé.
https://termine.lol/fr/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": "…" }