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:

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:

Beispiel – Kundenpreisliste abrufen

Dieser Aufruf entspricht der Statistikabfrage 507.

Beispiel – Kunden/Lieferanten einer Kategorie abrufen

Beispiel – Dokument versenden

Zum Beispiel in der Dokumentenbibliothek 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.

Zur Veranschaulichung haben wir beispielsweise diese Ereignisse während einer Entwicklung implementiert.

event – send_documents

Zunächst: Beim Hochladen oder Löschen eines Dokuments in der DoliPlus-Dokumentenbibliothek, die mit dem Auftrag verknüpft ist, wird eine Benachrichtigung an die spezifische URL gesendet.

Sie enthält folgende Informationen:

Anschließend nutzt das Kundensystem bei Empfang dieses Ereignisses die API. So ruft es die hochgeladenen Dokumente im Auftrag ab, um sein Informationssystem zu aktualisieren.

events – send_order

Weiterführende Informationen

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