REST-API einrichten und nutzen

 

REST-API einrichten und nutzen

Freie Termine abfragen und Termine buchen – direkt aus Ihrer eigenen Anwendung heraus.

Die API arbeitet mit JSON und wird über die Adresse https://example.com/api aufgerufen. Der Buchungsablauf besteht aus sechs Aufrufen, die aufeinander aufbauen: Kalender, Termingrund, Tag, Uhrzeit, Formularfelder und schließlich die Buchung. Alle Aufrufe erfolgen von Ihrem Server aus, nicht aus dem Browser Ihrer Kunden.

Schritt 1: API aktivieren und Token erzeugen

Die API ist im Auslieferungszustand abgeschaltet. Sie aktivieren sie im Administrationsbereich.

  1. Klicken Sie in der Navigation auf Konfiguration.
  2. Klicken Sie in der Unternavigation auf Allgemeine Einstellungen.
  3. Klicken Sie in der Liste auf Schnittstelle.
  4. Schalten Sie Schnittstelle aktivieren ein. Die Änderung wird sofort gespeichert.
  5. Klicken Sie auf Neuen Token generieren, um den Zugangs-Token für die Schnittstelle zu erzeugen.
  6. Kopieren Sie den angezeigten Token sofort und bewahren Sie ihn sicher auf, er wird nicht erneut angezeigt.

Bildschirmfotos

Klicken Sie in der Navigation auf Konfiguration

1

Klicken Sie in der Unternavigation auf Allgemeine Einstellungen

2

Klicken Sie in der Liste auf Schnittstelle

3

Schalten Sie Schnittstelle aktivieren ein. Die Änderung wird sofort gespeichert

4

Klicken Sie auf Neuen Token generieren, um den Zugangs-Token für die Schnittstelle zu erzeugen

5

Kopieren Sie den angezeigten Token sofort und bewahren Sie ihn sicher auf, er wird nicht erneut angezeigt

6

Das Token beginnt mit apm_, gefolgt von 64 Zeichen, und wird nur ein einziges Mal angezeigt. Im System wird ausschließlich ein Hash gespeichert, das Token selbst lässt sich später nicht mehr auslesen. Es gibt genau ein Token pro Installation: Erzeugen Sie ein neues Token, verliert das bisherige sofort seine Gültigkeit.

Das Token senden Sie bei jedem Aufruf im Kopfbereich der Anfrage mit:

Authorization: Bearer apm_ihr-token

Schritt 2: Verbindung prüfen und Terminkalender abfragen

Mit dem ersten Aufruf prüfen Sie die Verbindung und erhalten die Nummern Ihrer Terminkalender.

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

Antwort:

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

Die id des gewünschten Kalenders verwenden Sie in allen weiteren Aufrufen als Parameter schedule.

Schritt 3: Termingründe abfragen

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

Antwort:

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

duration ist die Dauer in Sekunden (1800 Sekunden entsprechen 30 Minuten). Die id verwenden Sie weiter als Parameter reason. Sind für einen Kalender keine Termingründe eingerichtet, ist data leer.

Schritt 4: Tage mit freien Terminen abfragen

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

Antwort:

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

Zurückgegeben werden nur Tage, an denen mindestens eine Terminzeit frei ist. Wie weit die Liste in die Zukunft reicht, bestimmen die Einstellungen Ihres Terminkalenders.

Schritt 5: Freie Uhrzeiten eines Tages abfragen

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

Antwort:

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

Die Zeitangaben sind Ortszeiten Ihrer Installation, das Format ist immer JJJJ-MM-TT HH:MM:SS.

Schritt 6: Formularfelder der Buchung abfragen

Welche Felder für eine Buchung benötigt werden, legen Sie selbst im Terminplaner fest. Fragen Sie die Felder deshalb immer ab, statt sie im eigenen Programm fest einzutragen. Das Leerzeichen im Parameter slot muss als %20 kodiert werden.

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

Antwort:

{
    "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": ""
        }
    }
}

Alle Felder mit "required": true müssen bei der Buchung gefüllt sein. Das Feld password wird von der API nie ausgegeben.

Schritt 7: Termin buchen

Die Buchung ist der einzige Aufruf mit der Methode POST. Der Kopfbereich muss Content-Type: application/json enthalten. In submission tragen Sie die Werte zu den Feldnamen aus Schritt 6 ein.

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

Antwort bei Erfolg (Status 201):

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

Der Termin ist damit im Terminplaner eingetragen. Die Benachrichtigungs-E-Mails werden wie bei jeder anderen Buchung verschickt.

Fehlermeldungen

Fehler werden ebenfalls als JSON ausgegeben, zum Beispiel {"error":"Unauthorized"}.

Hinweise

Zurück zur Übersicht: Modul "API (Schnittstelle)".

Nach oben