Api de communication bidirectionnelle Dolibarr & DoliPlus

Une API Rest et un Webhook permettent de mettre en place un dialogue de machine à machine entre DoliPlus et d’autres systèmes d’information de l’entreprise.

Cette fonctionnalité est en cours de développement et ne fait pas partie de la distribution standard.

Utiliser cet outil requière des compétences avancées et une connaissance de Dolibarr et DoliPlus.

Le support facture toutes explications, sur son emploi et toute assistance, car cet outil est assez peu documenté et reste utilisé par nos équipes de développements.

Utiliser l’API REST

Une interface type swagger permet de lister la plus part des possibilités de communications via API (Application Program Interface).

Cette fonctionnalité est ouverte sur demande spéciale et peut faire l’objet d’un travail de vérifications, améliorations avant sa mise en service en production selon des besoins spécifiques sur devis.

Une fois le module activé, Dolibarr devient également un serveur de webservices REST.

Vous pouvez donc envoyer votre propre requête REST à l’URL relative /api/index.php/xxx où xxx est le nom de l’API à appeler.

Une liste des API de votre installation est disponible via l’explorateur d’API.

Liste des services fournis. Vous pouvez voir la liste complète des services Web Dolibarr fournis, en appelant l’explorateur ici à l’adresse :

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

Par exemple, vous pouvez essayer l’explorateur sur l’instance de démonstration à l’adresse :

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

Dans le coin supérieur droit, collez le <token> (jeton APi)  de l’utilisateur que vous souhaitez utiliser pour appeler l’API et cliquez sur le bouton « explorer ».

Remarque : Le jeton de chaque utilisateur peut être défini sur la page d’enregistrement de l’utilisateur.

Après avoir cliqué sur « Explorer », vous devriez voir toutes les actions disponibles avec ce jeton. Si vous n’avez pas beaucoup d’actions, c’est probablement parce que les modules correspondants ne sont pas activés. Si vous souhaitez voir les factures, vous devez activer le module de facturation dans la configuration de Dolibarr. Idem pour les produits, les tiers et ainsi de suite.

Sur cette page d’exploration de l’API, vous pouvez faire pas mal de tests. Lecture des données de Dolibarr et écriture, modification et suppression également. Attention : Les données sont réellement modifiées dans votre base de données.

Vous pouvez ensuite tester directement depuis l’outil explorateur n’importe quelle API. C’est la solution recommandée pour tester n’importe quelle API Dolibarr puisque toutes les API et paramètres sont documentés ici. À la suite de tout test, vous obtiendrez la réponse mais également un exemple sur la façon d’appeler l’API.

Pour utiliser l’API REST, vous devez appeler une URL telle que celle-ci :

https://<mon_serveur>/api/index.php/<action>

Avec l’une des 4 méthodes suivantes : GET, POST, PUT, DELETE, en remplaçant <action> par l’action que vous souhaitez utiliser. Ex :

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

Exemple de codes

Il existe différentes façons de le faire. Voici un morceau de code, mais vous pouvez également utiliser d’autres bibliothèques.

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 );

            casser ; 
        cas  "PUT" :

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

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

            casser ; 
        par défaut : 
            if  ( $data ) 
                $url  =  sprintf ( "%s?%s" ,  $url ,  http_build_query ( $data )); 
    }

    // Authentification facultative : 
    // 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 );

    $résultat  =  curl_exec ( $curl );

    curl_close ( $curl );

    retourne  $résultat ; 
}

Ceci est juste un exemple de travail. Il n’y a pas de contrôle d’erreur et la sécurité n’a pas été prise en compte mais vous pouvez utiliser ce code, le modifier selon vos besoins
La fonction a 4 paramètres :

• $méthode : chaîne, « GET », « POST », « PUT », « DELETE »
• $apikey : string, « votre <token> généré plus tôt »
• $url : chaîne, url à appeler. Ex : « http://<mon_serveur>/api/index.php/invoices »
• $data : string, données au format json. Ce paramètre n’est pas obligatoire.

JavascriptAjax

< script > 
$ . ajax ({ 
  type :  'GET' , 
  async :  true , 
  contentType :  "application/json; charset=utf-8" , 
  data :  {  'lang' :  'en_US'  }, 
  dataType :  "json" , 
  cache :  false , 
  jsonp :  false , 
  en-têtes :  { 
    'DOLAPIKEY' :  'abcdef123456' 
  },  
  url :  'https://myserver/api/index., 
  succès :  fonction ( rep )  { 
    console . log ( "Succès de l'appel API" ); 
    consoler . journal ( rep ); 
  }, 
  erreur :  fonction ( rep )  { 
    console . log ( "Erreur d'appel API" ); 
    consoler . journal ( rep ); 
  } 
}); 
< /script>

Obtenir les champs de la table

Exemple table produits :

Pour obtenir les champs de la table produits, le plus simple est de lister un ou plusieurs produits afin d’obtenir dans une requête GET afin

Il est possible également de se rendre sur la console de configuration, un lien est disponible pour explorer les tables – un droit administrateur est requis. En revanche, certains champs peuvent être renommés lors des transactions, rowid peut devenir id ou socid pour un tiers. Donc cette méthode n’est pas fiable pour réaliser des injections.

Extrait de la table produit

Exemple – Lister des/un contact(s)

Exemple – Créer un contact

Avant de créer un contact, il peut être judicieux de vérifier s’il existe et également pour obtenir la structure des champs.

Table concernée  llx_socpeople pour les champs. A noter socid en lieu et place de fk_soc pour l’ID du tiers.

Requête POST

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": "Directeur" ,
"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'

Champs utiles principaux à injecter dans l’interface pour tester adapter selon, vos données.

Dans cet exemple l’ID créé est le 12084.

Nota :

Type de contacts: type

Exemple – Créer/modifier les champs personnalisés d’un contact

Les champs reprennent la même syntaxe utilisée lors de l’extraction avec le préfixe options_ : « options_xxxxxx »

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

Insérer les valeurs

Exemple – Modifier un contact

Reprenons l’exemple ci-dessus avec l’ID 20084, avec la requête PUT  sur l’URL : https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084

Exemple – Supprimer  un contact

Reprenons l’exemple ci-dessus avec l’ID 20084, avec la requête DELETE

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

Exemple – Modifier le statut d’une proposition

Exemple de paramètres :

Exemple – Appeler une liste de produits

Paramètres acceptés, cela est quelque peu documenté dans l’explorateur REST.

filtres sql
Ils sont transmis à la base de données après vérification. Ceux-ci fonctionnent sur le point de terminaison du produit :

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

Date
Le format de date ISO est accepté : %Y-%m-%d par exemple 2020-07-14. aammjj n’est pas accepté.

Exemple – Appeler un dictionnaire de fonctions de contacts de tiers

Les dictionnaires disponibles sont classés dans la rubrique  SETUP, ici on utilise GET /setup/dictionary/jobs

Exemple de sortie ordonnée par code et job

Exemple – Appeler une liste de prix client

Correspond à la requête de statistique 507.

Exemple – Appeler de tiers appartenant à une catégorie

Exemple – Envoyer un document

Sur la G.E.D d’une commande réf PRO-CO2007-0254

Exemple – Télécharger un document

Pour une commande client avec Réf PRO-CO2007-0254.pdf

Exemple – Lister les documents

Pour une commande client donnée avec pour Id 456

Exemple – Lister les images de produits

Un lien publique «link» est disponible dans la réponse pour accéder aux images de photos des produits

Exemple – Lister les gestionnaires client par rang

Ajouter un filtre sur un ID client

Mise en place de données poussée via Webhook events.

Pour faire simple, les webhooks permettent de déclencher une action suite à un événement. Ils sont généralement utilisés pour faire communiquer des systèmes. C’est la façon la plus simple de recevoir une alerte lorsque quelque chose se produit dans un autre système.

Un webhook est un rappel HTTPS à l’URL spécifique d’un utilisateur. Les webhooks sont utilisés pour les notifications en temps réel, de sorte que votre système peut être mis à jour dès que l’événement se produit.

Au contraire d’une API qui requiert que vous l’interrogiez en continu, les Webhooks vous font savoir quand l’information a été reçue, c’est un moyen très efficace de recevoir des notifications en s’affranchissant d’une vérification continuelle : la mise à jour est immédiate lorsque l’évènement se produit.

Pour illustrer la fonctionnalité, nous avons par exemple mis en place par exemple au cours d’un développement ces événements :

event – send_documents

Au dépôt, ou suppression d’un document dans l’explorateur de document G.E.D Doliplus attaché à la commande, une notification est envoyée sur l’URL spécifique, avec les informations suivantes :

Suite à la réception de cet événement le système du client utilise l’Api pour aller chercher les documents déposés dans la commande pour mettre à jour son système d’information.

events – send_order