L’API de communication bidirectionnelle de DoliPlus

L’API de communication bidirectionnelle de DoliPlus met en place un dialogue de machine à machine. Concrètement, elle relie votre ERP à vos autres systèmes d’information.

Pour cela, elle s’appuie sur deux briques. D’abord une API REST. Ensuite un Webhook.

Cette fonctionnalité est en cours de développement. Par ailleurs, elle ne fait pas partie de la distribution standard.

De plus, son emploi requiert des compétences avancées et une bonne connaissance de DoliPlus.

Enfin, le support facture toute explication et toute assistance. En effet, cet outil reste peu documenté et il est surtout utilisé par nos équipes de développement.

Utiliser l’API REST

D’abord, une interface de type Swagger liste la plupart des communications possibles via l’API (Application Program Interface).

Par ailleurs, cette fonctionnalité s’ouvre sur demande spéciale. Ainsi, elle peut faire l’objet de vérifications et d’améliorations avant la mise en production, selon vos besoins et sur devis.

Concrètement, une fois le module activé, DoliPlus devient aussi un serveur de webservices REST.

Vous pouvez donc envoyer votre propre requête REST. Pour cela, ciblez l’URL relative /api/index.php/xxx, où xxx désigne le nom de l’API à appeler.

De plus, la liste des API de votre installation reste disponible via l’explorateur d’API.

Ainsi, vous pouvez voir la liste complète des services Web DoliPlus fournis. Pour commencer, appelez l’explorateur à l’adresse suivante :

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

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

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

Ensuite, dans le coin supérieur droit, collez le <token> (jeton API) de l’utilisateur souhaité. Puis cliquez sur le bouton « Explorer ».

Remarque : le jeton de chaque utilisateur se définit 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 en voyez peu, c’est sans doute que les modules correspondants restent désactivés.

Par exemple, pour voir les factures, activez d’abord le module de facturation dans la configuration de DoliPlus. De même pour les produits, les tiers, et ainsi de suite.

Sur cette page d’exploration, vous pouvez donc faire pas mal de tests. En effet, vous lisez les données de DoliPlus, mais aussi vous les écrivez, les modifiez et les supprimez.

Attention toutefois : les données sont réellement modifiées dans votre base.

Ensuite, vous pouvez tester directement n’importe quelle API depuis l’explorateur. C’est d’ailleurs la solution recommandée, car toutes les API et tous les paramètres y sont documentés.

Par conséquent, après chaque test, vous obtenez la réponse. De plus, vous récupérez un exemple sur la façon d’appeler l’API.

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

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

Utilisez l’une des 4 méthodes suivantes : GET, POST, PUT, DELETE. Remplacez ensuite <action> par l’action voulue. Ex :

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

Exemple de codes

Il existe différentes façons de procéder. Voici par exemple un morceau de code. Cependant, vous pouvez aussi 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 );

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

Ceci est juste un exemple de travail. En effet, il n’y a pas de contrôle d’erreur et la sécurité n’a pas été prise en compte. Cependant, vous pouvez utiliser ce code, puis le modifier selon vos besoins.

Par ailleurs, la fonction prend 4 paramètres :

• $method : 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. De plus, ce paramètre n’est pas obligatoire.

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., 
succès :  fonction ( rep )  { 
    console . log ( "Succès de l'appel API" ); 
    console . log ( rep ); 
  }, 
  erreur :  fonction ( rep )  { 
    console . log ( "Erreur d'appel API" ); 
    console . log ( rep ); 
  } 
}); 
< /script>

Obtenir les champs de la table

Prenons par exemple la table produits.

D’abord, pour obtenir ses champs, le plus simple est de lister un ou plusieurs produits via une requête GET.

Ensuite, vous pouvez aussi vous rendre sur la console de configuration. En effet, un lien y permet d’explorer les tables, sous réserve d’un droit administrateur.

En revanche, certains champs sont renommés lors des transactions. Ainsi, rowid peut devenir id, ou socid pour un tiers. Par conséquent, 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 déjà. De plus, cela permet d’obtenir la structure des champs.

Concrètement, la table concernée est llx_socpeople pour les champs. À noter : on utilise socid en lieu et place de fk_soc pour l’ID du tiers.

Voici donc la 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'

Ce sont les champs utiles à injecter dans l’interface pour tester. Ensuite, adaptez-les 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

Pour finir, les champs reprennent la syntaxe employée lors de l’extraction. Ainsi, ils portent le préfixe options_ : « options_xxxxxx »

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

Il ne reste plus qu’à insérer les valeurs.

Exemple – Modifier un contact

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

Exemple – Supprimer un contact

Reprenons à nouveau l’exemple ci-dessus avec l’ID 20084. Cette fois, utilisez 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

Voici par exemple les paramètres à transmettre :

Exemple – Appeler une liste de produits

Tout d’abord, les paramètres acceptés sont en partie documentés dans l’explorateur REST.

Ensuite, vous disposez de filtres SQL. Ceux-ci sont transmis à la base après vérification. Par exemple, ils fonctionnent sur le point de terminaison du produit :

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

Enfin, côté date, le format ISO est accepté : %Y-%m-%d, par exemple 2020-07-14. En revanche, le format aammjj n’est pas accepté.

Exemple – Appeler un dictionnaire de fonctions de contacts de tiers

D’abord, les dictionnaires disponibles sont classés dans la rubrique SETUP. Ici, on utilise donc GET /setup/dictionary/jobs.

Voici par exemple une sortie ordonnée par code et job :

Exemple – Appeler une liste de prix client

Cet appel correspond à la requête de statistique 507.

Exemple – Appeler de tiers appartenant à une catégorie

Exemple – Envoyer un document

Par exemple, sur la G.E.D d’une commande réf PRO-CO2007-0254.

Exemple – Télécharger un document

Par exemple, pour une commande client avec la réf PRO-CO2007-0254.pdf.

Exemple – Lister les documents

Par exemple, pour une commande client donnée avec l’Id 456.

Exemple – Lister les images de produits

Par ailleurs, un lien public « link » figure dans la réponse. Grâce à lui, vous accédez aux photos des produits.

Exemple – Lister les gestionnaires client par rang

Ensuite, vous pouvez aussi ajouter un filtre sur un ID client.

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

Pour faire simple, les webhooks déclenchent une action après un événement. Ainsi, on les utilise généralement pour faire communiquer des systèmes.

Concrètement, c’est la façon la plus simple de recevoir une alerte. En effet, elle se déclenche dès que quelque chose se produit dans un autre système.

Autrement dit, un webhook est un rappel HTTPS vers l’URL spécifique d’un utilisateur. De plus, il sert aux notifications en temps réel. Ainsi, votre système se met à jour dès que l’événement survient.

En revanche, une API classique exige une interrogation continue. Le webhook, lui, vous prévient quand l’information arrive. Par conséquent, c’est un moyen très efficace de recevoir des notifications sans vérification permanente.

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

event – send_documents

D’abord, au dépôt ou à la suppression d’un document dans la G.E.D DoliPlus attachée à la commande, une notification part vers l’URL spécifique.

Elle contient alors les informations suivantes :

Ensuite, à la réception de cet événement, le système du client utilise l’API. Ainsi, il va chercher les documents déposés dans la commande pour mettre à jour son système d’information.

events – send_order