Documentación API
Integra termine.lol en tu propia aplicación.
Autenticación
Los endpoints embed (Calendario & Franjas) requieren una clave API en el header. Las claves API se crean por calendario y se pueden gestionar en el panel bajo la pestaña "Claves API". Los endpoints de reserva (Reservar & Completar) son públicos y no requieren clave API — están protegidos por limitación de tasa.
Envía tu clave API en el header x-api-key:
x-api-key: your_api_key
URL base
Todos los endpoints utilizan la siguiente URL base:
https://termine.lol
Fechas y horas
startAt y endAt de una cita son la hora local del lugar, en la zona horaria del calendario (campo timezone). Se escriben en formato ISO con una Z al final, pero no son UTC: «2026-10-01T09:00:00.000Z» significa las 9:00 en el calendario, esté donde esté el servidor. Lo mismo vale para time y slotIndex de las franjas libres (slotIndex cuenta cuartos de hora desde medianoche, 36 = 09:00).
En cambio, createdAt, submittedAt, confirmedAt y reservationExpiresAt son instantes reales en UTC.
Gestión de errores
Todos los errores se devuelven como JSON con un campo `error`:
{
"error": "Ungültiger API-Key"
}Códigos de estado HTTP
- 400 — Solicitud inválida (faltan parámetros)
- 401 — Clave API inválida o faltante
- 403 — Clave API no autorizada para este calendario / límite alcanzado
- 404 — Recurso no encontrado
- 409 — Conflicto (franja horaria ya ocupada)
- 410 — reserva caducada (al completar una reserva)
- 429 — Demasiadas solicitudes (límite de tasa)
- 500 — Error interno del servidor
- Con datos no válidos (400), error es un objeto con una lista de mensajes por campo, no un texto.
- 429 incluye además retryAfter (segundos) y la cabecera Retry-After.
- Los mensajes de error están en alemán. Reservar y completar responden en el idioma indicado por Accept-Language o ?lang= (de, en, fr, es, it, tr).
{
"error": { "customerEmail": ["Ungültige E-Mail-Adresse"] }
}
{ "error": "rate_limited", "retryAfter": 42 }Flujo de reserva
El flujo típico de una reserva a través de la API:
- 1. Obtener calendario → Recibir miembros y tipos de cita
- 2. Obtener franjas → Cargar franjas horarias disponibles para un día
- 3. Reservar franja → Crear una reservación de 10 minutos
- 4. Completar reserva → Enviar datos del cliente, se envía correo de confirmación
- 5. El cliente confirma → Al hacer clic en el enlace del correo, se confirma la reserva
Obtener calendario
Devuelve la información básica de un calendario, incluyendo los miembros activos y los tipos de cita.
curl -H "x-api-key: your_api_key" \ https://termine.lol/api/embed/calendars/CALENDAR_ID
Parámetros de ruta
| Parameter | Description |
|---|---|
id* | El ID del calendario |
Respuesta
{
"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": ["..."]
}
]
}
}Obtener franjas horarias disponibles
Devuelve las franjas horarias disponibles para un día específico y un tipo de cita. Sin `personUserId`, se consultan todos los miembros y se fusionan los resultados (`byPerson` contiene el desglose).
curl -H "x-api-key: your_api_key" \ "https://termine.lol/api/embed/calendars/CALENDAR_ID/slots?date=2026-03-15&appointmentTypeId=TYPE_ID"
Parámetros de consulta
| Parameter | Description |
|---|---|
id* | El ID del calendario (string) |
date* | Fecha en formato YYYY-MM-DD (string) |
appointmentTypeId* | ID del tipo de cita (string) |
personUserId | ID del miembro (string, opcional — por defecto: "any" = todos los miembros) |
Respuesta
{
"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" }
]
}
]
}
}Reservar franja horaria
Reserva una franja horaria durante 10 minutos. La reserva debe completarse dentro de este tiempo. Este endpoint no requiere clave API — es público y está protegido por limitación de tasa (20 solicitudes/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
}'Cuerpo de la solicitud (JSON)
| Parameter | Description |
|---|---|
calendarId* | ID del calendario (string) |
appointmentTypeId* | ID del tipo de cita (string) |
date* | Fecha en formato YYYY-MM-DD (string) |
startSlot* | Índice del slot 0–95, cada 15 min (number) |
personUserId | ID del miembro (string, opcional — sin indicar se asigna automáticamente) |
appointmentMode | Modo de cita: "online" o "in_person" (string, opcional — solo para tipos híbridos) |
Respuesta (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 }
]
}
}Completar reserva
Envía los datos del cliente para una reserva reservada. El cliente recibirá un correo de confirmación con un enlace de confirmación. Este endpoint no requiere clave API — es público y está protegido por limitación de tasa (5 solicitudes/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"
}
}'Cuerpo de la solicitud (JSON)
| Parameter | Description |
|---|---|
bookingId* | ID de la reserva de la reservación (string) |
customerEmail* | Correo electrónico del cliente (string) |
customerData* | Datos del cliente como objeto — las claves corresponden a los valores `key` de los `fields` de la reservación (object) |
Respuesta (200 OK)
{
"data": {
"success": true,
"message": "Bestätigungs-E-Mail gesendet"
}
}POST /api/public/bookings/abandon
Libera una reserva de inmediato cuando el cliente abandona. Cuerpo: { "bookingId": "…" }. Sin esta llamada caduca sola a los 10 minutos.
Limitación de tasa
Los endpoints API tienen límites de tasa. Los límites varían según el endpoint:
- 120 solicitudes / minuto por clave (calendario y franjas)
- 20 reservas y 5 reservas completadas / minuto por dirección IP
Permisos (scopes)
Cada clave API lleva permisos. Las claves sin permisos guardados (todas las creadas antes de los scopes) cuentan como "embed". Si a una clave le falta el permiso necesario, la API responde 403 con `insufficient_scope`.
- embed — calendario, tipos de cita y huecos libres (endpoints de incrustación)
- bookings:read — listar y leer reservas, incluidos los datos de clientes
- bookings:write — cancelar, reprogramar, fijar estado y nota, reenviar la confirmación
{
"error": "insufficient_scope",
"required": "bookings:read",
"granted": ["embed"]
}Qué permiso necesita cada endpoint
- embed — GET /api/embed/calendars/:id, …/slots y GET /api/partner/calendar
- bookings:read — GET /api/partner/bookings y GET /api/partner/bookings/:id
- bookings:write — PATCH /api/partner/bookings/:id, GET …/available-slots y POST …/email
API para partners
Endpoints para integraciones que muestran y gestionan citas (p. ej. el plugin de WordPress). Todos están bajo /api/partner/, esperan la clave API en la cabecera x-api-key y se refieren siempre al calendario de la clave — no hay ID de calendario en la ruta.
GET /api/partner/calendar
El calendario de la clave: título, zona horaria, miembros, tipos de cita, campos del formulario y los permisos de la clave.
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
Listar reservas. Por defecto: todos los estados excepto reserved y expired, 25 por página.
curl -H "x-api-key: your_api_key" "https://termine.lol/api/partner/bookings?direction=future&limit=25&offset=0"
Parámetros de consulta
- from, to — fecha ISO, rango sobre startAt
- status — repetible: reserved, pending_confirmation, confirmed, cancelled, expired, completed, no_show
- direction — past o future
- limit (1–100, por defecto 25), offset (por defecto 0)
- q — búsqueda por correo y nombre
{
"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 reserva con todos los detalles. Si no pertenece al calendario de la clave, la API responde 404.
PATCH /api/partner/bookings/:id
Modificar una reserva, con la misma carga que el panel.
{ "status": "cancelled", "message": "Leider verhindert" }
{ "status": "completed" }
{ "status": "no_show" }
{ "internalNote": "Rückruf vereinbart" }
{ "reschedule": { "date": "2026-10-02", "startSlot": 40 } }- En cada solicitud se ejecuta exactamente un cambio, con esta prioridad: status, reschedule, internalNote, message. La respuesta es la reserva modificada.
- completed y no_show solo son posibles desde confirmed (y entre sí); cancelled funciona desde cualquier estado. Mover a una hora que no está libre responde 400.
GET /api/partner/bookings/:id/available-slots?date=YYYY-MM-DD
Huecos libres para mover una reserva en un día (?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
Reenviar el correo de confirmación: en reservas confirmadas con un nuevo enlace de cancelación, en pendientes con un nuevo enlace de confirmación.
{ "data": { "sent": true, "kind": "confirmed" } }Flujo de conexión (OAuth con PKCE)
En lugar de copiar una clave a mano, una app asociada puede conectar al usuario con un clic. Los clientes públicos (p. ej. un plugin en dominios ajenos) no necesitan secreto; aseguran el flujo con PKCE (S256).
- 1. Generar code_verifier (43–128 caracteres) y state; code_challenge = base64url(sha256(code_verifier))
- 2. Enviar al usuario a /connect con client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 y scope
- 3. El usuario ve el dominio de destino y los permisos, elige un calendario y aprueba. Vuelve ?code=…&state=… (o ?error=access_denied).
- 4. Canjear el código en el servidor: POST /api/connect/token con client_id, code, code_verifier y redirect_uri. Respuesta: calendarId, apiKey, scopes.
- 5. Al desconectar, llamar a POST /api/connect/revoke con client_id y apiKey para que no quede ninguna clave.
https://termine.lol/es/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": "…" }