Module Web Services API REST (développeur)

From Dolibarr ERP CRM Wiki
Revision as of 19:18, 23 May 2017 by Chagam (talk | contribs) (ajout premiers paragraphes depuis version anglaise)
Jump to navigation Jump to search

Return to developer
documentation index

File Doc dev.png

Return to
list of modules index
Art.png

Web services
Numero/ID of module 2610
User doc. of module Non applicable
Developer doc. of 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.

Seveur de Web services REST Dolibarr

Une fois que le module webservices REST est activé, Dolibarr devient également un serveur de Web services REST. Vous pouvez alors envoyer vos propres requetes sur l'url relative : /api/index.php

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.

Vous devez au préalable faire un premier appel au service login pour obtenir une clé API. Vous entrez alors la clé pour obtenir la liste des services proposés

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

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

Ajouter un nouveau service

Ajouter un nouveau service est aussi facile qu'ajouter un fichier nommé api_monmoduleobject.class.php dans le dossier htdocs/module/class. Vous trouverez des exemples dans htdocs/commande/class/api_orders.class.php

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/module/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

Installation

Pour installer, aller dans la page des modules et activer le module API REST. Dans la page de configuration du module, il y a 2 liens. Pas la peine de cliquer sur le premier, il ne fonctionne pas en l'état.

Le lien a cette forme : http://<mon serveur>/api/index.php/login?login=<mon login utilisateur>&password=yourpassword
copiez le lien, remplacez yourpassword par votre mot de passe utilisateur. Normalement, <mon serveur> et <mon login utilisateur> sont déjà remplacés. collez le lien dans votre navigateur pour générer votre <token>. ce dernier est lié à votre compte utilisateur.

Notez bien ce <Token> dans un coin !!!

Maintenant, vous pouvez aller sur le 2nd lien de la page de configuration du module. En haut a droite, coller le <token> puis cliquez sur explore. Normalement, vous allez voir apparaître toutes les actions accessibles avec ce <token>. Si vous n'avez pas beaucoup d'actions, c'est certainement que les modules ne sont pas activés. Par exemple, si vous voulez voir les factures (invoices), il faut activer le module adéquat dans votre configuration Dolibarr. Idem pour produits, etc. Pour information, Thirdparties, ce sont les Tiers.
Sur cette page d'exploration de l'API, vous pouvez faire pas mal de tests. aussi bien en lecture qu'en écriture, modification ou suppression

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

Pour ce faire, il existe plusieurs méthodes. Voici un morceau de code mais il existe également des librairies 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</nowiki" * $data : string flux au format json. ce champ n'est pas obligatoire. = Exemples = Maintenant, quelques exemples.<br/> dans tous les cas : * $apiKey = "mon <token>"; * $apiUrl = "<nowiki>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

Conclusion

Vous trouverez pas mal d'autres informations dans le code de Dolibarr, en regardant dans htdocs/<dossier>/class/api_xxx_class.php
Ex : htdocs/societe/class/api_thirdparties.class.php pour les tiers.
les factures se trouvent dans htdocs/compta/facture/class

Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_Web_Services_API_REST_(développeur)&oldid=37350"