提供REST API的Web服務模塊（開發者）

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search


返回
開發文檔

File Doc dev.png

返回
標準模塊列表
Art.png

Web services
模塊ID 2610
用戶手冊 不適用
開發文檔 本頁

功能

激活此模塊後，您就可以調用Dolibarr提供的Webservices。然後，您可以對Dolibarr提供的各種Web服務進行REST調用。

安裝

要安裝它，請打開 主頁->設置->模塊/應用 並激活"API / Web 服務 (REST 服務器)"模塊。

激活 API / Web 服務 (REST 服務器) 模塊後，Dolibarr 將成為REST Web服務器。您可以在相應的URL上發送自己的REST請求 ： /api/index.php/xxx 其中xxx是要調用的API的名稱。

Apache的設置

沒有什麼可做的。如果您的Dolibarr正在使用Apache，那麼REST API也應該可以工作。APIs將由與您的應用程序相同的虛擬web服務器提供服務。

Nginx的設置

像Apache一樣，如果您的Dolibarr在Nginx虛擬主機中工作，那麼您不用為APIs做任何事情。APIs將由與您的應用程序相同的虛擬web服務器提供服務。

但是，Nginx在許多發行版上的默認設置通常是gaz引擎，您可能會遇到麻煩。如果遇到這樣的問題，可以嘗試編輯Nginx配置文件以匹配以下示例。這是一個簡單的本地主機設置，提供有效的REST API處理（在parabola gnu/linux上用9.0.1測試）。 

worker_processes  1;
error_log  /var/log/nginx/error.log;

events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    #access_log  logs/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;

    server {
    	listen		80;
        server_name     dolibarr.localhost; # adjust to your domain

        root    /usr/share/webapps/dolibarr/htdocs; # adjust to your path 
        index   index.php;

        # from https://github.com/Dolibarr/dolibarr/issues/6163#issuecomment-391265538
        location ~ [^/]\.php(/|$) {
            fastcgi_split_path_info ^(.+?\.php)(/.*)$;
            if (!-f $document_root$fastcgi_script_name) {
                return 404;
            }

            # Mitigate https://httpoxy.org/ vulnerabilities
            fastcgi_param HTTP_PROXY "";

            root           /usr/share/webapps/dolibarr/htdocs;
            fastcgi_pass   unix:/run/php-fpm/php-fpm.sock;
            fastcgi_index  index.php;
            include        fastcgi_params;
            fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
            # Dolibarr Rest API path support
            fastcgi_param  PATH_INFO       $fastcgi_path_info;
            fastcgi_param  PATH_TRANSLATED $document_root$fastcgi_script_name;
        }
     }		
}

提供的服務清單

只有少數服務可用。從Dolibarr 5.0版開始，您可以通過以下地址調用explorer來查看提供的web服務的完整列表：

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

例如，您可以在以下地址的演示實例上嘗試使用explorer：

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

在右上角，粘貼要用於調用API的用戶的＜token＞，然後單擊「explorer」按鈕。注意：每個用戶的令牌可以在用戶的註冊頁面上設置。

您可能還希望首先調用「login」服務以獲取API令牌。作為響應，您將獲得用於獲取和調用所提供服務列表的令牌。

輸入令牌並單擊「Explore」後，您應該看到該令牌的所有可用操作。如果您沒有很多操作，可能是因為相應的模塊未啟用。如果要查看發票，必須在Dolibarr配置中啟用發票模塊。產品、合作方等也是如此。

然後，您可以直接從該瀏覽頁面測試任何API。這是測試任何Dolibarr API的推薦解決方案，因為這裡記錄了所有API和參數。測試之後，您將獲得結果，以及如何使用 curl 從命令行調用API的示例。

在這個API瀏覽頁面上，您可以進行大量測試。例如從Dolibarr讀取數據，並寫入、修改和刪除。警告：數據庫中的數據會被真正修改。

使用方法

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".

Dolibarr user for api.png


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

Vidéos sur le sujet

Retrieved from "https://wiki.dolibarr.org/index.php?title=提供REST_API的Web服务模块（开发者）&oldid=58271"