Dolibarr API

Dolibarr Api : module web API REST

Si ce module est activé, les services web fournis par Dolibarr sont activés. Vous pouvez alors faire des appels REST aux différents services web fournis par Dolibarr.

Installation

Pour l’installer, allez à la page des modules et activez le module « REST API ».

Après avoir activé le module REST web services, Dolibarr deviendra également un serveur REST web services. Vous pouvez ensuite envoyer des demandes personnalisées à l’adresse relative : /api/index.php/xxx, où xxx est l’API à appeler.

Liste des services fournis

Seuls quelques services sont disponibles. A partir de Dolibarr 5.0, la liste complète des services web peut être consultée en appelant le navigateur à l’adresse suivante.

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

Par exemple, vous pouvez essayer une copie de démonstration du navigateur à l’adresse suivante.

Dans le coin supérieur droit, collez le de l’utilisateur que vous voulez utiliser pour appeler l’API, puis cliquez sur le bouton « explorer ». Notes : Le jeton pour chaque utilisateur peut être défini sur la page d’enregistrement de l’utilisateur.

Vous pouvez également choisir d’effectuer le premier appel au service de connexion pour obtenir le jeton d’API. En réponse, vous recevrez un jeton à utiliser pour récupérer et appeler la liste des services offerts.

En saisissant le jeton et en cliquant sur « Explorer », vous verrez toutes les actions disponibles avec ce jeton. Si vous ne voyez pas beaucoup d’actions, c’est peut-être parce que le module concerné n’a pas été activé. Si vous voulez voir les factures, vous devez activer le module Factures dans la configuration de Dolibarr. Il en va de même pour les produits, les tiers, etc.

Vous pouvez alors tester n’importe quelle API directement à partir de cet explorateur. C’est la solution recommandée pour tester les APIs de Dolibarr car toutes les APIs et les paramètres sont documentés ici. Après le test, vous obtiendrez la réponse ainsi qu’un exemple de la façon d’appeler l’API à partir de la ligne de commande en utilisant curl.

Vous pouvez exécuter de nombreux tests sur cette page d’exploration de l’API. Lire les données de Dolibarr, ainsi que les écrire, les modifier et les supprimer. Attention : les données de votre base de données ont bien été modifiées.

Utilisation

En gros, pour utiliser REST, vous devez appeler une url comme http:///api/index.php/.
En utilisant l’une des 4 méthodes GET, POST, PUT, DELETE, en remplaçant par l’action sur laquelle vous souhaitez intervenir. Par exemple : http:///api/index.php/invoices

Il existe plusieurs méthodes pour y parvenir. Vous trouverez ci-dessous un code opérationnel pour appeler l’API, mais il existe également des bibliothèques qui simplifient la tâche, comme 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 généré plus haut »
• $url : string l’url à appeler. Ex : « http:///api/index.php/invoices »
• $data : string flux au format json. Ce champ est requis pour les appels POST ou PUT.

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

Dans tous les cas, on a :

• $apiKey = «  »;
• $apiUrl = « http:///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 "
ERROR", var_dump($newProductResult), "
";
			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