Inhaltsverzeichnis

  1. Einführung

  2. Was ist die Dolibarr REST API?

  3. Einrichten des API-Zugriffs in Dolibarr

  4. Authentifizierungsmethoden und API-Token

  5. Übersicht über den Benutzerendpunkt

  6. Erstellen eines Benutzers über die API

  7. Lesen von Benutzerdaten

  8. Aktualisieren von Benutzerinformationen

  9. Deaktivieren oder Löschen von Benutzern

  10. Zuweisen von Benutzern zu Gruppen und Berechtigungen

  11. Erweiterte Benutzereigenschaften und Metadaten

  12. Verwalten externer Benutzer mit der API

  13. Best Practices für die Automatisierung von Benutzerkonten

  14. Behandeln von API-Fehlern und -Antworten

  15. Integration der API in Systeme von Drittanbietern

  16. API-Zugriff sichern und Missbrauch verhindern

  17. Verwenden von Webhooks für Echtzeit-Benutzeraktualisierungen

  18. Protokollieren und Überwachen von API-Aktivitäten

  19. Einschränkungen und bekannte Probleme bei der Benutzerverwaltung über die API

  20. Zusammenfassung und Empfehlungen

1. Einleitung

Da sich ERP-Systeme hin zu Cloud-nativen, vernetzten Architekturen entwickeln, spielen APIs eine entscheidende Rolle bei der Datenintegration und der Automatisierung von Abläufen. Dolibarr ERP & CRM verfügt über eine robuste REST-API, die die Anbindung externer Systeme an nahezu alle Aspekte der Plattform ermöglicht. Einer der wichtigsten Interaktionsbereiche ist die Benutzerkontenverwaltung.

In dieser Anleitung erfahren Sie, wie Sie Benutzerkonten programmgesteuert mithilfe der Dolibarr REST-API verwalten. Von der Erstellung und Aktualisierung von Benutzern über die Zuweisung von Berechtigungen bis hin zur Sicherung des API-Zugriffs decken wir alles ab, was für eine effektive Integration erforderlich ist.

2. Was ist die Dolibarr REST API?

Die REST-API ist eine von Dolibarr bereitgestellte Schnittstelle, die es externen Systemen ermöglicht, CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) durchzuführen. Sie folgt RESTful-Prinzipien und ermöglicht so die einfache Integration verschiedener Technologien und Tools.

Verfügbare Endpunkte decken die meisten Module ab, darunter:

  • Dritte (Unternehmen, Kontakte)

  • Produkte und Dienstleistungen

  • Rechnungen und Bestellungen

  • Projekte und Aufgaben

  • Benutzer und Berechtigungen

3. Einrichten des API-Zugriffs in Dolibarr

Um die REST-API zu verwenden, müssen Sie:

  • Aktivieren Sie das API-Modul in Dolibarr (Startseite > Setup > Module).

  • Erstellen eines API-Schlüssels/Tokens aus einem Benutzerkonto

  • Legen Sie die entsprechenden Berechtigungen für diesen Benutzer fest

  • Greifen Sie über den Endpunkt auf die API zu: https://yourdomain.com/api/index.php

Dolibarr enthält API-Dokumentation, auf die über die Swagger-Schnittstelle zugegriffen werden kann, normalerweise unter /api/index.php/explorer.

4. Authentifizierungsmethoden und API-Token

Die Authentifizierung erfolgt über HTTP-Header. Die Standardmethode verwendet ein API-Token:

GET /users
Host: yourdomain.com
DOLAPIKEY: abcdef1234567890abcdef1234567890

Stellen Sie sicher, dass:

  • Geben Sie API-Schlüssel niemals im Frontend-Code preis

  • Generieren Sie Schlüssel aus Sicherheitsgründen regelmäßig neu

  • Verwenden Sie HTTPS, um den Datenverkehr zu verschlüsseln

5. Übersicht über den Benutzerendpunkt

Der Basisendpunkt für die Benutzerverwaltung ist:

GET /users

Zu den unterstützten Vorgängen gehören:

  • GET /users: alle Benutzer auflisten

  • GET /users/{id}: einen bestimmten Benutzer abrufen

  • POST /users: einen neuen Benutzer erstellen

  • PUT /users/{id}: Aktualisieren Sie einen vorhandenen Benutzer

  • DELETE /users/{id}: einen Benutzer löschen

Jedes Benutzerobjekt enthält Felder wie:

  • login

  • firstname

  • lastname

  • email

  • admin

  • statut

6. Erstellen eines Benutzers über die API

So erstellen Sie einen Benutzer:

POST /users
Content-Type: application/json
DOLAPIKEY: your_api_key

{
  "login": "jdoe",
  "password": "secret",
  "firstname": "John",
  "lastname": "Doe",
  "email": "jdoe@example.com",
  "admin": 0,
  "statut": 1
}

Dolibarr gibt bei Erfolg die ID des neuen Benutzers zurück. Passwörter müssen sicher sein und sicher verwaltet werden.

7. Lesen von Benutzerdaten

So rufen Sie die Daten eines Benutzers ab:

GET /users/123
DOLAPIKEY: your_api_key

Dadurch wird das JSON-Objekt für die Benutzer-ID 123 zurückgegeben, einschließlich persönlicher Daten, Anmeldung, Status und Gruppenmitgliedschaften.

8. Aktualisierung der Benutzerinformationen

So ändern Sie die Informationen eines Benutzers:

PUT /users/123
Content-Type: application/json
DOLAPIKEY: your_api_key

{
  "email": "newemail@example.com",
  "lastname": "Doe-Smith"
}

Fügen Sie nur Felder ein, die aktualisiert werden müssen. Wenn Sie andere auslassen, bleiben sie unverändert.

9. Deaktivieren oder Löschen von Benutzern

So deaktivieren Sie einen Benutzer (anstatt ihn zu löschen):

PUT /users/123
{
  "statut": 0
}

So löschen Sie einen Benutzer dauerhaft:

DELETE /users/123

Gehen Sie beim Löschen vorsichtig vor, da sich dies auf mit dem Benutzer verknüpfte Datensätze auswirken kann.

10. Zuweisen von Benutzern zu Gruppen und Berechtigungen

Die Konzernleitung wird nicht direkt durch die /users Endpunkt. Sie müssen:

  • Nutzen Sie /groups kombiniert mit einem nachhaltigen Materialprofil. /groups/{id}/users

  • POST um einen Benutzer einer Gruppe zuzuordnen

  • Konfigurieren Sie Gruppenberechtigungen in der Benutzeroberfläche oder über die API, falls unterstützt

Berechtigungen werden aus der Gruppenmitgliedschaft geerbt.

11. Erweiterte Benutzereigenschaften und Metadaten

Zu den erweiterten Optionen gehören:

  • Benutzerdefinierte Felder (Extrafelder)

  • Sprachpräferenz (default_lang)

  • Zeitzone (timezone)

  • Externes Benutzerkennzeichen (fk_soc für Drittverbände)

Diese Eigenschaften verbessern die benutzerspezifische Konfiguration.

12. Externe Benutzer mit der API verwalten

Externe Benutzer sind mit Kunden oder Lieferanten verknüpft. Beim Anlegen dieser Benutzer gilt Folgendes:

  • Umfassen die fk_soc Feld zum Verlinken mit einem Drittanbieter

  • Beschränken Sie den Modulzugriff entsprechend

Externe Benutzer haben oft eine eingeschränkte Sichtbarkeit und ihre Berechtigungen sollten streng kontrolliert werden.

13. Best Practices für die Automatisierung von Benutzerkonten

  • Überprüfen Sie alle Eingaben vor dem Senden an die API

  • Implementieren Sie Regeln zur Kennwortstärke

  • Nicht mehr benötigte Benutzer automatisch deaktivieren

  • Synchronisieren Sie mit externen Systemen nach einem Zeitplan

  • Dokumentieren Sie die API-Nutzung und den Autorisierungsumfang

14. Umgang mit API-Fehlern und -Antworten

Dolibarr gibt standardmäßige HTTP-Statuscodes zurück:

  • 200 OK: erfolgreicher Vorgang

  • 400 Bad Request: ungültige Daten

  • 401 Unauthorized: ungültiges Token

  • 404 Not Found: Benutzer nicht gefunden

Überprüfen Sie immer die Antworten und gehen Sie mit Fehlern ordnungsgemäß um.

15. Integration der API in Systeme von Drittanbietern

Typische Integrationen umfassen:

  • HR-Systeme (zum Erstellen von Benutzern beim Onboarding)

  • CRMs oder Ticketsysteme

  • Externe SaaS-Plattformen, die eine Dolibarr-Benutzersynchronisierung benötigen

Verwenden Sie Webhooks, Batch-Skripte oder Middleware, um Daten sicher zu synchronisieren.

16. API-Zugriff sichern und Missbrauch verhindern

  • Rate-Limit-API-Aufrufe

  • Überwachen Sie Nutzung und Protokolle

  • Verwenden Sie unterschiedliche Token pro Anwendung

  • Schlüssel geheim halten

  • Überprüfen Sie alle externen Integrationen

17. Verwenden von Webhooks für Echtzeit-Benutzeraktualisierungen

Obwohl Dolibarr keine nativen Webhooks enthält, können Sie:

  • Erweitern Sie Module, um Hooks auszugeben

  • Verwenden Sie geplante Skripts, um Änderungen abzufragen

  • Implementieren Sie benutzerdefinierte Trigger, um Systeme zu benachrichtigen

Diese können dazu beitragen, dass externe Systeme synchron bleiben.

18. Protokollieren und Überwachen von API-Aktivitäten

Dolibarr protokolliert API-Aktivitäten in:

  • Apache-Protokolle (Zugriff und Fehler)

  • Protokolle auf Anwendungsebene, wenn der Debug-Modus aktiviert ist

  • Externe Protokollaggregationstools über Middleware

Protokollieren Sie wichtige Ereignisse wie Benutzererstellung, Kennwortänderungen und Anmeldeversuche.

19. Einschränkungen und bekannte Probleme bei der Benutzerverwaltung über API

  • Einige Benutzereinstellungen erfordern eine manuelle UI-Konfiguration

  • Kein integrierter Prüfpfad für API-Änderungen

  • Die Extrafeld-Behandlung kann je nach Konfiguration variieren

Beiträge und Patches der Community können einige dieser Lücken schließen.

20. Zusammenfassung und Empfehlungen

Die Verwaltung von Benutzerkonten mit der Dolibarr REST API bietet Flexibilität und Automatisierungspotenzial. Durch die Nutzung von Standardendpunkten und Best Practices können Unternehmen die Benutzerbereitstellung, -aktualisierung und -deaktivierung optimieren.

Administratoren sollten sicherstellen, dass der API-Zugriff sicher, fehlertolerant und sorgfältig in bestehende Workflows integriert ist. Während Dolibarr sich weiterentwickelt, bleibt die API ein wichtiges Werkzeug für die Skalierung und Modernisierung der ERP-Nutzung über verschiedene Systeme und Teams hinweg.