Referencia de la API REST

Todas las llamadas con parámetros, códigos de estado y esquemas.

Esta página describe la interfaz por completo. Si configura la API por primera vez, es mejor que empiece con la guía paso a paso.

La dirección base es /api en su propia instalación, es decir, en los ejemplos https://example.com/api. Todas las llamadas se realizan desde su servidor, no desde el navegador de sus clientes: no se envían cabeceras CORS y el token no debe incluirse en un sitio web ni en una app.

Autenticación

Cada llamada necesita un token. Lo genera en el área de administración, en Configuración → API. El token empieza por apm_, seguido de 64 caracteres, y solo se muestra una única vez. Hay exactamente un token por instalación: un token nuevo invalida inmediatamente el anterior.

Authorization: Bearer apm_ihr-token

Sin un token válido, cada llamada responde con 401 {"error":"Unauthorized"}. Si la API no está activada en el área de administración, responde con 503 API disabled.

GET/schedules

Devuelve todos los calendarios de citas de la instalación. Los valores id devueltos se utilizan en todas las demás llamadas como parámetro schedule.

Códigos de estado

Estado	Significado
200	Lista de calendarios de citas
401	Falta el token o no es válido
429	Se ha alcanzado el límite de solicitudes
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 200

{
    "data": [
        { "id": 1, "name": "Hauptstandort" },
        { "id": 2, "name": "Filiale" }
    ]
}

Llamada con curl

curl -H "Authorization: Bearer apm_ihr-token" \
  https://example.com/api/schedules

GET/reasons

Devuelve los motivos de cita (servicios) de un calendario de citas. Si el calendario no tiene motivos de cita configurados, data es un array vacío. duration es la duración en segundos.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
`schedule`	integer ≥ 1	Obligatorio	Número del calendario de citas de `GET /schedules`	`1`

Códigos de estado

Estado	Significado
200	Lista de motivos de cita (puede estar vacía)
401	Falta el token o no es válido
404	Calendario de citas no encontrado
429	Se ha alcanzado el límite de solicitudes
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 200

{
    "data": [
        {
            "id": 1,
            "name": "Beratungsgespräch",
            "description": "Standardberatung",
            "duration": 1800
        },
        {
            "id": 2,
            "name": "Folgetermin",
            "description": "",
            "duration": 900
        }
    ]
}

Llamada con curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/reasons?schedule=1"

GET/days

Devuelve los días en los que hay al menos una hora libre para este calendario de citas y este motivo de cita. El formato es AAAA-MM-DD. Hasta qué punto del futuro llega la lista lo determina la configuración del calendario de citas.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
`schedule`	integer ≥ 1	Obligatorio	Número del calendario de citas	`1`
`reason`	integer ≥ 1	Obligatorio	Número del motivo de cita de `GET /reasons`	`1`

Códigos de estado

Estado	Significado
200	Lista de días con citas libres
401	Falta el token o no es válido
404	Calendario de citas o motivo de cita no encontrado
429	Se ha alcanzado el límite de solicitudes
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 200

{
    "data": ["2026-05-23", "2026-05-24", "2026-05-26"]
}

Llamada con curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/days?schedule=1&reason=1"

GET/slots

Devuelve las horas libres de un día. Las horas indicadas son horas locales de la instalación, el formato es AAAA-MM-DD HH:MM:SS. Si ese día ya no queda nada libre, data es un array vacío.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
`schedule`	integer ≥ 1	Obligatorio	Número del calendario de citas	`1`
`reason`	integer ≥ 1	Obligatorio	Número del motivo de cita	`1`
`day`	string	Obligatorio	Día en formato `AAAA-MM-DD` de `GET /days`	`2026-05-23`

Códigos de estado

Estado	Significado
200	Lista de horas libres (puede estar vacía)
401	Falta el token o no es válido
404	Calendario de citas, motivo de cita o día no encontrado
429	Se ha alcanzado el límite de solicitudes
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 200

{
    "data": [
        "2026-05-23 09:00:00",
        "2026-05-23 09:30:00",
        "2026-05-23 10:00:00"
    ]
}

Llamada con curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/slots?schedule=1&reason=1&day=2026-05-23"

GET/forms

Devuelve los campos de formulario que deben rellenarse para reservar esta hora. Los nombres de los campos se utilizan como claves en el objeto submission de POST /bookings. Consulte siempre los campos en lugar de fijarlos en su propio programa. El campo password nunca se devuelve.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
`schedule`	integer ≥ 1	Obligatorio	Número del calendario de citas	`1`
`reason`	integer ≥ 1	Obligatorio	Número del motivo de cita	`1`
`slot`	string	Obligatorio	Hora en formato `AAAA-MM-DD HH:MM:SS`. El espacio debe codificarse como `%20`.	`2026-05-23%2009:00:00`

Códigos de estado

Estado	Significado
200	Campos de formulario, indexados por nombre de campo
401	Falta el token o no es válido
404	Calendario de citas, motivo de cita u hora no encontrado
429	Se ha alcanzado el límite de solicitudes
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 200

{
    "data": {
        "first_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Vorname",
            "required": true,
            "value": ""
        },
        "last_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Nachname",
            "required": true,
            "value": ""
        },
        "email": {
            "form_type": "textbox",
            "input_type": "email",
            "label": "E-Mail-Adresse",
            "required": false,
            "value": ""
        },
        "phone": {
            "form_type": "textbox",
            "input_type": "tel",
            "label": "Telefonnummer",
            "required": false,
            "value": ""
        }
    }
}

Llamada con curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/forms?schedule=1&reason=1&slot=2026-05-23%2009:00:00"

POST/bookings

Crea una cita. Consulte primero los campos de formulario mediante GET /forms y envíe sus valores en el objeto submission. La cabecera debe contener Content-Type: application/json.

Campos del cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
`schedule`	integer ≥ 1	Obligatorio	Número del calendario de citas	`1`
`reason`	integer ≥ 1	Obligatorio	Número del motivo de cita	`1`
`slot`	string	Obligatorio	Hora en formato `AAAA-MM-DD HH:MM:SS`, exactamente 19 caracteres	`2026-05-23 09:00:00`
`submission`	object	Obligatorio	Valores para los nombres de campo de `GET /forms`

Cuerpo de la solicitud

{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com",
        "phone": "+49 30 1234567"
    }
}

Códigos de estado

Estado	Significado
201	La cita se ha creado
400	Solicitud no válida, falta un campo obligatorio o JSON no válido
401	Falta el token o no es válido
404	Calendario de citas, motivo de cita u hora no encontrado
415	Falta `Content-Type: application/json`
429	Se ha alcanzado el límite de solicitudes
500	No se ha podido guardar el registro del cliente o la cita
503	La API no está activada o la instalación aún no ha finalizado

Respuesta 201

{
    "booking_id": 142,
    "booking_details_id": "a3f8c2d1e5b6",
    "user_id": 87,
    "slot": "2026-05-23T09:00:00Z"
}

Respuesta 400 si falta un campo obligatorio

{
    "error": "Field is required",
    "field": "email"
}

Llamada con curl

curl -X POST https://example.com/api/bookings \
  -H "Authorization: Bearer apm_ihr-token" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com"
    }
  }'

Esquemas

Las estructuras de datos que aparecen en las respuestas.

Schedule

{
    "id": integer,
    "name": string
}

Reason

{
    "id": integer,
    "name": string,
    "description": string,
    "duration": integer   // segundos
}

FormField

{
    "form_type": string,
    "input_type": string,
    "label": string,
    "required": boolean,
    "value": any
}

BookingRequest

{
    "schedule": integer,
    "reason": integer,
    "slot": "AAAA-MM-DD HH:MM:SS",
    "submission": {
        "<nombre_campo>": <valor>
    }
}

BookingResponse

{
    "booking_id": integer,
    "booking_details_id": string,
    "user_id": integer,
    "slot": "2026-05-23T09:00:00Z"   // UTC, ISO 8601
}

Error / BookingError

{
    "error": string,
    "field": string   // opcional
}

Respuestas de error comunes

Estas respuestas pueden producirse en todas las llamadas.

Estado	Significado	Explicación
401	Unauthorized	El token falta, es incorrecto o ha sido sustituido por uno nuevo. Algunos servidores eliminan la cabecera `Authorization`; en caso de duda, consulte a su proveedor.
404	Not Found	El calendario de citas, motivo de cita, día u hora solicitado no está (o ya no está) disponible. Un parámetro que falta o tiene un formato incorrecto también genera 404, no 400.
429	Too Many Requests	Se ha alcanzado el límite de 300 solicitudes por minuto y token. La cabecera `Retry-After` indica el tiempo de espera en segundos.
503	Service Unavailable	La API no está activada en el área de administración (`API disabled`) o la instalación aún no ha finalizado (`Not configured`). Ambos casos afectan a todas las llamadas.

Los errores se devuelven siempre como JSON y tienen siempre la misma forma:

{ "error": "Beschreibung des Fehlers" }

En la reserva, un error de validación indica además el campo afectado:

{ "error": "Field is required", "field": "email" }

Encontrará la lista completa de mensajes de error por llamada en la guía.

Descripción legible por máquina

Todas las llamadas se describen además en un archivo OpenAPI según la versión 3.1. Con él puede generar bibliotecas cliente o cargar la interfaz en herramientas como Postman, Insomnia o Swagger UI.

Ver openapi.json

En el archivo, en servers, figura la dirección /api. Se trata deliberadamente de una indicación relativa, para que el archivo sea válido en cualquier instalación. Por ello, introduzca en su herramienta la dirección de su propia agenda de citas, por ejemplo https://example.com/api. El mismo archivo se encuentra también en su instalación en /api/openapi.json.

Volver a la guía o a la vista general: módulo "API (interfaz)".

Arriba