REST-API

Durch die Verwendung der Beekeeper-API kannst du deine Nutzer auf gleichzeitig synchronisieren.

Bitte besuche unser Developer-Portal für Informationen zur Strukturierung und Authentifizierung von Anfragen.

Wie bei einem regulären Hochladen von CSV/Excel oder Synchronisieren per FTP erstellt dieser Endpunkt einen Import, der im Admin-Dashboard unter Nutzer > Importe angezeigt wird.

Nutzer werden an den Server als mehrteilige Datei im JSON-Format gesendet (siehe unten). Sie werden anschließend asynchron importiert.

Dateistruktur

Der Endpunkt für gleichzeitige Importe akzeptiert eine Datei, die in jeder Zeile ein JSON-Nutzerobjekt enthält. Jedes Nutzerobjeckt ist wie im folgenden Code-Block strukturiert. Beachte, dass die Struktur des Objekts „user_data“ mit der des Endpunkts /users übereinstimmt.

Nutzerinhalt:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": []
}

Dateiinhalt:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
...

Nutzer werden anhand des Werts in „id_field“ identifiziert – nach Wahl entweder per „name“, „email“ oder „tenantuserid“ (eine Erklärung dieser Werte folgt). Dieses Feld muss im Objekt „user_data“ vorhanden sein.

Wenn der Nutzer aufgrund des angegebenen Feldes id_field nicht abgeglichen werden kann, erfolgt dies entsprechend der Liste id_field_fallbacks. Für die Liste id_field_fallbacks können dieselben Werte (name, email, tenantuserid) verwendet werden. Alternativ kann die Liste leer gelassen werden.

Die folgende cURL zeigt die JSON-Nutzerobjekte zum Erstellen, Aktualisieren, Sperren und Löschen, dabei wird wie zuvor der Nutzername Max Mustermann verwendet:

curl -X POST -H "Authorization: Token <access_key>" \
-H "Content-Type: multipart/form-data; boundary=3d1a8e334ce84031bdce8eb049467620" \
-d '--3d1a8e334ce84031bdce8eb049467620
Content-Disposition: form-data; name="file"; filename="user_data.json"
Content-Type: application/json

{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "email": "max_mustermann@example.com", "custom_fields": [{"key": "firstname", "value": "Max"}, {"key": "lastname", "value": "Mustermann"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "tenantuserid": "max_1", "custom_fields": [{"key": "firstname", "value": "Maxine"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_musterman", "suspended":true}}
{"type": "delete", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann"}}

--3d1a8e334ce84031bdce8eb049467620--
' 'https://unternehmen.beekeeper.io/api/2/users/force-import'

So erstellst/aktualisierst du Nutzer:

Zum Erstellen oder Aktualisieren eines Nutzers stelle den Typ auf „update“ ein. Wenn der Nutzer nicht vorhanden ist, wird er automatisch erstellt.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "email": "max_mustermann@example.com",
    "suspended": false,
    "custom_fields": [
      {
        "key": "firstname",
        "value": "Max"
      },
      {
        "key": "lastname",
        "value": "Mustermann"
      },
      {
        "key": "position",
        "value": "IT Support"
      },
    ]
  },
  "groups": [
    { "name": "Honeybees" }
  ]
}

So sperrst du Nutzer:

Füge wie oben im JSON-Nutzerobjekt das Feld „suspended=true“ hinzu.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "suspended": true
  }
}

So löschst du Nutzer:

Lege den Typ auf „delete“ fest. Der Nutzer wird dann gelöscht.

{
  "type": "delete",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  }
}

So fügst du Nutzer zu Gruppen hinzu:

Lege den Typ auf „update“ fest und führe alle Gruppennamen auf, denen der Nutzer angehören soll.

Um einen Nutzer aus einer Gruppe zu entfernen, entferne ihn einfach aus der Liste. Die Gruppenmitgliedschaften werden jedes Mal überschrieben.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  },
  "groups": [
   { "name" : "Honeybees" },
   { "name": "Bumblebees" }
  ]
}

Standorte

Wenn Ihr Produkt Standorte enthält, werden Ihre Benutzer dem Standardstandort zugeordnet. Sie können sie aber auch anderen Standorten zuordnen. Wie bereits erwähnt, im Nutzerinhalt und Dateiinhalt. Die Werte der Standorte werden wie folgt addiert:

Nutzerinhalt:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": [],
  "locations": []
}

Dateiinhalt:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
...

So fügst du Nutzer zu Standorte hinzu:

Lege den Typ auf „update“ fest und führe alle Standortenamen auf, denen der Nutzer angehören soll.

Standardmässig sind alle Benutzer zunächst dem default Standorte zugeordnet. Ein Benutzer kann zu mehreren Standorte gehören.

{
  "type": "update",
  "options": {
  "id_field": "name"
 },
  "user_data": {
  "name": "max_mustermann",
 },
  "locations": [
   {"unique_name": "Asia"},
   {"unique_name": "America"}
 ]
}