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:

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 bzw. bei Abfragen unter Verwendung der Änderungsverfolgung.

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.

412 Der Aktualisierungsvorgang wurde aufgrund eines Versionskonfliktes abgebrochen. Wird nur bei Verwendung des HTTP-Anfrageheaders If-Unmodified-Since und für Aktualisierungsrouten verwendet. Siehe auch Änderungsverfolgung.

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.

Änderungsverfolgung

Einige Stammdatenobjekte sowie Termine enthalten Zeitstempel zur Nachverfolgung von Änderungen (siehe ITrackModification). Die internen Zeitstempel werden automatisch vom System bei Anlage (ITrackModification.internalCreatedAt) sowie bei jeder Änderung (ITrackModification.internalModifiedAt). Außerdem stehen mit ITrackModification.externalCreatedAt und ITrackModification.externalModifiedAt zwei Zeitstempel für die optionale Speicherung von externen Zeitstempeln zur Verfügung.

Für diese Objekte bieten die Routen Unterstützung für Änderungsverfolgung nach dem ETag-Standard (MDN). Der ETag repräsentiert den aktuellsten Zeitstempel des betroffenen Objekts / der betroffenen Objekte (internalModifiedAt oder internalCreatedAt) als UNIX-Zeitstempel (UTC).

Liefert eine Route mit Änderungsverfolgung ein oder mehrere Datenobjekte zurück, wird der aktuellste Zeitstempel im HTTP-Anwortheader ETag mitgeliefert und kann (alternativ) durch Auslesen oder Enumerieren über die Eigenschaften internalModifiedAt oder internalCreatedAt ermittelt werden.

Für die Abfrage von Objekten und (optional) beim Aktualisieren von Objekten kann der zuletzt bekannte Änderungszeitstempel bei der Anfrage mitgeschickt werden, um nur geänderte Objekte abzurufen oder um bei Änderungen Versionskonflikte zu erkennen. Dazu steht der optionale URL-Parameter etag (sowie der Alias since) zur Verfügung. Alternativ kann bei diesen Routen der HTTP-Anfrageheader If-Match (MDN) sowie If-Unmodified-Since (MDN, nur für Aktualisierungen) angegeben werden. Bei der Angabe dieser HTTP-Header werden etwaige URL-Parameter etag und since ignoriert.

Der ebenfalls im ETag-Standard definierte HTTP-Anfrageheader If-None-Match wird aktuell nicht unterstützt.

Die folgenden Beispiele zeigen die Verwendung der Änderungsverfolgung für verschiedene Arten von Routen:

  • Abfrage von geänderten Objekten

    GET /route?since=1653042896 Liefert alle nach dem 20. Mai 2022, 12:34:56 Uhr MESZ (10:34 UTC bzw. GMT) angelegten oder geänderten Objekte.

    • oder alternativ mit HTTP-Anfrageheader GET /route
      If-Match: "1653042896"
  • Aktualisierung eines Objekts

    PUT /route/{itemId}?etag=1653042896 Aktualisiert das Objekt nur, wenn es sich nach dem 20. Mai 2022, 12:34:56 Uhr MESZ (10:34 UTC bzw. GMT) nicht geändert hat und liefert andernfalls den HTTP-Statuscode 412 Precondition Failed zurück.

    • oder alternativ mit HTTP-Anfrageheader PUT /route/{itemId}
      If-Unmodified-Since: "1653042896" (statt If-Unmodified-Since kann auch If-Match gesendet werden)
Die Änderungsverfolgung ist hilfreich für eine bessere Integration, z.B. um zu übetragende Datenmengen zu reduzieren, um gecachte Objekte zu synchronisieren oder um Konflikte zwischen intern und extern modifizierten Objekten zu erkennen.

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
GET /management/store

Liefert die Daten zur Filiale.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IStoreModel>

PUT /management/store

Aktualisiert die Daten der Filiale. Nur die zu ändernden Eigenschaften müssen übergeben werden.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IStoreModel

  • Response Body

    IApiResponseModel<IStoreModel>

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
POST /management/date-states

Legt einen neuen Terminstatus an.

VORSICHT! Mit dem Hinzufügen des ersten Terminstatus werden alle Standard-Stati für die Filiale deaktiviert!
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
GET /management/categories

Liefert eine Auflistung aller Dienstleistungskategorien.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • all boolean Optional. Wenn true, werden alle Kategorien inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Kategorien ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IServiceCategoryModel[]>

GET /management/categories/{categoryId}

Liefert die Dienstleistungskategorie mit der ID {categoryId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • categoryId number Benötigt. Die interne oder externe ID der Dienstleistungskategorie.
    • all boolean Optional. Wenn true, werden alle Kategorien inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Kategorien ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IServiceCategoryModel>

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
  • URL-Parameter
    • categoryId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID der Dienstleistungskategorie.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IServiceCategoryModel

  • Response Body

    IApiResponseModel<IServiceCategoryModel>

Dienstleistungen
GET /management/services

Liefert eine Auflistung aller Dienstleistungen.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • 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.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IServiceModel[]>

GET /management/services/{serviceId}

Liefert die Dienstleistung mit der ID {serviceId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • 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.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IServiceModel>

POST /management/services

Legt eine neue Dienstleistung an.

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

Legt eine neue Beziehung zu einer Mitarbeitergruppe für die Dienstleistung mit der ID {serviceId} an.

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
  • URL-Parameter
    • serviceId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID der Dienstleistung.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IServiceModel

  • Response Body

    IApiResponseModel<IServiceModel>

Dienstleistungspakete
GET /management/packages

Liefert eine Auflistung aller Dienstleistungspakete.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • 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.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IPackageModel[]>

GET /management/packages/{packageId}

Liefert das Dienstleistungspaket mit der ID {packageId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • 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.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IPackageModel>

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
  • URL-Parameter
    • packageId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Dienstleistungspakets.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IPackageModel

  • Response Body

    IApiResponseModel<IPackageModel>

Mitarbeitergruppen
GET /management/groups

Liefert eine Auflistung aller Mitarbeitergruppen.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • all boolean Optional. Wenn true, werden alle Mitarbeitergruppen inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Mitarbeitergruppen ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IEmployeeGroupModel[]>

GET /management/groups/{groupId}

Liefert die Mitarbeitergruppe mit der ID {groupId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • groupId number Benötigt. Die interne oder externe ID der Mitarbeitergruppe.
    • all boolean Optional. Wenn true, werden alle Mitarbeitergruppen inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Mitarbeitergruppen ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IEmployeeGroupModel>

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
  • URL-Parameter
    • groupId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID der Mitarbeitergruppe.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IEmployeeGroupModel;

  • Response Body

    IApiResponseModel<IEmployeeGroupModel>

Mitarbeiter
GET /management/employees

Liefert eine Auflistung aller Mitarbeiter.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • all boolean Optional. Wenn true, werden alle Mitarbeiter inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Mitarbeiter ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IEmployeeModel[]>

GET /management/employees/{employeeId}

Liefert den Mitarbeiter mit der ID {employeeId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • employeeId number Benötigt. Die interne oder externe ID des Mitarbeiters.
    • all boolean Optional. Wenn true, werden alle Mitarbeiter inklusive den inaktiven/gelöschten ermittelt. Der Standardwert ist false, d.h. es werden nur die aktiven Mitarbeiter ermittelt.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IEmployeeModel>

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
Unveränderlichkeit Bei Aktualisierung wird ein neuer Datensatz generiert und der bestehende Datensatz gesperrt. Dies führt zu einer neuen ID!
  • URL-Parameter
    • employeeId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Mitarbeiters.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IEmployeeModel

  • Response Body

    IApiResponseModel<IEmployeeModel>

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.
GET /customers/{customerId}

Liefert den Datensatz des Kunden mit der ID {customerId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • customerId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Kunden.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<ICustomerModel>

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.
Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • customerId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Kunden.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    INewCustomerModel

  • Response Body

    IApiResponseModel<ICustomerModel>

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.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • 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.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body
GET /dates/{dateId}

Liefert den Datensatz des Termins mit der ID {dateId}.

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • dateId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Termins.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<IDateModel>

PUT /dates/{dateId}

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

Diese Route unterstützt Änderungsverfolgung über das ITrackModification-Interface und optionale URL-Parameter oder HTTP-Header.
  • URL-Parameter
    • dateId number Benötigt (wenn nicht in Request Body angegeben). Die interne oder externe ID des Termins.
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Werden durch die Einschränkung keine Ergebnisobjekte gefunden, liefert die Route 304 Not Modified zur Unterstützung von Cache-Mechanismen.
    • since number Optional. Alias für etag.

    siehe auch Allgemeine Parameter

  • Request Body

    IDateModel \ IDateModel[]

  • Response Body

    IApiResponseModel<IDateModel \ IDateModel[]>

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!
Die Angabe des Terminstatus über state oder state_id kann filialabhängig erforderlich sein. Über die allgemeinen Filialeinstellungen kann dies geprüft werden.
  • URL-Parameter
    • dateId number Benötigt. Die interne oder externe ID des Termins.
    • state string Optional. Die Kategorie des Terminstatus für den gelöschten Termin. Erlaubt sind nur Terminstati, die den (Termin abschließen).
    • state_id number Optional, wird bei der Angabe von state ignoriert. Die interne ID des Terminstatus für den gelöschten Termin. Erlaubt sind nur Terminstati, die den (Termin abschließen).
    • reason string Optional. Kurzbeschreibung des Löschgrundes (Freitext).

    siehe auch Allgemeine Parameter

  • Request Body
  • Response Body

    IApiResponseModel<boolean>

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[]>

Sonstige Routen
GET /changes

Liefert alle Zeitstempel der letzten Änderungen für einzelne Objekttypen. Bestandteil der Änderungsverfolgung.

  • Diese Route unterstützt beim Datenabruf die folgenden Werte für den Expand-Parameter:
  • categories - Liefert die Auflistung modifiedCategories mit den neuen und geänderten Dienstleistungskategorien seit der letzten Abfrage
  • services - Liefert die Auflistung modifiedServices mit den neuen und geänderten Dienstleistungen seit der letzten Abfrage
  • packages - Liefert die Auflistung modifiedPackages mit den neuen und geänderten Dienstleistungspaketen seit der letzten Abfrage
  • groups - Liefert die Auflistung modifiedGroups mit den neuen und geänderten Mitarbeitergruppen seit der letzten Abfrage
  • employees - Liefert die Auflistung modifiedEmployees mit den neuen und geänderten Mitarbeitern seit der letzten Abfrage
  • dates - Liefert die Auflistung modifiedDates mit den neuen und geänderten Terminen seit der letzten Abfrage
Die Angabe des Zeitpunkts der letzten Abfrage über das ITrackModification-Interface ist bei Verwendung des Expand-Parameters erforderlich (entweder URL-Parameter oder HTTP-Header).
  • URL-Parameter
    • etag number Optional. Der UNIX-Zeitstempel (UTC) zum Einschränken der Ergebnismenge anhand der letzten Änderung. Siehe Änderungsverfolgung. Muss bei Verwendung des Expand-Parameter angeben werden.
    • since number Optional. Alias für etag.
    • days number Optional. Für die Kombination mit expand=dates. Schränkt die Liste der zurückgelieferten Termine in IAllModificationTimestamps.modifiedDates auf die angegebene Anzahl Tage ab heute ein (0 - nur heute, 1 - heute und morgen, usw.).
  • Request Body
  • Response Body

    IApiResponseModel<IAllModificationTimestamps[]>

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.1816. Zur Startseite © Copyright 2023 TERMINGO GmbH. All rights reserved.