Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core Module und Plugins > agorum core client areas

agorum core client areas REST-API

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins agorum core insign. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Das Plugin agorum core client areas wird mit einer REST-Schnittstelle ausgeliefert, die für die Verwaltung von Mandanten verwendet wird. Diese REST-Schnittstelle bietet Funktionen zur Erstellung, Aktualisierung und Verwaltung von Mandanten und deren Benutzern.

Verwendung

Sie können mit agorum core client areas Mandanten in agorum core einrichten und dasselbe agorum core-System für Zugriffe von unterschiedlichen Einrichtungen oder Abteilungen benutzen. Die Benutzer und Daten der Mandanten werden dabei vollständig getrennt verwaltet. Über die REST-Schnittstelle können Sie die Mandantenadministration automatisieren.

Zur einfacheren Verwendung der REST-Schnittstelle enthält das Projekt eine Postman-Collection , die Sie in Postman laden können, um die Services direkt aufzurufen.

/agorum/roi/customers/agorum.client.areas/doc/agorum.client.areas.postman_collection.json

Wenn Sie nicht Postman verwenden, finden Sie hier eine Kurzbeschreibung der verfügbaren Anfragen.

Bearer Token

Zur Verwendung der REST-API benötigen Sie ein JWT-Token. Dieses Token können Sie über das folgende mitgelieferte Skript erzeugen:

/agorum/roi/customers/agorum.client.areas/js/setup/create-jwt.js

Sie müssen das Token bei jeder Anfrage mitgeben.

Basispfad

Der Basispfad für alle Anfragen besteht aus dem Servernamen von agorum core und folgendem Pfad:

/api/rest/custom/agorum.client.areas.tools.noauth

Services

POST createArea

Die Anfrage erzeugt einen Mandaten mit der angegebenen Nummer im identifizierten Bereich. Der Standardbereich ist client-areas. Sie können optional weitere Mandanteneinstellungen mitgeben, etwa den Mandantennamen.

Als Body müssen Sie eine JSON-Struktur nach folgendem Muster mitgeben:

{
  "identifier": "client-areas",
  "number": "88"
}

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

POST createUser/{{identifier}}/{{number}}

Die Anfrage erzeugt einen Benutzer mit Zuordnung zu dem über identifier und number angegebenen Mandanten.

Als Body müssen Sie eine JSON-Struktur nach folgendem Muster mitgeben:

{
  "name": "user.test.1",
  "password": "agorum",
  "givenName": "User",
  "familyName": "Test 1",
  "emailaddress": "user.test.1@agorum.com",
  "language": "de",
  "features": []
}

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

PUT lockUser/{{identifier}}/{{number}}/{{name}}

Die Anfrage lockUser sperrt den angegebenen Mandantenbenutzer. Sie müssen identifier, number und name (des Benutzers) angeben. Gesperrte Benutzer können sich nicht mehr im System anmelden.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

PUT modifyArea/{{identifier}}/{{number}}

Die Anfrage ändert die Mandateninformationen des über identifier und number angegebenen Mandanten.

Als Body müssen Sie eine JSON-Struktur nach folgendem Muster mitgeben.

{
  "name": "Testmandant 99",
  "settings": {
    "agorum.client.areas.sampleClientSettings": {
      "sample_setting_1": "Value 1",
      "sample_setting_2": 2
    }
  },
  "addresses": [
    {
      "address_type": "invoice",
      "company_name": "agorum Software GmbH",
      "company_additional_name": "",
      "street": "Vogelsangstr.",
      "house_number": "22",
      "zip": "73760",
      "city": "Ostfildern",
      "country": "de",
      "email": "rechnung@agorum.com",
      "contact": "Rolf Lang",
      "settings": {
        "agorum.client.areas.sampleAddressSettings": {
          "sample_setting_1": "Value 1",
          "sample_setting_2": 2
        }
      }
    }
  ]
}

Tipp: Sie können die Informationen aus der Anfrage GET areaInfo kopieren und als Grundlage für Ihre Änderungen und Ergänzungen verwenden.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

PUT modifyUser/{{identifier}}/{{number}}/{{name}}

Die Anfrage modifyUser ändert die Daten des angegebenen Mandantenbenutzers.

Als Body müssen Sie eine JSON-Struktur nach folgendem Muster mitgeben.

Hinweis: Das Passwort und die Benutzerfunktionen werden nur geändert, wenn Sie diese explizit angeben. Sonst bleiben die vorhandenen Werte bestehen.

{
  "name": "user.test.1",
  "oldName": "user.test.1",
  "password": "agorum",
  "givenName": "User",
  "familyName": "Test 1",
  "emailaddress": "user.test.1@agorum.com",
  "language": "de",
  "features": [
    "agorum.client.areas.admin"
  ]
}

Tipp: Sie können die Informationen aus der Anfrage GET areaInfo kopieren und als Grundlage für Ihre Änderungen und Ergänzungen verwenden.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

PUT unlockUser

Die Anfrage unlockUser entsperrt den angegebenen Mandantenbenutzer. Sie müssen identifier, number und name (des Benutzers) angeben.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

GET areaInfo/{{identifier}}/{{number}}

Die Anfrage areaInfo fragt Informationen zu einem über identifier und number angegebenen Mandanten ab.

Im Erfolgsfall erhalten Sie einen Rückgabewert 200 und eine JSON-Struktur mit den konfigurierten Mandanteninformationen nach folgendem Muster zurück:

{
    "identifier": "client-areas",
    "number": "34",
    "settings": {},
    "addresses": [
        {
            "zip": "33333",
            "settings": {},
            "address_type": "other",
            "city": "Musterhausen",
            "street": "TestStraße",
            "company_name": "Testmandant3",
            "house_number": "4"
        }
    ],
    "name": "testmandant8"
}

GET areaStatistic/{{identifier}}/{{number}}

Die Anfrage liefert eine Statistik des über identifier und number angegebenen Mandanten zurück. Mit der Statistik können Sie etwa folgende Informationen abfragen:

Anzahl der Ordner
Anzahl der Objekte
Anzahl der Dateien
Anzahl der Benutzer

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur wie im folgenden Beispiel zurück:

{
    "volume": 782570,
    "identifier": "client-areas",
    "number": "34",
    "volumeAll": 7.9327668E7,
    "volumeHidden": 78545098,
    "folders": 15,
    "filesHidden": 1714,
    "objects": 1737.0,
    "files": 8,
    "users": 1.0
}

GET availableFeatures

Die Anfrage availableFeatures fragt eine Liste aller konfigurierten Benutzerfunktionen ab, siehe Zusätzliche Benutzerfunktionen aktivierbar machen.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur wie im folgenden Beispiel zurück:

[
    {
        "displayName": "Mandantenadministrator",
        "name": "agorum.client.areas.admin",
        "description": "Diese Funktion ermöglicht es dem Benutzer, innerhalb seines Mandanten Benutzer zu verwalten."
    },
    {
        "displayName": "Weitere Einstellungen für Mandanten",
        "name": "agorum.client.areas.clientExtraSettings",
        "description": "Zugriff auf Weitere Einstellungen für Mandanten zulassen."
    }
]

GET listAreas

Die Anfrage gibt eine Liste aller Mandanten zurück. Es sind keine weiteren Angaben erforderlich.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur wie im folgenden Beispiel zurück:

[
    {
        "identifier": "client-areas",
        "number": "XY",
        "name": null
    },
    {
        "identifier": "another-client-area",
        "number": "88",
        "name": "test"
    }
]

GET listUsers/{{identifier}}/{{number}}

Die Anfrage gibt alle Benutzer des über identifier und number angegebenen Mandanten zurück.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur wie im folgenden Beispiel zurück:

[
    "testmandant3-benutzer1"
]

GET userInfo/{{name}}

Die Anfrage gibt Informationen zu dem über den Benutzernamen angegebenen Benutzer zurück.

Im Erfolgsfall erhalten Sie den Rückgabewert 200 und eine JSON-Struktur wie im folgenden Beispiel zurück:

{
    "features": [],
    "clientIdentifier": "client-areas",
    "givenName": "Test",
    "familyName": "Mandant3",
    "name": "testmandant3-benutzer1",
    "emailaddress": "testbenutzer@testmandant3.de",
    "language": "fr",
    "clientNumber": "34",
    "locked": false,
    "readOnlyMode": false
}

DELETE deleteArea/{{identifier}}/{{number}}

Die Anfrage löscht den über identifier und number angegebenen Mandanten, synchron mit allen Benutzern, Daten und Berechtigungen. Die Funktion ist erst beendet, wenn der Löschvorgang komplett abgeschlossen ist.

Achtung: Die Daten sind danach komplett gelöscht und können nicht wiederhergestellt werden.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.

DELETE deleteAreaTask/{{identifier}}/{{number}}

Die Anfrage löscht den über identifier und number angegebenen Mandanten im Hintergrund, komplett, mit allen Benutzern, Daten und Berechtigungen. Das Löschen wird auch fortgesetzt, wenn das System neu gestartet wird.

Achtung: Die Daten sind danach komplett gelöscht und können nicht wiederhergestellt werden.

Im Erfolgsfall erhalten Sie den Rückgabewert 200.