← Retour à l'accueil

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
L'accès API est disponible à partir du plan Pro.
Tous les endpoints sous /api/embed/ et /api/partner/ exigent une clé. Les clés verrouillées ou révoquées sont traitées comme des clés inconnues (401). N’utilisez les clés que sur votre serveur : l’API n’envoie pas d’en-têtes CORS, les appels depuis le navigateur d’un autre domaine échouent.

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.

from et to de la liste des réservations sont eux aussi lus comme heure locale. Envoyez-les sans fuseau horaire, p. ex. 2026-10-01 ou 2026-10-01T09:00:00.

Gestion des erreurs

Toutes les erreurs sont renvoyées en JSON avec un champ `error` :

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

Codes de statut HTTP

{
  "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. 1. Récupérer le calendrier → Obtenir les membres et types de rendez-vous
  2. 2. Récupérer les créneaux → Charger les créneaux disponibles pour un jour
  3. 3. Réserver un créneau → Créer une réservation de 10 minutes
  4. 4. Finaliser la réservation → Envoyer les données client, l'e-mail de confirmation est envoyé
  5. 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.

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

Paramètres de chemin

ParameterDescription
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": ["..."]
      }
    ]
  }
}
Les deux endpoints du calendrier renvoient aussi confirmationMode (« instant » ou « double_opt_in ») et, par type de rendez-vous, priceCents (prix en centimes ou null), currency et category.

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

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"

Paramètres de requête

ParameterDescription
id*L'ID du calendrier (string)
date*Date au format YYYY-MM-DD (string)
appointmentTypeId*ID du type de rendez-vous (string)
personUserIdID 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).

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

Corps de la requête (JSON)

ParameterDescription
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)
personUserIdID du membre (string, optionnel — sans indication, attribution automatique)
appointmentModeMode 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 }
    ]
  }
}
Les `fields` contiennent les champs de formulaire à remplir lors de la réservation. Utilisez les valeurs `key` comme clés dans l'objet `customerData` lors de la soumission.
Facultatif : extraAppointmentTypeIds (jusqu’à 4 types de rendez-vous supplémentaires dans le même rendez-vous). calendarId peut aussi être le slug du calendrier.

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

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

Corps de la requête (JSON)

ParameterDescription
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"
  }
}
La réponse contient confirmed : pour les calendriers en confirmationMode « instant », la réservation est confirmée immédiatement (confirmed: true, pas d’e-mail de confirmation nécessaire) ; sinon le client confirme via le lien de l’e-mail (confirmed: false).

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 :


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

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write n'inclut pas bookings:read. Les autorisations se choisissent à la création de la clé dans le tableau de bord.

Quelle autorisation pour quel endpoint


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"]
  }
}
Les deux endpoints du calendrier renvoient aussi confirmationMode (« instant » ou « double_opt_in ») et, par type de rendez-vous, priceCents (prix en centimes ou null), currency et category.

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

{
  "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
  }
}
Les réservations anonymisées reviennent sans données clients (anonymized: true).

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

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" } }
kind vaut « confirmed » (confirmation avec lien d’annulation) ou « confirmation_request » (nouveau lien de confirmation).
Limite par clé : 120 requêtes de lecture et 30 d'écriture par minute.

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. 1. Générer code_verifier (43–128 caractères) et state ; code_challenge = base64url(sha256(code_verifier))
  2. 2. Envoyer l'utilisateur vers /connect avec client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 et scope
  3. 3. L'utilisateur voit le domaine cible et les autorisations, choisit un calendrier et approuve. Retour : ?code=…&state=… (ou ?error=access_denied).
  4. 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. 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": "…" }
Les codes sont valables 10 minutes et utilisables une seule fois. Pour les clients publics, redirect_uri doit utiliser https (http uniquement pour localhost). Les partenaires enregistrés avec un secret envoient client_secret au lieu de code_verifier.