← Volver al inicio

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
El acceso API está disponible a partir del plan Pro.
Todos los endpoints bajo /api/embed/ y /api/partner/ necesitan una clave. Las claves bloqueadas o revocadas se tratan como desconocidas (401). Usa las claves solo en tu servidor: la API no envía cabeceras CORS, así que las llamadas desde el navegador de otro dominio fallan.

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.

from y to de la lista de reservas también se leen como hora local. Envíalos sin zona horaria, p. ej. 2026-10-01 o 2026-10-01T09:00:00.

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

{
  "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. 1. Obtener calendario → Recibir miembros y tipos de cita
  2. 2. Obtener franjas → Cargar franjas horarias disponibles para un día
  3. 3. Reservar franja → Crear una reservación de 10 minutos
  4. 4. Completar reserva → Enviar datos del cliente, se envía correo de confirmación
  5. 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.

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

Parámetros de ruta

ParameterDescription
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": ["..."]
      }
    ]
  }
}
Los dos endpoints del calendario devuelven además confirmationMode («instant» o «double_opt_in») y, por tipo de cita, priceCents (precio en céntimos o null), currency y category.

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

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"

Parámetros de consulta

ParameterDescription
id*El ID del calendario (string)
date*Fecha en formato YYYY-MM-DD (string)
appointmentTypeId*ID del tipo de cita (string)
personUserIdID 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).

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

Cuerpo de la solicitud (JSON)

ParameterDescription
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)
personUserIdID del miembro (string, opcional — sin indicar se asigna automáticamente)
appointmentModeModo 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 }
    ]
  }
}
Los `fields` contienen los campos del formulario que deben completarse durante la reserva. Usa los valores `key` como claves en el objeto `customerData` al enviar.
Opcional: extraAppointmentTypeIds (hasta 4 tipos de cita más en la misma cita). calendarId también puede ser el slug del calendario.

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

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

Cuerpo de la solicitud (JSON)

ParameterDescription
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"
  }
}
La respuesta incluye confirmed: en calendarios con confirmationMode «instant» la reserva queda confirmada al momento (confirmed: true, sin correo de confirmación); en caso contrario el cliente confirma con el enlace del correo (confirmed: false).

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:


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

{
  "error": "insufficient_scope",
  "required": "bookings:read",
  "granted": ["embed"]
}
bookings:write no incluye bookings:read. Los permisos se eligen al crear la clave en el panel.

Qué permiso necesita cada endpoint


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"]
  }
}
Los dos endpoints del calendario devuelven además confirmationMode («instant» o «double_opt_in») y, por tipo de cita, priceCents (precio en céntimos o null), currency y category.

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

{
  "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
  }
}
Las reservas anonimizadas vuelven sin datos de clientes (anonymized: true).

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

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" } }
kind es «confirmed» (confirmación con enlace de cancelación) o «confirmation_request» (nuevo enlace de confirmación).
Límite por clave: 120 peticiones de lectura y 30 de escritura por minuto.

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. 1. Generar code_verifier (43–128 caracteres) y state; code_challenge = base64url(sha256(code_verifier))
  2. 2. Enviar al usuario a /connect con client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 y scope
  3. 3. El usuario ve el dominio de destino y los permisos, elige un calendario y aprueba. Vuelve ?code=…&state=… (o ?error=access_denied).
  4. 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. 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": "…" }
Los códigos valen 10 minutos y se canjean una sola vez. Para clientes públicos redirect_uri debe usar https (http solo para localhost). Los partners registrados con secreto envían client_secret en lugar de code_verifier.