Die REST-API von Dolibarr, vom Schlüssel bis zur bezahlten Rechnung

Dolibarr bringt eine REST-API mit: Alles, was Sie am Bildschirm tun (Geschäftspartner, Rechnungen, Aufträge, Produkte…), lässt sich aus einem anderen Programm, einer Website oder einem Skript erledigen. Diese Seite beginnt bei null und führt bis zu einer freigegebenen Rechnung mit PDF und Zahlung. Jeder Befehl wurde am 13. Oktober 2026 gegen eine neue Dolibarr-24.0.1-Instanz ausgeführt.

Unterwegs drei Verhaltensweisen, die die Dokumentation nicht erwähnt:

• zusammen mit der Rechnung gesendete Zeilen ändern ihre Reihenfolge, auf der Rechnung und im PDF;
• eine über die API freigegebene Rechnung hat kein PDF, solange man es nicht anfordert;
• ist das Modul deaktiviert, antwortet die API trotzdem mit „200 OK“.

1. Das Modul aktivieren

Einstellungen › Module/Anwendungen, Modul API/Webservices (REST Server). Seine Einstellungsseite nennt die Adresse des Explorers und erlaubt, den Zugriff auf bestimmte IP-Adressen zu beschränken.

Solange das Modul deaktiviert ist, antwortet jede API-Adresse mit dem Code 200 und diesem Text:

Module <b>Api</b> must be enabled.<br><br>To activate modules, go on setup Area (Home->Setup->Modules).

Ein Skript, das nur den HTTP-Code prüft, hält alles für in Ordnung: Prüfen Sie auch, dass die Antwort JSON ist.

Aktivieren Sie auch die Module, deren Daten Sie brauchen. Für diese Seite: Geschäftspartner, Rechnungen und, für Zahlungen, Banken | Kassen. Die APIs eines deaktivierten Moduls erscheinen nicht.

2. Einen eigenen Benutzer und seinen Schlüssel anlegen

Der API-Schlüssel hat genau die Berechtigungen des Benutzers, dem er gehört. Legen Sie ihn nicht auf Ihrem Administratorkonto an, sondern auf einem Benutzer nur für die API.

1. Benutzer und Gruppen › Neuer Benutzer: ein Name, ein Login (zum Beispiel api-rechnungen).
2. In der Zeile Token für API auf Erzeugen klicken: Ein Schlüssel mit 32 Zeichen erscheint. Kopieren Sie ihn, dann Benutzer erstellen.
3. Reiter Berechtigungen: nur das Nötige vergeben. Für alles Folgende hat das genügt:

Die Benutzerkarte zeigt den Schlüssel danach als „Versteckt“: Er wird verschlüsselt in der Datenbank gespeichert. Um ihn wieder zu sehen, öffnen Sie die Karte mit Ändern.

3. Der erste Aufruf

Alle Adressen beginnen mit https://ihr-dolibarr/api/index.php/. Der Schlüssel wird im Header DOLAPIKEY übergeben:

DOLI=https://ihr-dolibarr/api/index.php
KEY=ihren_schluessel_hier_einfuegen
curl -s -H "DOLAPIKEY: $KEY" "$DOLI/status"

{
    "success": {
        "code": 200,
        "dolibarr_version": "24.0.1",
        "access_locked": "0"
    }
}

Der Header Authorization: Bearer <Schlüssel> funktioniert ebenfalls. Dolibarr akzeptiert den Schlüssel auch in der Adresse (?DOLAPIKEY=…), dann landet er aber in den Logs von Servern und Proxys: Nehmen Sie lieber den Header.

Die Fehler, die Ihnen begegnen

4. Einen Kunden anlegen

curl -s -X POST -H "DOLAPIKEY: $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Bäckerei Martin", "client": 1}' \
  "$DOLI/thirdparties"

Die Antwort ist einfach die ID des neuen Geschäftspartners, zum Beispiel 1. "client": 1 macht ihn zum Kunden. Einen Geschäftspartner nach Namen suchen:

curl -s -G -H "DOLAPIKEY: $KEY" \
  --data-urlencode "sqlfilters=(t.nom:like:'Bäckerei%')" \
  "$DOLI/thirdparties"

5. Die Rechnung anlegen, dann ihre Zeilen einzeln

Die API nimmt eine Rechnung mit ihren Zeilen in einem einzigen Aufruf an (ein Array lines). Tun Sie das nicht. In unseren Tests änderten die Zeilen ihre Reihenfolge: in der Reihenfolge 1, 2, 3 gesendet, standen sie auf der Rechnung und im PDF als 2, 1, 3, und als 3, 1, 2, wenn der Rang jeder Zeile angegeben war. Beim Anlegen glaubt Dolibarr, jede Zeile zwischen die anderen einzufügen, und verschiebt die Ränge falsch. Derselbe Code steckt in 24.0.2 und im Entwicklungszweig.

Legen Sie zuerst die Rechnung allein an:

curl -s -X POST -H "DOLAPIKEY: $KEY" -H "Content-Type: application/json" \
  -d '{"socid": 1, "type": 0, "date": "2026-10-13"}' \
  "$DOLI/invoices"

Die Antwort ist die ID der Rechnung (hier 4). socid ist die ID des Kunden, "type": 0 steht für eine Standardrechnung. Ein Datum im Format JJJJ-MM-TT wird akzeptiert. Fügen Sie dann jede Zeile in der gewünschten Reihenfolge hinzu:

curl -s -X POST -H "DOLAPIKEY: $KEY" -H "Content-Type: application/json" \
  -d '{"desc": "Installation von Dolibarr", "qty": 1, "subprice": 690, "tva_tx": 19, "product_type": 1}' \
  "$DOLI/invoices/4/lines"

subprice ist der Netto-Einzelpreis, tva_tx der Steuersatz, und product_type ist 1 für eine Dienstleistung, 0 für ein Produkt. Die Rechnung bleibt ein Entwurf, mit einer vorläufigen Referenz wie (PROV4).

6. Die Rechnung freigeben

curl -s -X POST -H "DOLAPIKEY: $KEY" "$DOLI/invoices/4/validate"

Die Antwort enthält die vollständige Rechnung mit ihrer endgültigen Referenz ("ref": "FA2610-0001").

7. Das PDF erzeugen und abrufen

Am Bildschirm erzeugt die Freigabe das PDF. Über die API nicht: Nach der Freigabe enthält der Ordner der Rechnung kein PDF. Fordern Sie es ausdrücklich an, mit der erhaltenen Referenz:

curl -s -X PUT -H "DOLAPIKEY: $KEY" -H "Content-Type: application/json" \
  -d '{"modulepart": "invoice", "original_file": "FA2610-0001/FA2610-0001.pdf", "langcode": "de_DE"}' \
  "$DOLI/documents/builddoc" > /dev/null

Die Datei ist dann in Dolibarr gespeichert, als hätten Sie sie am Bildschirm erzeugt. Zum Herunterladen liefert die API ihren Inhalt base64-kodiert (hier mit jq dekodiert):

curl -s -H "DOLAPIKEY: $KEY" \
  "$DOLI/documents/download?modulepart=invoice&original_file=FA2610-0001/FA2610-0001.pdf" \
  | jq -r .content | base64 -d > FA2610-0001.pdf

8. Die Zahlung erfassen

Eine Zahlung muss einem Konto des Moduls Banken zugeordnet sein: Ohne accountid antwortet die API „Invalid value specified for accountid“. Die ID des Kontos steht in der Adresse seiner Karte (…/compta/bank/card.php?id=1). Die ID der Zahlungsart finden Sie über die API:

curl -s -H "DOLAPIKEY: $KEY" "$DOLI/setup/dictionary/payment_types"

Bei einer Neuinstallation: 2 Überweisung, 3 Lastschrift, 4 bar, 6 Karte, 7 Scheck. Dann:

curl -s -X POST -H "DOLAPIKEY: $KEY" -H "Content-Type: application/json" \
  -d '{"datepaye": "2026-10-13", "paymentid": 2, "closepaidinvoices": "yes", "accountid": 1, "num_payment": "UEB-001"}' \
  "$DOLI/invoices/4/payments"

Mit "closepaidinvoices": "yes" wechselt eine vollständig bezahlte Rechnung in den Status bezahlt.

Der Explorer, für alles Weitere

Unter https://ihr-dolibarr/api/index.php/explorer/ listet Dolibarr alle seine APIs auf. Fügen Sie den Schlüssel oben rechts ein und klicken Sie auf Explore: Ohne Schlüssel erscheint nur die API login. Jeder Aufruf ist dort beschrieben und lässt sich ausprobieren; die Liste hängt von den aktivierten Modulen ab. Dieselbe Beschreibung im Swagger-Format liegt unter /api/index.php/explorer/swagger.json.

Gute Praxis

• Ein Benutzer pro Verwendung (Website, Rechnungswerkzeug, Skript…), jeder nur mit seinen eigenen Berechtigungen: So können Sie einen sperren, ohne die anderen zu berühren.
• Immer über HTTPS: Der Schlüssel reist mit jeder Anfrage.
• Dient die API nur einem bekannten Server, beschränken Sie den Zugriff in den Moduleinstellungen auf dessen IP-Adresse.

Wenn Sie Dolibarr mit einem anderen Programm verbinden möchten, ohne den Code selbst zu schreiben: Das Paket Individuelles Modul beginnt mit einem genauen Angebot.