Zum Hauptinhalt springen

REST API

Generelle Informationen​

Was ist die REST API?​

DocBee stellt eine RESTful API mit sogenannten Endpoints bereit, mit deren Hilfe Sie Daten abfragen, anlegen, editieren und löschen können.

Wann sollten Sie die REST API verwenden?​

Falls einer oder mehrere der folgenden Punkte zutreffen, empfehlen wir den Einsatz der REST API.

  • Sie wollen ein externes System wie z.B. ein noch nicht unterstütztes ERP System anbinden
  • Sie wollen weitere Automatisierung-Schritte vornehmen, die nicht durch Externe Ereignisse oder Automatisierungen gelöst werden können.

Allgemein​

Anmeldung​

Hinweis: Sie können auch direkt in DocBee unter Mein Profil > API Token Authentifizierungs-Token erzeugen, dann wird die Anmeldung über die REST API nicht benötigt und Sie können diesen Schritt überspringen

Um mit der REST API arbeiten zu können, muss zunächst ein Authentifizierungs-Token erzeugt werden, der bei jedem anderen Aufruf mitgeliefert werden muss.

Um einen Authentifizierungs-Token zu erhalten, muss ein HTTP POST an den speziellen Endpoint restApi/login gesendet werden und mit folgendem JSON Payload (Wobei <BENUTZERNAME> und <PASSWORT> durch die Zugangsdaten eines Benutzers ersetzt werden müssen):

{
  "username": "<BENUTZERNAME>",
  "password": "<PASSWORT>",
  "lifeTime": 15,
  "lifeTimeRefresh": true
}

Hinweis: Die Eigenschaft lifeTime definiert, wie lange der Token in Minuten gültig ist und die Eigenschaft lifeTimeRefresh definiert, ob jede Anfrage an die REST API die Gültigkeit des Tokens wieder um den Wert, der in lifeTime eingestellt ist, verlängern soll.

Beispiel (curl)​

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "username": "<BENUTZERNAME>", \ 
   "password": "<PASSWORT>", \ 
   "lifeTime": 15, \ 
   "lifeTimeRefresh": true \ 
 }' 'https://my.docbee.com/restApi/login'

Als Antwort liefert DocBee nun entweder einen HTTP STATUS 401, falls die Zugangsdaten nicht korrekt sein sollten, oder ein JSON Objekt mit folgendem Aufbau.

{
  "access_token": "<ACCESS_TOKEN>",
  "username": "<BENUTZERNAME>",
  "expire_date": "2019-09-28T14:15:00.000Z",
  "token_type": "Bearer",
  "id": <BENUTZER_ID>
}

Die Antwort enthält den Authentifizierungs-Token in der Eigenschaft access_token. Dieser muss bei jedem weiteren Aufruf als Authorization-Header mit folgendem Wert Bearer <ACCESS_TOKEN> mitgesendet werden.

Hinweis: Die REST API arbeitet mit der Berechtigung des Benutzers, der beim Login verwendet wurde. Falls der Benutzer keine Berechtigung auf bestimmte Datensätze hat, gilt dies auch für die REST API.

Daten abfragen​

Um Daten über eine REST API abzufragen, werden HTTP GET Aufrufe an den jeweiligen Endpoint geschickt.

Bei der Abfrage von Daten wird zwischen einzelnen Datensätzen und einer Liste von Datensätzen unterschieden.

Beispiel Liste (curl)​

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <ACCESS_TOKEN>' 'https://my.docbee.com/restApi/v1/customer'

Daten anlegen​

Um einen neuen Datensatz anzulegen, wird ein HTTP POST Aufruf mit einem JSON Payload erzeugt und an den jeweiligen Endpoint geschickt.

Daten editieren​

Um einen existierenden Datensatz zu editieren, wird ein HTTP PUT Aufruf mit einem JSON Payload an den jeweiligen Endpoint geschickt.

Daten löschen​

Um einen existierenden Datensatz zu löschen, wird ein HTTP DELETE Aufruf an den jeweiligen Endpoint geschickt.

Hinweis: Nicht alle Endpoints unterstützen alle Funktionen. Eine detailierte Dokumentation der Endpoints finden Sie unter Administration > Anbindungen > REST API Dokumentation

Erweiterte Aufrufe​

Ergebnis einschränken / erweitern​

Die DocBee REST API ermöglicht es Ihnen, über den Parameter fields das Ergebnis des Aufrufes zu einzuschränken bzw. zu erweitern.

Der Parameter fields erwartet eine kommaseparierte Liste von Eigenschaften.

Das Erweitern ermöglicht Ihnen, zusätzlich Eigenschaften eines verknüpften Objektes zurück zu erhalten ohne eine weitere Anfrage an den Server zu schicken. Dafür setzen Sie in fields einfach den Namen des verknüpften Objektes und die gewünschte Eigenschaft getrennt mit einem . z.B. customer.name.

Beispiel Kontakt (einschränken)​

Falls Sie von einem Kontakt nur die id und die email zurück bekommen wollen, setzen Sie einfach den fields Parameter auf id,email.

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <ACCESS_TOKEN>' 'https://my.docbee.com/restApi/v1/customerContact?fields=id%2Cemail'

Beispiel Kontakt (erweitern)​

Falls Sie von einem Kontakt zusätzlich die Daten des Kunden haben wollen ohne eine weitere Anfrage an die REST API zu stellen, können Sie im Parameter fields folgende Werte angeben: id,email,name,customer.name,customer.id

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <ACCESS_TOKEN>' 'https://my.docbee.com/restApi/v1/customerContact?fields=id%2Cemail%2Cname%2Ccustomer.name%2Ccustomer.id'

Hinweis: Mit dem Zeichen * in der fields Liste erhalten Sie alle Eigenschaften diese Objektes zurück.

Anzahl der zurückgelieferten Ergebnisse​

Die DocBee REST API ermöglicht es Ihnen, über den Parameter limit die Anzahl der zurückgelieferten Ergebnisse des Aufrufes zu verändern.

Ist der Parameter limit nicht gesetzt werden standardmäßig 10 Einträge zurückgeliefert. Der Maximalwert für den Parameter limit beträgt 50 Einträge.

Array aktualisieren​

In Arrays, wie beispielsweise bei Tags, ist es jetzt möglich, anstelle eines JSON-Arrays ein JSON-Objekt zu übergeben. Dies ermöglicht es, Elemente hinzuzufügen (add), festzulegen (set) oder zu entfernen (remove), ohne sie zuvor manuell bearbeiten zu müssen.

Hinzufügen​

Das folgende Beispiel würde bei einem PUT nun den Tag mit der id = 1 hinzufügen und alle anderen schon gesetzten Tags einfach behalten.

{
   "tags": {
        "action": "add",
        "ids": [1]
   } 
}

Entfernen​

Das folgende Beispiel würde bei einem PUT nun den Tag mit der id = 1 entfernen und alle anderen schon gesetzten Tags einfach behalten.

{
   "tags": {
        "action": "remove",
        "ids": [1]
   } 
}

Setzen​

Das folgende Beispiel würde bei einem PUT nun den Tag mit der id = 1 setzen und alle anderen Tags überschreiben.

{
   "tags": {
        "action": "set",
        "ids": [1]
   } 
}

Dies wäre identisch mit dem Aufruf

{
   "tags": [1]
}

Informationen​

Datumswerte​

Alle Datumswerte innerhalb der DocBee REST API werden in UTC zurückgegeben.

Endpoints​

Objekt in DocBeeEndpoint
Vertragv1/agreement
Vertrags-Gruppenv1/agreementCategory
Vertrags-Bestandteilv1/agreementComponent
Vertrags-Laufzeitv1/agreementPeriod
Abwesenheitenv1/away
Abwesenheitens-Grundv1/awayReason
Firmierungv1/companyData
Vertraulichkeitv1/confidentialTag
Kontingentv1/contignent
Kontingent-Buchungv1/contignentItem
Aufwandschätzungv1/costEstimation
Aufwandschätzung-Aufgabev1/costEstimationTask
Aufwandschätzung-Teilaufgabev1/costEstimationSubTask
Kundev1/customer
Kunden-Kontaktv1/customerContact
Kunden-Standortv1/customerLocation
Kunden-Objektv1/customerObject
Kunden-Gruppev1/customerProfile
Kunden-Statusv1/customerStatus
Kunden-Loginv1/customerUser
Zusatzfelderv1/customField
Abteilungv1/department
Abteilungs-Gruppenv1/departmentProfile
Leistungv1/docBeeDocument
Leistungs-Konfliktv1/docBeeDocumentConflict
Leistungs-Nachrichtv1/docBeeDocumentMessage
Leistungs-Tätigkeitv1/docBeeDocumentTask
Leistungs-Tätigkeit-Materialv1/docBeeDocumentTaskMaterial
Leistungs-Tätigkeit-Planungszeitv1/docBeeDocumentTaskPlanningTime
Leistungs-Tätigkeit-Leistungserfasssungv1/docBeeDocumentTaskWorkLog
Leistungs-Reisezeitv1/docBeeDocumentTraveLog
Leistungs-Vorlagenv1/docBeeDocumentTemplate
DocBee Skriptv1/docBeeScript
E-Mail Adressenv1/emailAddress
Export-Profilev1/exportProfile
Dateiv1/file
Abrechnungv1/invoice
Materialv1/materialItem
Nachrichtv1/message
Mobilnummernv1/mobileNumber
Mitarbeiterstatistikv1/mis
Benachrichtigungenv1/notification
Objektv1/object
Objekt-Kategoriev1/objectCategory
Beobachterv1/observer
Beobachter-Kategoriev1/observerCategory
Beobachter-Typv1/observerType
Zahlungsprofilv1/paymentProfile
Zahlungsprofil-Preisv1/paymentProfilePrice
Rollenv1/permissionGroup
Prioritätv1/priority
Protokollv1/protocol
Protokoll-Wertev1/protocolEntry
Protokoll-Gruppev1/protocolGroup
Protokoll-Gruppe-Datenv1/protocolGroupData
Protokoll-Gruppe-Wertev1/protocolGroupEntries
Protokoll-Musterv1/protocolTemplate
Protokoll-Muster-Auswahl-Elementev1/protocolTemplateElement
Protokoll-Muster-Felderv1/protocolTemplateEntry
Protokoll-Muster-Gruppen-Kontainerv1/protocolTemplateGroupContainer
Protokoll-Muster-Gruppenv1/protocolTemplateGroup
Protokoll-Muster-Gruppen-Feld-Verknüpfungv1/protocolTemplateGroupEntryMapping
Protokoll-Muster-Komponentv1/protocolTemplateComponent
Protokoll-Muster-Bedingungv1/protocolTemplateAction
Protokoll-Muster-Bedingung-Bedingungv1/protocolTemplateAction
Protokoll-Muster-Bedingung-Reaktionv1/protocolTemplateReaction
Protokoll-Muster-Bedingung-Reaktionv1/protocolTemplateReaction
Protokoll-Typv1/protocolTemplateType
Queuev1/queue
Zusatzlistev1/selectionCategory
Zusatzliste-Wertv1/selectionValue
Externer Dienstleisterv1/serviceProvider
Externer Dienstleister - Benutzerv1/serviceProviderUser
Leistungsartv1/serviceType
Leistungsart-Gruppenv1/serviceTypeProfile
Tagv1/tag
Tabellen-Einstellungenv1/tableConfigStorage
Tätigkeits-Vorlagenv1/taskTemplate
Vorgangv1/ticket
Vorgangs-Boardsv1/ticketBoard
Vorgangs-Boards-Gruppev1/ticketBoardProfile
Vorgangs-Kategoriev1/ticketCategory
Vorgangs-Verknüpfungs-Typv1/ticketLinkType
Vorgangs-Nachrichtv1/ticketMessage
Vorgangs-Verknüpfungv1/ticketLink
Vorgangs-Statusv1/ticketStatus
Vorgangs-Vorlagev1/ticketTemplate
Timerv1/timer
Externe Zeiterfassungv1/timeRecord
Reiseartv1/traveType
Benutzerv1/user
Benutzer & Queuesv1/userAndQueue
Mitarbeiter-Gruppenv1/userProfile
Aktivitätenv1/userActivity
Externes Arbeitspaketv1/workPipe