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 DocBee	Endpoint
Vertrag	v1/agreement
Vertrags-Gruppen	v1/agreementCategory
Vertrags-Bestandteil	v1/agreementComponent
Vertrags-Laufzeit	v1/agreementPeriod
Abwesenheiten	v1/away
Abwesenheitens-Grund	v1/awayReason
Firmierung	v1/companyData
Vertraulichkeit	v1/confidentialTag
Kontingent	v1/contignent
Kontingent-Buchung	v1/contignentItem
Aufwandschätzung	v1/costEstimation
Aufwandschätzung-Aufgabe	v1/costEstimationTask
Aufwandschätzung-Teilaufgabe	v1/costEstimationSubTask
Kunde	v1/customer
Kunden-Kontakt	v1/customerContact
Kunden-Standort	v1/customerLocation
Kunden-Objekt	v1/customerObject
Kunden-Gruppe	v1/customerProfile
Kunden-Status	v1/customerStatus
Kunden-Login	v1/customerUser
Zusatzfelder	v1/customField
Abteilung	v1/department
Abteilungs-Gruppen	v1/departmentProfile
Leistung	v1/docBeeDocument
Leistungs-Konflikt	v1/docBeeDocumentConflict
Leistungs-Nachricht	v1/docBeeDocumentMessage
Leistungs-Tätigkeit	v1/docBeeDocumentTask
Leistungs-Tätigkeit-Material	v1/docBeeDocumentTaskMaterial
Leistungs-Tätigkeit-Planungszeit	v1/docBeeDocumentTaskPlanningTime
Leistungs-Tätigkeit-Leistungserfasssung	v1/docBeeDocumentTaskWorkLog
Leistungs-Reisezeit	v1/docBeeDocumentTraveLog
Leistungs-Vorlagen	v1/docBeeDocumentTemplate
DocBee Skript	v1/docBeeScript
E-Mail Adressen	v1/emailAddress
Export-Profile	v1/exportProfile
Datei	v1/file
Abrechnung	v1/invoice
Material	v1/materialItem
Nachricht	v1/message
Mobilnummern	v1/mobileNumber
Mitarbeiterstatistik	v1/mis
Benachrichtigungen	v1/notification
Objekt	v1/object
Objekt-Kategorie	v1/objectCategory
Beobachter	v1/observer
Beobachter-Kategorie	v1/observerCategory
Beobachter-Typ	v1/observerType
Zahlungsprofil	v1/paymentProfile
Zahlungsprofil-Preis	v1/paymentProfilePrice
Rollen	v1/permissionGroup
Priorität	v1/priority
Protokoll	v1/protocol
Protokoll-Werte	v1/protocolEntry
Protokoll-Gruppe	v1/protocolGroup
Protokoll-Gruppe-Daten	v1/protocolGroupData
Protokoll-Gruppe-Werte	v1/protocolGroupEntries
Protokoll-Muster	v1/protocolTemplate
Protokoll-Muster-Auswahl-Elemente	v1/protocolTemplateElement
Protokoll-Muster-Felder	v1/protocolTemplateEntry
Protokoll-Muster-Gruppen-Kontainer	v1/protocolTemplateGroupContainer
Protokoll-Muster-Gruppen	v1/protocolTemplateGroup
Protokoll-Muster-Gruppen-Feld-Verknüpfung	v1/protocolTemplateGroupEntryMapping
Protokoll-Muster-Komponent	v1/protocolTemplateComponent
Protokoll-Muster-Bedingung	v1/protocolTemplateAction
Protokoll-Muster-Bedingung-Bedingung	v1/protocolTemplateAction
Protokoll-Muster-Bedingung-Reaktion	v1/protocolTemplateReaction
Protokoll-Muster-Bedingung-Reaktion	v1/protocolTemplateReaction
Protokoll-Typ	v1/protocolTemplateType
Queue	v1/queue
Zusatzliste	v1/selectionCategory
Zusatzliste-Wert	v1/selectionValue
Externer Dienstleister	v1/serviceProvider
Externer Dienstleister - Benutzer	v1/serviceProviderUser
Leistungsart	v1/serviceType
Leistungsart-Gruppen	v1/serviceTypeProfile
Tag	v1/tag
Tabellen-Einstellungen	v1/tableConfigStorage
Tätigkeits-Vorlagen	v1/taskTemplate
Vorgang	v1/ticket
Vorgangs-Boards	v1/ticketBoard
Vorgangs-Boards-Gruppe	v1/ticketBoardProfile
Vorgangs-Kategorie	v1/ticketCategory
Vorgangs-Verknüpfungs-Typ	v1/ticketLinkType
Vorgangs-Nachricht	v1/ticketMessage
Vorgangs-Verknüpfung	v1/ticketLink
Vorgangs-Status	v1/ticketStatus
Vorgangs-Vorlage	v1/ticketTemplate
Timer	v1/timer
Externe Zeiterfassung	v1/timeRecord
Reiseart	v1/traveType
Benutzer	v1/user
Benutzer & Queues	v1/userAndQueue
Mitarbeiter-Gruppen	v1/userProfile
Aktivitäten	v1/userActivity
Externes Arbeitspaket	v1/workPipe