Dolibarr ERP CRM Wiki

Changes

Module Web Services API REST (développeur) (view source)

Revision as of 03:16, 9 October 2023

1,439 bytes added ,  1 year ago
m
Updating interlang links (links to translated versions of this page in other languages) triggered by origin English page "Module_Web_Services_API_REST_(developer)" update.
Line 1: Line 1: −
{{TemplateDocDevEn}}
+
<!-- BEGIN interlang links -->
−
{{TemplateModEN}}
+
<!-- Do NOT edit this section
−
[[Category:List of Modules]]
+
    Links below are automatically managed by PolyglotBot
−
{{BasculeDevUserEn|
+
    You can edit links on the English source page : Module_Web_Services_API_REST_(developer) -->
−
name=Web services|
+
[[en:Module_Web_Services_API_REST_(developer)]]
 +
[[ja:Module_Web_Services_API_REST_(developer)_JA]]
 +
[[zh:提供REST_API的Web服务模块（开发者）]]
 +
<!-- END interlang links -->
 +
 
 +
{{TemplateDocDevFr}}
 +
{{TemplateModFR}}
 +
[[Category:Liste des Modules (développeur)]]
 +
{{BasculeDevUser|
 +
nom=Web services|
 
num=2610|
 
num=2610|
 
devdoc=Cette page|
 
devdoc=Cette page|
Line 18: Line 27:  
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.
 
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 =
+
= Installation =
−
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'''
+
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 =
 
= Liste des services fournis =
Line 26: Line 38:     
'''http://yourdolibarrurl/api/index.php/explorer'''.
 
'''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 :  
 
Par exemple, vous pouvez essayer l'explorateur sur l'instance de démonstration à l'adresse suivante :  
Line 34: Line 43:  
'''https://demo.dolibarr.org/api/index.php/explorer'''
 
'''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.
+
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.
   −
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.
+
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.
   −
Pour une documentation à propos des annotations : https://github.com/Luracast/Restler/blob/master/ANNOTATIONS.md
+
= Utilisation =
   −
= Installation =
+
Grosso modo, pour utiliser REST, il faut appeler une url du genre suivant <nowiki>http://<mon_serveur>/api/index.php/<action></nowiki><br/>
 +
avec une des 4 méthodes : GET, POST, PUT, DELETE, en remplaçant <action> par l'action sur laquelle vous voulez intervenir. Ex : <nowiki>http://<mon_serveur>/api/index.php/invoices</nowiki>
   −
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 : <nowiki>http://<mon serveur>/api/index.php/login?login=<mon login utilisateur>&password=yourpassword</nowiki><br/>
+
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".
−
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 !!!
+
[[File:Dolibarr user for api.png|400px]]
   −
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.<br/>
  −
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 =
+
Vous devrez utiliser cette clé API dans n'importe lequel de vos programmes clients devant appeler une API Dolibarr.
   −
Grosso modo, pour utiliser REST, il faut appeler une url du genre suivant <nowiki>http://<mon_serveur>/api/index.php/<action></nowiki><br/>
  −
avec une des 4 méthodes : GET, POST, PUT, DELETE, en remplaçant <action> par l'action sur laquelle vous voulez intervenir. Ex : <nowiki>http://<mon_serveur>/api/index.php/invoices</nowiki>
     −
Pour ce faire, il existe plusieurs méthodes. Voici un morceau de code mais il existe également des librairies telles que phphttpclient.com/
+
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.
   −
<source lang="php">
+
<syntaxHighlight lang="php">
 
function CallAPI($method, $apikey, $url, $data = false)
 
function CallAPI($method, $apikey, $url, $data = false)
 
{
 
{
Line 107: Line 114:  
     return $result;
 
     return $result;
 
}
 
}
−
</source>
+
</syntaxHighlight>
    
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.
 
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.
Line 113: Line 120:  
* $method : string "GET", "POST", "PUT", "DELETE"
 
* $method : string "GET", "POST", "PUT", "DELETE"
 
* $apikey : string "votre <token> généré plus haut"
 
* $apikey : string "votre <token> généré plus haut"
−
* $url : string l'url à appeler. Ex : "<nowiki>http://<mon_serveur>/api/index.php/invoices</nowiki"
+
* $url : string l'url à appeler. Ex : "<nowiki>http://<mon_serveur>/api/index.php/invoices</nowiki>"
−
* $data : string flux au format json. ce champ n'est pas obligatoire.
+
* $data : string flux au format json. Ce champ est requis pour les appels POST ou PUT.
   −
= Exemples =
+
= Exemples avec PHP =
   −
Maintenant, quelques exemples.<br/>
+
Maintenant, quelques exemples opérationnels pour différents cas d'utilisation.<br/>
−
dans tous les cas :
+
 
−
* $apiKey = "mon <token>";
+
Dans tous les cas, on a :
 +
* $apiKey = "<mon token>";
 
* $apiUrl = "<nowiki>http://<mon_serveur>/api/index.php/</nowiki>";
 
* $apiUrl = "<nowiki>http://<mon_serveur>/api/index.php/</nowiki>";
      −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// Récupérer la liste des produits
 
// Récupérer la liste des produits
 
$listProduits = [];
 
$listProduits = [];
Line 137: Line 145:  
}
 
}
 
}
 
}
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* récupérer les 10'000 premiers produits triés par leur id dans la base
 
* récupérer les 10'000 premiers produits triés par leur id dans la base
Line 144: Line 152:       −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// Créer un produit
 
// Créer un produit
 
$ref = "ma_reference_produit_X203ZZ";
 
$ref = "ma_reference_produit_X203ZZ";
Line 153: Line 161:  
$newProductResult = CallAPI("POST", $apiKey, $apiUrl."products", json_encode($newProduct));
 
$newProductResult = CallAPI("POST", $apiKey, $apiUrl."products", json_encode($newProduct));
 
$newProductResult = json_decode($newProductResult, true);
 
$newProductResult = json_decode($newProductResult, true);
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* avant de créer un produit, il peut être sage de vérifier qu'il existe. En reprenant le premier exemple, cela fait :
 
* avant de créer un produit, il peut être sage de vérifier qu'il existe. En reprenant le premier exemple, cela fait :
      −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// ma référence
 
// ma référence
 
$ref = "ma_reference_produit_X203ZZ";
 
$ref = "ma_reference_produit_X203ZZ";
Line 185: Line 193:  
}
 
}
 
}
 
}
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* je regarde si la référence de mon article existe dans le tableau créé dans le premier exemple.
 
* je regarde si la référence de mon article existe dans le tableau créé dans le premier exemple.
Line 193: Line 201:       −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// créer une commande avec 2 articles
 
// créer une commande avec 2 articles
   Line 237: Line 245:  
$newCommandeResult = json_decode($newCommandeResult, true);
 
$newCommandeResult = json_decode($newCommandeResult, true);
 
}
 
}
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* $clientDoliId vaut l'id du client dans la base doli. Soit vous le connaissez, soit vous pouvez le chercher auparavant
 
* $clientDoliId vaut l'id du client dans la base doli. Soit vous le connaissez, soit vous pouvez le chercher auparavant
Line 243: Line 251:       −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// Valider une commande  
 
// Valider une commande  
 
$newCommandeValider = [
 
$newCommandeValider = [
Line 251: Line 259:  
$newCommandeValiderResult = CallAPI("POST", $apiKey, $apiUrl."orders/".$newCommandeResult."/validate", json_encode($newCommandeValider));
 
$newCommandeValiderResult = CallAPI("POST", $apiKey, $apiUrl."orders/".$newCommandeResult."/validate", json_encode($newCommandeValider));
 
$newCommandeValiderResult = json_decode($newCommandeValiderResult, true);
 
$newCommandeValiderResult = json_decode($newCommandeValiderResult, true);
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* on voit dans cet exemple, en avant dernière lignes, on a : $apiUrl."orders/".$newCommandeResult."/validate".<br/>
 
* on voit dans cet exemple, en avant dernière lignes, on a : $apiUrl."orders/".$newCommandeResult."/validate".<br/>
Line 257: Line 265:       −
<source lang="php">
+
<syntaxHighlight lang="php">
 
// chercher si le client existe dans la base
 
// chercher si le client existe dans la base
 
$clientSearch = json_decode(CallAPI("GET", $apiKey, $apiUrl."thirdparties", array(
 
$clientSearch = json_decode(CallAPI("GET", $apiKey, $apiUrl."thirdparties", array(
Line 267: Line 275:  
)
 
)
 
), true);
 
), true);
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* limit => 1 pour ne renvoyer que 1 client
 
* limit => 1 pour ne renvoyer que 1 client
Line 274: Line 282:       −
<source lang="php">
+
<syntaxHighlight lang="php">
 
//client n'existe pas. le crée puis on récupère son id
 
//client n'existe pas. le crée puis on récupère son id
 
$newClient = [
 
$newClient = [
Line 285: Line 293:  
$newClientResult = json_decode($newClientResult, true);
 
$newClientResult = json_decode($newClientResult, true);
 
$clientDoliId = $newClientResult;
 
$clientDoliId = $newClientResult;
−
</source>
+
</syntaxHighlight>
 
Commentaires :
 
Commentaires :
 
* client => 1 car c'est un client (et pas un fournisseur)
 
* client => 1 car c'est un client (et pas un fournisseur)
Line 291: Line 299:  
* on récupère l'id du client dans $clientDoliId
 
* on récupère l'id du client dans $clientDoliId
   −
= Conclusion =
+
= 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'''
   −
Vous trouverez pas mal d'autres informations dans le code de Dolibarr, en regardant dans htdocs/<dossier>/class/api_xxx_class.php<br/>
+
= Vidéos sur le sujet =
−
Ex : htdocs/societe/class/api_thirdparties.class.php pour les tiers.<br/>
+
<youtube width="200" height="180">WHV22L8enWw</youtube>  
−
les factures se trouvent dans htdocs/compta/facture/class<br/>
+
<youtube width="200" height="180">RPUcoweeuR8</youtube>
 +
<youtube width="200" height="180">ZwssM-viocM</youtube>
PolyglotBot
1,977

edits

Retrieved from "https://wiki.dolibarr.org/index.php?title=Special:MobileDiff/37350...58265"