Options
All
  • Public
  • Public/Protected
  • All
Menu

@termingo/termingo-planner-api-ts

TERMINGO Kalender

Schnittstellendokumentation

Dieses Dokument beschreibt die Schnittstelle zum Zugriff auf Kalenderdaten der TERMINGO-Kalenderanwendung. Es enthält die folgenden Themen:

Diese Dokumentation beschreibt die Legacy-Schnittstelle für ISB-Kassensysteme. Für die Dokumentation der aktuellen Schnittstelle besuchen Sie bitte docs.calendar.api.termingo.de.

Allgemeines

Diese Dokumentation verwendet die folgenden grafischen Elemente zur Hervorhebung:

Dringende Information oder dringender Hinweis.
Wichtige Information oder wichtiger Hinweis.
Allgemeine Information oder allgemeiner Hinweis.
  • Beispiel zum aktuellen Kontext dieser Dokumentation.
  • Listet die verwendeten Routen auf.
  • Die gekennzeichnete Eigenschaft wird nur mit dem passenden Expand-Parameter ermittelt.
  • Links zu weiterführenden Informationen.

Interner Verweis Verweist auf einen Bestandteil dieser Dokumentation.

Externer Verweis Verweist auf eine Webseite außerhalb dieser Dokumentation.

Unveränderlichkeit Bestimmte Modelle und Datensätze können nicht verändert werden. Dies dient der Nachvollziehbarkeit und der Validität existierender Datensätze. Stattdessen wird bei Aktualisierungen ein neuer Datensatz generiert und der alte Datensatz gesperrt. Dies führt zu neuen internen IDs!

Externe Referenzen

Fast alle filialspezifischen Objekte stellen mit der Eigenschaft integrationId die Möglichkeit zum Speichern einer externen Referenz zur Verfügung. Diese Integrationsschlüssel sind als 10-stellige, vorzeichenlose Nummern (Wertebereich 0 .. 10 Milliarden - 1) pro Objekttyp und Filiale eindeutig zu belegen, da dieser Wert in der Kalenderanwendung indiziert wird. Die Verwendung längerer Integrationsschlüssel (mehr als 10 Ziffern) wird von der API nicht akzeptiert und mit einer Fehlermeldung quittiert.

Objekt-Adressierung über ID in der URL

Der Großteil der manipulativen Routen (POST, DELETE) erfordert die Angabe der ID des betroffenen Objekts als dynamischen Bestandteil der URL. Bei einigen GET-Routen ist diese Form der Einschränkung per ID optional möglich. In dieser Dokumentation werden diese ID-Bestandteile als Platzhalter in geschweiften Klammern dargestellt: {objectId}

Die Angabe verweist standardmäßig auf die interne, numerische ID des Objekts in der Kalenderanwendung. Bei Objekten welche über eine integrationId verfügen kann zudem mit Hilfe des Präfix ref: auch die externe ID für die Eingrenzung verwendet werden.

  • Zugriff auf die Dienstleistung mit der internen ID 1234
  • GET /management/service/1234
  • Zugriff auf den Mitarbeiter mit der integrationId 87050021
  • DELETE /management/employee/ref:87050021

Session-Handling mit JSON Web Token

Nach der erfolgreichen Authentifizierung erfolgt das Session Handling über einen JSON Web Token (JWT). Implementierungen in verschiedenen Programmiersprachen werden auf der JWT-Homepage aufgelistet.

Der Token hat folgenden Payload:

{
  "iss": "termingo-planner-api",
  "iat": 1516239022,
  "exp": 1516259022,
  "version": "1.2.345"
}

Die Eigenschaften im Payload haben folgende Bedeutung:

Der JSON Web Token, der in den HTTP Headers der Antwort der Authentifizierungsroute nach erfolgreicher Authentifizierung zurückgeliefert wird. Dieser Token muss bei jedem nachfolgenden API-Aufruf als HTTP-Header X-Auth-Token mitgesendet werden.

Wenn der übermittelte Token ungültig oder abgelaufen ist, reagieren die Routen mit dem HTTP Status Code 401. Durch erneuten Aufruf der Authentifizierungsroute kann dann ein neuer, gültiger Token ausgestellt werden.

Authentifizierung

Die Authentifizierung erfolgt über den Austausch eines Hashes eines Filial-spezifischen API-Keys.

API-Key

Der API-Key ist ein global eindeutiger Identifier (GUID, Global Unique ID). Jeder Store erhält für Zugriffe auf die Kalenderdaten einen eigenen API-Key.

Der API-Key wird während der Initialisierung des Kalenders automatisch generiert. Optional kann der Filiale durch ein Passwort den Zugriff zusätzlich schützen. Details dazu siehe auch Ersteinrichtung.

Steuerung der API-Aufrufe

Die API-Aufrufe können mit zusätzlichen Parametern als URL Query Part versehen werden. Die Angabe erfolgt im üblichen Format ?param1=value1&param2=value2&...&paramN=valueN.

Es ist darauf zu achten, dass Sonderzeichen in ihren entsprechenden Entitäten übermittelt werden.

Allgemeine Parameter

Die folgenden allgemeinen Parameter können bei jedem Aufruf übergeben werden.

correlation string

Die zu verwendende Vorgangs-ID. Wird keine Vorgangs-ID angegeben, wird automatisch eine ID erzeugt.

Wichtig: Vorgangs-IDs sollten eindeutig sein und aus nicht mehr als 50 Zeichen bestehen. Die Verwendung nicht eindeutiger Vorgang-IDs kann zu unerwarteten Ergebnissen führen.
skip number

Die bei der Datenermittlung zu überspringenden Datensätze. Wird ignoriert, wenn der Aufruf keine Auflistung an Datensätzen ermittelt.

limit number

Die zu maximale Anzahl der zu ermittelnden Datensätze. Wird ignoriert, wenn der Aufruf keine Auflistung an Datensätzen ermittelt.

expand string

Die kommaseparierte Liste der zu erweiternden Eigenschaften bei der Datenermittlung. Welche Eigenschaften erweitert werden können ist bei den entsprechenden Routen vermerkt.

Ergebnis der API-Aufrufe

Jeder API-Aufruf wird mit einem entsprechenden HTTP-Statuscode und einem generischen Ergebnisobjekt quittiert. Das Ergebnisobjekt liefert im Fehlerfall zusätzlich zum HTTP-Statuscode einen anwendungsbezogenen Fehlercode.

Allgemeine Response Status Codes

Die folgenden HTTP Status Codes werden allgemein verwendet. Wenn eine Route zusätzliche HTTP Status Codes verwendet, ist dies bei der jeweiligen Route angegeben.

200 Der Vorgang wurde erfolgreich bearbeitet.

201 Der Vorgang wurde erfolgreich bearbeitet und es wurde ein neues Element angelegt. Dies wird statt dem Status Code 200 für POST-Requests gesendet, bei denen ein Element in der Datenbank angelegt wurde.

204 Der Vorgang wurde erfolgreich bearbeitet und liefert keine Daten zurück.

304 Der Vorgang wurde erfolgreich abgebrochen, weil keine zu verarbeitenden Daten gefunden wurden. Dies wird in der Regel gesendet, wenn kein Update eines bestehenden Datensatzes möglich war.

401 Nicht angemeldet. Bitte mit der entsprechenden Route anmelden.

403 Die mitgelieferten Anmeldedaten sind nicht korrekt, abgelaufen oder es fehlen Berechtigungen, um im aktuellen Kontext auf die Route zuzugreifen.

404 Das angegebene Objekt wurde nicht gefunden. Dies geschieht in der Regel bei Routen, die eine ID enthalten und diese ID nicht aufgelöst werden kann bzw. kein passender Datensatz existiert.

409 Der Vorgang wurde abgebrochen, da es Konflikte mit zwischenzeitlichen Änderungen gibt. Dies geschieht in der Regel bei Routen, die einen Datensatz aktualisieren sollen der zuvor anderweitig verändert wurde. Um das Problem zu beheben, bitte zunächst Datensatz abrufen.

415 Die übermittelten Daten haben das falsche oder ein unbekanntes Datenformat.

424 Der Vorgang wurde wegen einer fehlenden Vorraussetzung abgebrochen. Dies deutet normalerweise auf einen Validierungsfehler hin.

500 Bei der Verarbeitung des Requests ist ein Fehler aufgetreten.

501 Die aufgerufene Route existiert nicht.

503 Der Endpunkt steht im Moment aus technischen Gründen nicht zur Verfügung. Der Aufruf sollte zu einem späteren Zeitpunkt erneut übermittelt werden.

Sicherheitsmaßnahmen

Zur Sicherstellung der Betriebsfähigkeit und zur Vermeidung von Datenabzug ist die API durch verschiedene technische Maßnahmen abgesichert. Die genaue Konfiguration der Sicherheitsparameter kann beim Betreiber der API angefragt werden.

Anfragelimitierung Pro zugreifendem Endgerät wird nur eine bestimmte Anzahl an Requests in einem bestimmten Zeitfenster erlaubt. Wenn Sie dieses Limit überschreiten, wird Ihr Client blockiert und Sie erhalten eine entsprechende Fehlermeldung. Bitte passen Sie in einem solchen Fall Ihre Requests entsprechend an oder senden Sie Ihre Requests nicht direkt hintereinander.
Empfehlung Nutzen Sie, sofern vorhanden, bei verändernden Routen die Variante mit mehreren Eingabeobjekten um bei Massenimports und -updates nicht von der Anfragelimitierung geblockt zu werden.

Routen

Im Folgenden werden die Routen der RESTful-Schnittstelle für den Zugriff auf die Kalenderdaten beschrieben.

Session-Handling

Management

Die folgenden Routen stehen für die Konfiguration des Filialkalenders zur Verfügung.

Filiale - Allgemein
DELETE /management/store

Entfernt die Kassenintegration für die Filiale.

VORSICHT! Gelöschte Elemente können nur vom Administrator manuell wiederhergestellt werden!
  • URL-Parameter
    • disable void Optional. Wenn angegeben wird die Filiale komplett deaktiviert und für Kalendernutzung und Online-Buchung gesperrt.

    siehe Allgemeine Parameter

  • Request Body

    -

  • Response Body

    IApiResponseModel<void>

Terminstati
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/store/{dateStateId}

Aktualisiert den Terminstatus mit der ID {dateStateId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Unveränderlichkeit Bei Aktualisierung des Namens wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
DELETE /management/date-states/{dateStateId}

Löscht bzw. deaktiviert den Terminstatus mit der ID {dateStateId}.

VORSICHT! Gelöschte Elemente können nur vom Administrator manuell wiederhergestellt werden!
Globale, filialunabhängige Terminstati können nicht gelöscht werden.
Nach dem Löschen des letzten Terminstatus einer Filiale werden die Standard-Stati wiederhergestellt.

Dienstleistungskategorien
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/categories/{categoryId}

Aktualisiert die Dienstleistungskategorie mit der ID {categoryId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!

Dienstleistungen
GET /management/services/{serviceId}

Liefert die Dienstleistung mit der ID {serviceId}.

  • URL-Parameter
    • serviceId number Benötigt. Die interne oder externe ID der Dienstleistung.
    • all boolean Optional. Wenn true, werden alle Dienstleistungen inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Dienstleistungen ermittelt.

    siehe auch Allgemeine Parameter

  • Request Body

    -

  • Response Body

    IApiResponseModel<IServiceModel>

Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/services/{serviceId}

Aktualisiert die Dienstleistung mit der ID {serviceId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!

Dienstleistungspakete
GET /management/packages/{packageId}

Liefert das Dienstleistungspaket mit der ID {packageId}.

  • URL-Parameter
    • packageId number Benötigt. Die interne oder externe ID des Dienstleistungspakets.
    • all boolean Optional. Wenn true, werden alle Dienstleistungspakete inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Dienstleistungspakete ermittelt.

    siehe auch Allgemeine Parameter

  • Request Body

    -

  • Response Body

    IApiResponseModel<IPackageModel>

Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/packages/{packageId}

Aktualisiert das Dienstleistungspaket mit der ID {packageId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!

Mitarbeitergruppen
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/groups/{groupId}

Aktualisiert die Mitarbeitergruppe mit der ID {groupId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!

Mitarbeiter
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
PUT /management/employees/{employeeId}

Aktualisiert den Mitarbeiter mit der ID {employeeId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!

Kunden

Die folgenden Routen stehen für den Zugriff auf die Kundendaten zur Verfügung. Um Kundendaten zu ermitteln kann zusätzlich die Kundensuche genutzt werden.

Ein direkter Abruf aller Kundendaten über die API ist aus Datenschutzgründen nicht möglich.
PUT /customers/{customerId}

Aktualisiert den Kunden mit der ID {customerId}. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route kann sowohl zum Aktualisieren als auch zum Anlegen verwendet werden. Die ID aus der URL wird dabei nicht übernommen. Der Body darf in dieser Aufrufvariante nur ein Datenobjekt enthalten.

Termine

Die folgenden Routen stehen für den Zugriff auf die Termine zur Verfügung.

GET /dates

Liefert eine Auflistung der Termine mit den per Parameter übergebenen Argumenten.

  • URL-Parameter
    • mode string Optional. Der Modus für die Terminermittlung. Mögliche Werte sind in DateQueryMode definiert. Der Standardwert ist day.
    • day Date | number Optional. Das Datum für das Termine geliefert werden sollen, Angabe im JSON-ISO-Format (yyyy-mm-dd) oder als UNIX-Zeitstempel (Sekunden seit 01.01.1970). Der Standardwert ist das aktuelle Datum.
    • type string Optional. Die Terminart, die ermittelt werden soll. Mögliche Werte sind in DateQueryType definiert. Der Standardwert ist event.
    • deleted boolean Optional. Wenn true, werden nur gelöschte Termine ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Termine ermittelt.

    siehe auch Allgemeine Parameter

  • Request Body

    -

  • Response Body
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
Anfragelimitierung Bei Masseninserts und -updates mehrere Objekte pro Request übergeben (empfohlen: 50), da sonst ggf. die Sicherheitsmaßnahmen Ihren Client blockieren.
DELETE /dates/{dateId}

Löscht bzw. deaktiviert den Termin mit der ID {dateId}.

VORSICHT! Gelöschte Termine können nicht wiederhergestellt werden. Gelöschte Kundentermine werden mit den relevanten Daten separat gesichert!
GET /conflicts

Liefert Terminkonflikte für übergebenen Termin.

  • URL-Parameter
    • dateId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Termins.

    siehe auch Allgemeine Parameter

  • Request Body

    IDateModel

  • Response Body

    IApiResponseModel<DatesDictionary>
    Der Schlüssel des Dictionarys ist die ID des Dienstleistungsschritts des Termins, zu dem Konflikte vorliegen. Der Schlüssel hat das Format s{stepId}.

Suche

Die folgenden Routen stehen für die Suche nach verschiedenen Datenobjekten zur Verfügung.

GET /search/customer

Sucht nach einem Kunden.

  • URL-Parameter
    • query string Der Suchbegriff. Es wird eine Volltextsuche durchgeführt.
    • {field} string|number Vergleicht das Feld mit den Namen {field} mit dem übergebenen Wert.

    Entweder der query oder ein field Parameter müssen verwendet werden. Mehrere Suchparameter werden mit AND kombiniert.
    siehe auch Allgemeine Parameter

  • Request Body

    -

  • Response Body

    IApiResponseModel<ICustomerModel[]>

How-To

Hier finden Sie eine Sammlung beispielhafter Anleitungen.

Ersteinrichtung

Die Ersteinrichtung des Kalenders aus der Kasse heraus erfordert einige aufeinanderfolgende API-Aufrufe. Diese werden im Folgenden beschrieben.

  1. Registrieren der Filiale
    POST /management/store
  2. Mitarbeitergruppen anlegen
    POST /management/groups
    (mindestens eine, mehrere durch wiederholte Aufrufe)
  3. Mitarbeiter anlegen
    POST /management/employees
    (mindestens einen, mehrere durch wiederholte Aufrufe)
  4. Dienstleistungskategorien anlegen
    POST /management/categories
    (mindestens eine, mehrere durch wiederholte Aufrufe)
  5. Dienstleistungen mit Schritten anlegen
    POST /management/services
    (mindestens eine, mehrere durch wiederholte Aufrufe)

Generated using TypeDoc. API-Dokumentation v2.0.1367. Zur Startseite © Copyright 2021 TERMINGO GmbH. All rights reserved.