Module Web Services API REST (développeur)

Retour index
Documentation développeur

Retour index
liste des modules

Web services
Numéro/ID du module	2610
Doc utilisateur du module	Non applicable
Doc développeur du module	Cette page

Fonction

Quand ce module est activé, vous activez l'utilisation des Webservices fournis par Dolibarr. Vous pouvez alors faire des appels REST sur différents Webservices fournis par Dolibarr.

Installation

Pour l'installer, ouvrez la page des modules et activez le module "API REST".

Une fois que le module Web services REST est activé, Dolibarr devient également un serveur de Web services REST. Vous pouvez alors envoyer vos propres requêtes sur l'url relative : /api/index.php/xxx où xxx est l'API à appeler.

Liste des services fournis

Seuls quelques services sont disponibles. À compter de la version 5.0 de Dolibarr, vous pouvez consulter la liste complète des web services proposés en appelant l'explorer à cette adresse :

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

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

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

Dans le coin supérieur droit, collez le <token> de l'utilisateur que vous souhaitez utiliser pour appeler l'API, puis cliquez sur le bouton "explorer". Remarque: Le jeton de chaque utilisateur peut être défini sur la page d'enregistrement de l'utilisateur.

Vous pouvez aussi préférer faire un premier appel au service login pour obtenir le jeton API. Vous aurez en réponse le jeton à utiliser pour obtenir et appeler la liste des services proposés.

Après avoir saisi le jeton et cliqué sur "Explore", 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 voulez voir les factures, vous devez activer le module Factures dans la configuration de Dolibarr. Même chose pour les Produits, les Tiers, etc.

Vous pouvez ensuite tester directement à partir de cet explorateur n'importe quelle API. Ceci est la solution recommandée pour tester toute API Dolibarr, car toutes les API et paramètres sont documentés ici. À la suite d'un test, vous obtiendrez la réponse, mais également un exemple sur la façon d'appeler l'API à partir de la ligne de commande à l'aide de curl.

Sur cette page d'exploration de l'API, vous pouvez faire beaucoup de tests. Lire des données de Dolibarr et écrire, modifier et supprimer également. Attention: les données sont vraiment modifiées dans votre base de données.

Utilisation

Grosso modo, pour utiliser REST, il faut appeler une url du genre suivant http://<mon_serveur>/api/index.php/<action>
avec une des 4 méthodes : GET, POST, PUT, DELETE, en remplaçant <action> par l'action sur laquelle vous voulez intervenir. Ex : http://<mon_serveur>/api/index.php/invoices

Avant d'utiliser une API, vous devez d'abord obtenir une clé API personnalisée. Vous devez créer un nouvel utilisateur et générer ou définir sa "clé pour l'API".

Vous devrez utiliser cette clé API dans n'importe lequel de vos programmes clients devant appeler une API Dolibarr.

Pour ce faire, il existe plusieurs méthodes. Voici un morceau de code opérationnel pour appeler une API, mais il existe également des librairies qui simplifie le travail, telles que phphttpclient.com.

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

    // Optional Authentication:
	//    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;
}

Ce n'est qu'un exemple, ce n'est pas sécurisé, cela ne prend pas en compte les codes erreurs mais vous pouvez le modifier et l'adapter à vos besoins. la fonction prend 4 paramètres :

• $method : string "GET", "POST", "PUT", "DELETE"
• $apikey : string "votre <token> généré plus haut"
• $url : string l'url à appeler. Ex : "http://<mon_serveur>/api/index.php/invoices"
• $data : string flux au format json. Ce champ est requis pour les appels POST ou PUT.

Exemples avec PHP

Maintenant, quelques exemples opérationnels pour différents cas d'utilisation.

Dans tous les cas, on a :

• $apiKey = "<mon token>";
• $apiUrl = "http://<mon_serveur>/api/index.php/";

// Récupérer la liste des produits
	$listProduits = [];
	$produitParam = ["limit" => 10000, "sortfield" => "rowid"];
	$listProduitsResult = CallAPI("GET", $apiKey, $apiUrl."products", $produitParam);
	$listProduitsResult = json_decode($listProduitsResult, true);

	if (isset($listProduitsResult["error"]) && $listProduitsResult["error"]["code"] >= "300") {
	} else {
		foreach ($listProduitsResult as $produit) {
			$listProduits[intval($produit["id"])] = html_entity_decode($produit["ref"], ENT_QUOTES);
		}
	}

Commentaires :

• récupérer les 10'000 premiers produits triés par leur id dans la base
• html_entity_decode est nécessaire car les apostrophes sont encodés
• il est facile d'utiliser la même méthode (en remplaçant products par dictionnarycountries) pour récupérer la liste des pays

// Créer un produit
	$ref = "ma_reference_produit_X203ZZ";
	$newProduct = [
		"ref"	=> $ref,
		"label"	=> $ref
	];
	$newProductResult = CallAPI("POST", $apiKey, $apiUrl."products", json_encode($newProduct));
	$newProductResult = json_decode($newProductResult, true);

Commentaires :

• avant de créer un produit, il peut être sage de vérifier qu'il existe. En reprenant le premier exemple, cela fait :

// ma référence
	$ref = "ma_reference_produit_X203ZZ";
// existe-t-elle dans mon tableau
	$produitKey = array_search($ref, $listProduits);
	if ($produitKey) {
// oui
		$fk_product = $produitKey;
	} else {
// non
// Créer un produit
		$newProduct = [
			"ref"	=> $ref,
			"label"	=> $ref
		];
		$newProductResult = CallAPI("POST", $apiKey, $apiUrl."products", json_encode($newProduct));
		$newProductResult = json_decode($newProductResult, true);
		if (isset($newProductResult["error"]) && $newProductResult["error"]["code"] >= "300") {
// il y a eu une erreur
			echo "<pre>ERROR", var_dump($newProductResult), "</pre>";
			exit;
		} else {
// tout va bien
			$fk_product = $newProductResult;
			$listProduits[$fk_product] = $ref;
		}
	}

Commentaires :

• je regarde si la référence de mon article existe dans le tableau créé dans le premier exemple.
• si elle existe, j'utilise sa clé dans le tableau comme id
• si elle n'existe pas, je crée l'article puis le j'ajoute à mon tableau pour les prochaines fois et je récupère l'id créé
• cette méthode permet de limiter les appels API quand on doit importer 500 commandes par exemple. Récupérer une fois la liste des produits au début au lieu de chercher à chaque fois dans Dolibarr.

// créer une commande avec 2 articles

// le tableau qui contiendra toutes les lignes d'articles de la commande
	$newCommandeLine = [];

// article 1
	$ref1 = "ma_reference_produit_X203ZZ";
	$prix1 = 10;
	$qtt1  = 100;
	$tva1 = 20;
	$fk_product1
// article 2
	$ref2 = "ma_reference_produit_B707FD";
	$prix2 = 13;
	$qtt2  = 37;
	$tva2 = 20;

	$newCommandeLine[] = [
		"desc"		=> $ref1,
		"subprice"	=> $prix1,
		"qty"		=> $qtt1,
		"tva_tx"	=> floatval($tva1),
		"fk_product"=> $fk_product1
	];

	$newCommandeLine[] = [
		"desc"		=> $ref2,
		"subprice"	=> $prix2,
		"qty"		=> $qtt2,
		"tva_tx"	=> floatval($tva2),
		"fk_product"=> $fk_product2
	];

	if (count($newCommandeLine) > 0) {
		$newCommande = [
			"socid"			=> $clientDoliId,
			"type" 			=> "0",
			"lines"			=> $newCommandeLine,
			"note_private"	=> "Commande importée automatiquement depuis l'application",
		];
		$newCommandeResult = CallAPI("POST", $apiKey, $apiUrl."orders", json_encode($newCommande));
		$newCommandeResult = json_decode($newCommandeResult, true);
	}

Commentaires :

• $clientDoliId vaut l'id du client dans la base doli. Soit vous le connaissez, soit vous pouvez le chercher auparavant
• type => 0, c'est une commande client (par opposition à 1 = commande fournisseur)

// Valider une commande 
	$newCommandeValider = [
		"idwarehouse"	=> "0",
		"notrigger"		=> "0"
	];
	$newCommandeValiderResult = CallAPI("POST", $apiKey, $apiUrl."orders/".$newCommandeResult."/validate", json_encode($newCommandeValider));
	$newCommandeValiderResult = json_decode($newCommandeValiderResult, true);

Commentaires :

• on voit dans cet exemple, en avant dernière lignes, on a : $apiUrl."orders/".$newCommandeResult."/validate".
  

$newCommandeResult est l'id de la commande crée (récupéré dans l'exemple précédent)

// chercher si le client existe dans la base
	$clientSearch = json_decode(CallAPI("GET", $apiKey, $apiUrl."thirdparties", array(
		"sortfield" => "t.rowid", 
		"sortorder" => "ASC", 
		"limit" => "1", 
		"mode" => "1",
		"sqlfilters" => "(t.nom:=:'".$nom_client."')"
		)
	), true);

Commentaires :

• limit => 1 pour ne renvoyer que 1 client
• mode => 1 car on cherche un client (on aurait aussi pu chercher un fournisseur qui est aussi un tiers mais avec un statut différent)
• sqlfilters syntaxe un peu particulière mais il y a qq autres exemples sur la page d'explorer d'API

//client n'existe pas. le crée puis on récupère son id
	$newClient = [
		"name" 			=> "nom société client",
		"email"			=> "email société client",
		"client" 		=> "1",
		"code_client"	=> "-1"
	];
	$newClientResult = CallAPI("POST", $apiKey, $apiUrl."thirdparties", json_encode($newClient));
	$newClientResult = json_decode($newClientResult, true);
	$clientDoliId = $newClientResult;

Commentaires :

• client => 1 car c'est un client (et pas un fournisseur)
• code_client => -1 pour que le code client soit généré automatiquement.
• on récupère l'id du client dans $clientDoliId

Développer un nouveau service / sa propre API

Ajouter un nouveau service est aussi facile qu'ajouter un fichier nommé api_monmoduleobject.class.php dans le dossier htdocs/monmodule/class. Si vous utilisez le "modulebuilder" pour développer sur Dolibarr, cette API avec les méthode CRUD pourra même être générée pour vous. Sinon, un copié-collé d'un fichier API existant fera l'affaire. Vous pouvez prendre comme exemple le fichier dans htdocs/commande/class/api_orders.class.php et l'adapter à votre classe / besoin.

Le framework détecte automatiquement les API et elle devrait être visible dans l'explorateur.

Les méthodes et paramètres sont détectées en fonction de l'introspection réalisée dans les classes PHP de l'objet (htdocs/monmodule/class/object.class.php) en utilisant les annotations trouvées dans la classe.

Pour une documentation à propos des annotations : https://github.com/Luracast/Restler/blob/master/ANNOTATIONS.md

Vous trouverez pas mal d'autres informations dans le code de Dolibarr. Vous trouverez tous les fichiers API de Dolibarr sous le nom htdocs/<dossier>/class/api_xxx_class.php