Bidirektionale Kommunikations-API

Bidirektionale Kommunikations-API von DoliPlus

Die bidirektionale Kommunikations-API von DoliPlus

Die bidirektionale Kommunikations-API von DoliPlus ermöglicht den Maschine-zu-Maschine-Dialog. Konkret verbindet sie Ihr ERP mit anderen Informationssystemen.

Dafür nutzt sie zwei Komponenten: eine REST-API und einen Webhook.

Diese Funktion befindet sich in Entwicklung. Ihre Nutzung erfordert fortgeschrittene Kenntnisse und Erfahrung mit DoliPlus.

Die REST-API nutzen

Zunächst listet eine Swagger-Oberfläche die meisten API-Kommunikationsmöglichkeiten auf (Application Program Interface).

Diese Funktion wird auf speziellen Wunsch freigeschaltet. So kann sie vor dem Produktivbetrieb geprüft und an Ihre Bedürfnisse angepasst werden – gegen Kostenvoranschlag.

Ist das Modul aktiviert, wird DoliPlus zu einem REST-Webservice-Server.

Sie können eigene REST-Anfragen senden. Nutzen Sie dazu die relative URL /api/index.php/xxx, wobei xxx den API-Namen bezeichnet.

Die verfügbaren APIs Ihrer Installation zeigt der API-Explorer an.

So sehen Sie alle bereitgestellten DoliPlus-Webservices. Rufen Sie den Explorer unter folgender Adresse auf:

http://yourdolibarrurl/api/index.php/explorer

Testen Sie den Explorer beispielsweise in der Demo-Instanz:

https://demo.dolibarr.org/api/index.php/explorer

Fügen Sie oben rechts den <token> (API-Schlüssel) des gewünschten Nutzers ein. Klicken Sie dann auf „Explorer“.

Hinweis: Der Token wird im Benutzerprofil festgelegt.

Nach Klick auf „Explorer“ sehen Sie alle verfügbaren Aktionen für diesen Token. Wenige Einträge deuten auf deaktivierte Module hin.

Für Rechnungen aktivieren Sie zuerst das Rechnungsmodul in DoliPlus. Ebenso für Produkte, Kunden/Lieferanten etc.

Im Explorer können Sie umfangreiche Tests durchführen: Daten lesen, schreiben, ändern und löschen.

Achtung: Änderungen wirken direkt auf Ihre Datenbank.

Testen Sie APIs direkt im Explorer – die empfohlene Methode, da alle APIs und Parameter dort dokumentiert sind.

Nach jedem Test erhalten Sie eine Antwort mit Beispielcode für den API-Aufruf.

Für API-Nutzung rufen Sie eine URL wie diese auf:

https://<mein_server>/api/index.php/<aktion>

Nutzen Sie eine der 4 Methoden: GET, POST, PUT, DELETE. Ersetzen Sie <aktion> durch die gewünschte Aktion, z.B.:

https://<mein_server>/api/index.php/invoices

Beispielcode

Es gibt verschiedene Vorgehensweisen. Hier ein Beispielcode. Sie können jedoch auch andere Bibliotheken nutzen.

fonction API REST  callAPI ( $method ,  $apikey ,  $url ,  $data  =  false ) 
{ 
    $curl  =  curl_init (); 
    $httpheader  =  [ 'DOLAPIKEY : ' . $apikey ] ;

    switch  ( $method ) 
    { 
        case  "POST" : 
            curl_setopt ( $curl ,  CURLOPT_POST ,  1 ); 
            $httpheader  []  =  "Content-Type:application/json" ;

            if  ( $data ) 
                curl_setopt ( $curl ,  CURLOPT_POSTFIELDS ,  $data );

            break ; 
        case  "PUT" :

	    curl_setopt ( $curl ,  CURLOPT_CUSTOMREQUEST ,  'PUT' ); 
            $httpheader  []  =  "Content-Type:application/json" ;

            if  ( $data ) 
                curl_setopt ( $curl ,  CURLOPT_POSTFIELDS ,  $data );

            break ; 
        default : 
            if  ( $data ) 
                $url  =  sprintf ( "%s?%s" ,  $url ,  http_build_query ( $data )); 
    }

    // Authentification optionnelle : 
    // curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); 
    // curl_setopt($curl, CURLOPT_USERPWD, "username:password");

    curl_setopt ( $curl ,  CURLOPT_URL ,  $url ); 
    curl_setopt ( $curl ,  CURLOPT_RETURNTRANSFER ,  1 ); 
    curl_setopt ( $curl ,  CURLOPT_HTTPHEADER ,  $httpheader );

    $result  =  curl_exec ( $curl );

    curl_close ( $curl );

    return  $result ; 
}

Dies ist nur ein Arbeitsbeispiel. Es enthält keine Fehlerprüfung und keine Sicherheitsmaßnahmen. Sie können den Code jedoch nutzen und anpassen.

Die Funktion hat 4 Parameter:

$method : String, „GET“, „POST“, „PUT“, „DELETE“
$apikey : String, „Ihr <Token> aus vorheriger Generierung“
$url : String, aufzurufende URL. Z.B.: „http://<mein_server>/api/index.php/invoices“
$data : String, JSON-Daten. Optional.

JavaScript Ajax

< script > 
$ . ajax ({ 
  type :  'GET' , 
  async :  true , 
  contentType :  "application/json; charset=utf-8" , 
  data :  {  'lang' :  'en_US'  }, 
  dataType :  "json" , 
  cache :  false , 
  jsonp :  false , 
  headers :  { 
    'DOLAPIKEY' :  'abcdef123456' 
  }, 
  url :  'https://myserver/api/index., 
success :  function ( rep )  { 
    console . log ( "API-Aufruf erfolgreich" ); 
    console . log ( rep ); 
  }, 
  error :  function ( rep )  { 
    console . log ( "API-Aufruf fehlgeschlagen" ); 
    console . log ( rep ); 
  } 
}); 
< /script>

Felder einer Tabelle abrufen

Nehmen wir zum Beispiel die Tabelle „produits“.

Zunächst ist der einfachste Weg, die Felder zu erhalten, ein oder mehrere Produkte über eine GET-Anfrage aufzulisten.

Alternativ können Sie auch die Konfigurationskonsole aufrufen. Dort gibt es einen Link, um Tabellen zu durchsuchen, vorausgesetzt Sie haben Administratorrechte.

Allerdings werden einige Felder während der Transaktionen umbenannt. So kann „rowid“ zu „id“ werden oder „socid“ für einen Kunden. Daher ist diese Methode nicht zuverlässig für Injection-Zwecke.

Auszug aus der Produkttabelle

Beispiel – Kontakt(e) auflisten

Beispiel – Einen Kontakt erstellen

Bevor Sie einen Kontakt anlegen, kann es sinnvoll sein, zu prüfen, ob er bereits existiert. Zudem erhalten Sie so die Feldstruktur.

Konkret lautet die betreffende Tabelle für die Felder „llx_socpeople“. Hinweis: „socid“ wird anstelle von „fk_soc“ für die Kunden-ID verwendet.

Hier die POST-Anfrage:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'DOLAPIKEY: XXXXX571e9accee5df' -d '
{
"socid": 1 ,
"entity": "1" ,
"civilite": "MR" ,
"name": "TEST" ,
"firstname": "TEST2" ,
"address": "12 rue de fleurs" ,
"cp": "75010" ,
"ville": "PARIS" ,
"poste": "Direktor" ,
"phone_pro": "0413054367" ,
"phone_perso": "0425363212" ,
"phone_mobile": "0606060504" ,
"email": "test@gmail.com" ,
"fk_user_creat": "1" ,
"note": "EE" ,
"note_public": "ZZ" ,
"import_key": "API" ,
"statut": "1"
}
' 'https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts'

Dies sind die relevanten Felder für Testzwecke. Passen Sie sie anschließend an Ihre Daten an.

In diesem Beispiel lautet die erstellte ID 12084.

Hinweis:

Kontakttypen: type

Beispiel – Benutzerdefinierte Felder eines Kontakts erstellen/bearbeiten

Abschließend folgen die Felder der Syntax bei der Extraktion. Sie tragen das Präfix options_: „options_xxxxxx“

{
"options_client": "1",
"options_asso": "aaa,zzz",
"options_compl": "",
"options_test": ""
}

Nun müssen nur noch die Werte eingefügt werden.

Beispiel – Einen Kontakt bearbeiten

Nehmen wir das obige Beispiel mit der ID 20084. Diesmal verwenden Sie die PUT-Anfrage auf die URL: https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084

Beispiel – Einen Kontakt löschen

Nehmen wir erneut das obige Beispiel mit der ID 20084. Diesmal verwenden Sie die DELETE-Anfrage.

curl -X DELETE --header 'Accept: application/json' --header 'DOLAPIKEY: xxxxx0571e9accee5df' 'https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084'

Beispiel – Status eines Angebots ändern

Hier die zu übermittelnden Parameter:

{
„status“ : 2 (angenommen) oder 3 (abgelehnt) ,
„notrigger“: 1 – keine weiteren Ereignisse auslösen ,
„note_private“ : „über API geändert“
}

Beispiel – Produktliste abrufen

Zunächst sind die akzeptierten Parameter teilweise im REST-Explorer dokumentiert.

Dann stehen Ihnen SQL-Filter zur Verfügung. Diese werden nach Überprüfung an die Datenbank weitergegeben. Beispielsweise funktionieren sie beim Produkt-Endpunkt:

(t.fk_product_type: = :’0′) und (t.tosell: = :’1′) und (t.label: ilike :’%string‘)

Schließlich wird für Datumsangaben das ISO-Format akzeptiert: %Y-%m-%d, z.B. 2020-07-14. Das Format aammjj wird hingegen nicht akzeptiert.

Beispiel – Wörterbuch der Kontaktfunktionen für Kunden/Lieferanten abrufen

Zunächst sind die verfügbaren Wörterbücher im Bereich SETUP kategorisiert. Hier verwenden wir daher GET /setup/dictionary/jobs.

Hier ist beispielsweise eine nach Code und Job sortierte Ausgabe:

[ { „code“: „BE“, „job“: „Zeichner / Schätzer / Techniker im Konstruktionsbüro“ }, { „code“: „COMPTA“, „job“: „Buchhaltung / Rechnungsbegleichung“ }, { „code“: „CONCPT“, „job“: „Konzeptentwickler / Verkäufer / Projektleiter“ }, { „code“: „CRAYON“, „job“: „Küchenabteilungsleiter“ },……..]

Beispiel – Kundenpreisliste abrufen

Dieser Aufruf entspricht der Statistikabfrage 507.

Beispiel – Kunden/Lieferanten einer Kategorie abrufen

Beispiel – Dokument versenden

Zum Beispiel im DMS einer Bestellung mit Referenz PRO-CO2007-0254.

Beispiel – Dokument herunterladen

Zum Beispiel für eine Kundenbestellung mit der Referenz PRO-CO2007-0254.pdf.

Beispiel – Dokumente auflisten

Zum Beispiel für eine bestimmte Kundenbestellung mit der ID 456.

Beispiel – Produktbilder auflisten

Zudem enthält die Antwort einen öffentlichen Link „link“. Über diesen gelangen Sie zu den Produktfotos.

Beispiel – Kundenmanager nach Rang auflisten

Sie können auch einen Filter auf eine Kunden-ID anwenden.

Erweiterte Dateneinrichtung über Webhook-Events

Um es einfach auszudrücken: Webhooks lösen eine Aktion nach einem Ereignis aus. Daher werden sie üblicherweise genutzt, um Systeme miteinander kommunizieren zu lassen.

Konkret ist es die einfachste Methode, eine Benachrichtigung zu erhalten. Sie wird nämlich sofort ausgelöst, sobald etwas in einem anderen System passiert.

Anders gesagt: Ein Webhook ist ein HTTPS-Rückruf an die spezifische URL eines Nutzers. Zudem dient er für Echtzeit-Benachrichtigungen. So aktualisiert sich Ihr System unmittelbar, wenn das Ereignis eintritt.

Im Gegensatz dazu erfordert eine klassische API eine kontinuierliche Abfrage. Der Webhook hingegen benachrichtigt Sie, sobald die Information eintrifft. Folglich ist es eine äußerst effiziente Methode, Benachrichtigungen ohne ständige Überprüfung zu erhalten.

Jede Benachrichtigung geht an die Adresse, die Sie in den Einstellungen des API-Moduls hinterlegt haben. Sie enthält die Kennung des Objekts und seinen Zustand: create (Erstellung), update (Änderung) oder delete (Löschung). Beim Empfang fragt Ihre Software die REST-API ab, um die Details des Objekts zu lesen.

Diese Ereignisse werden heute übertragen.

event – send_order (Aufträge)

Eine Benachrichtigung wird bei der Freigabe eines Auftrags (create), bei jeder Änderung (update) und bei der Löschung (delete) gesendet. Auch die Änderung eines benutzerdefinierten Feldes des Auftrags gilt als Änderung.

[
„id“ => Id des Auftrags,
„state“ => create / update / delete
]

event – send_invoice (Rechnungen)

Eine Benachrichtigung wird bei der Freigabe einer Rechnung (create) gesendet, dann bei jeder Änderung, Zahlung, Rückkehr in den Status „unbezahlt“ oder Stornierung (update) und bei der Löschung (delete). Entwürfe werden nicht übertragen: Ihre Software erhält nur echte Rechnungen. Auch die Änderung eines benutzerdefinierten Feldes der Rechnung gilt als Änderung.

[
„id“ => Id der Rechnung,
„state“ => create / update / delete
]

event – send_products (Produkte und Preise)

Eine Benachrichtigung wird bei der Erstellung, Änderung und Löschung eines Produkts gesendet. Sie wird auch gesendet, wenn sich sein Verkaufspreis ändert und wenn ein Lieferantenpreis hinzugefügt, geändert oder gelöscht wird. In diesen beiden Fällen gibt das Feld „change“ an, was sich geändert hat.

[
„id“ => Id des Produkts,
„state“ => create / update / delete,
„change“ => price (Verkaufspreis) / buyprice (Lieferantenpreise) — nur bei einer Preisänderung
]

So aktualisiert Ihre Software die Preise genau des betroffenen Produkts, sobald sie sich ändern. Ein nächtliches Neueinlesen des gesamten Katalogs ist damit überflüssig.

event – send_tiers, send_contacts, send_categories

Ebenso wird eine Benachrichtigung bei der Erstellung, Änderung und Löschung eines Geschäftspartners, eines Kontakts oder einer Kategorie gesendet. Bei Geschäftspartnern und Kontakten enthält die Benachrichtigung direkt deren Kontaktdaten.

event – send_documents

Schließlich wird beim Hinzufügen oder Löschen eines Dokuments in der DoliPlus-Dokumentenverwaltung eines laufenden Auftrags eine Benachrichtigung an die hinterlegte Adresse gesendet.

[
„id“ => Id des Auftrags,
„element“ => commande,
„state“ => add / delete,
„file“ => Dateipfad
]

Beim Empfang dieses Ereignisses ruft Ihre Software über die API die im Auftrag abgelegten Dokumente ab.

Was keine Benachrichtigung auslöst

Ein Massenimport (CSV-Datei mit Produkten oder Einkaufspreisen) schreibt direkt in die Datenbank, ohne diese Ereignisse zu durchlaufen. Planen Sie nach einem Import daher eine einmalige Synchronisierung auf Ihrer Seite ein.

Ihre Preise und Rechnungen in Echtzeit

Sie verbinden DoliPlus mit einer Planungs-, Produktions- oder Shop-Software? Seit September 2026 erfährt diese Software sofort, was sich an Ihren Preisen und Ihrer Fakturierung ändert:

ein geänderter Verkaufspreis oder Lieferantenpreis wird sofort übertragen, Produkt für Produkt;
jede freigegebene, bezahlte oder geänderte Rechnung wird gemeldet, wie es für Aufträge bereits der Fall war;
die benutzerdefinierten Felder Ihrer Aufträge und Rechnungen werden bei jeder Änderung verfolgt.

Der Gewinn ist doppelt. Zum einen arbeitet Ihre andere Software immer mit aktuellen Preisen. Zum anderen entfallen vollständige Katalog-Neueinlesungen, oft nachts geplant, die Ihren Server unnötig belasten.

Weiterführende Informationen

Software verbinden: Ohne Doppeleingabe oder Code — verknüpfen Sie Ihre Software, ohne Doppeleingabe oder Entwicklung.

Dolibarr DoliPlus

Bidirektionale Kommunikations-API von DoliPlus