Module Web Services API REST (developer): Difference between revisions

Jump to navigation Jump to search

Module Web Services API REST (developer) (view source)

Revision as of 15:41, 6 September 2026

2,116 bytes added ,  1 month ago
m
→‎List of provided services
VisualWikitext
mNo edit summary
Tag: 2017 source edit
Tag: 2017 source edit
 
(18 intermediate revisions by 4 users not shown)
Line 3: Line 3:
     Links below will be automatically replicated on translated pages by PolyglotBot -->
     Links below will be automatically replicated on translated pages by PolyglotBot -->
[[fr:Module_Web_Services_API_REST_(développeur)]]
[[fr:Module_Web_Services_API_REST_(développeur)]]
[[ja:Module_Web_Services_API_REST_(developer)_JA]]
[[zh:提供REST_API的Web服务模块（开发者）]]
<!-- END interlang links -->
<!-- END interlang links -->


Line 13: Line 15:
devdoc=This page|
devdoc=This page|
userdoc=Not applicable|}}
userdoc=Not applicable|}}


=Function=
=Function=
Line 102: Line 97:


'''http://yourdolibarrurl/api/index.php/explorer'''.
'''http://yourdolibarrurl/api/index.php/explorer'''.
For example, you can try the explorer on the demo instance at:
'''https://preview.dolibarr.org/api/index.php/explorer'''
The swagger file to describe all available API services can be found at:
'''https://preview.dolibarr.org/api/index.php/explorer/swagger.json?DOLAPIKEY=demokey'''




Line 112: Line 115:
On this exploration page of the API, you can do quite a lot of tests. Reading datas from Dolibarr and writing, modifying and deleting as well. Warning: Data are really modified in your database.
On this exploration page of the API, you can do quite a lot of tests. Reading datas from Dolibarr and writing, modifying and deleting as well. Warning: Data are really modified in your database.


For example, you can try the explorer on the demo instance at:
You can then test directly from the explorer tool any API. This is the recommended solution to test any Dolibarr API since any API and parameters is documented here. As a result of any test, you will get the answer but also example on how to call the API from command line using '''curl'''.
 
'''https://demo.dolibarr.org/api/index.php/explorer'''
 
You can then test directly from this explorer any API. This is the recommended solution to test any Dolibarr API since any API and parameters is documented here. As a result of any test, you will get the answer but also example on how to call the API from command line using '''curl'''.


=Use=
=Use=
Line 123: Line 122:
with one of the 4 following methods : GET, POST, PUT, DELETE, replacing <action> by the action you want to use. Ex : <nowiki>http://<my_server>/api/index.php/invoices</nowiki>
with one of the 4 following methods : GET, POST, PUT, DELETE, replacing <action> by the action you want to use. Ex : <nowiki>http://<my_server>/api/index.php/invoices</nowiki>


Before using any API, you must first get a custom API-key. You have to create a new user and generate or set its "Key for API".
[[File:Dolibarr user for api.png|400px]]
You will have to use this API key in any of your client program that need to call a Dolibarr API. The API key must be provided as a HTTP header "DOLAPIKEY: apikey".
If you are using the multicompany module, you can also force the API to be executed as if you were logged into a given entity by adding the HTTP header "DOLAPIENTITY: idOfEntity"
==Client code example==
===PHP===
There's different ways to do so. Here's a piece of code but you can also use libraries such as phphttpclient.com
There's different ways to do so. Here's a piece of code but you can also use libraries such as phphttpclient.com


<syntaxhighlight lang="PHP">
<syntaxhighlight lang="PHP">
Line 171: Line 182:
     return $result;
     return $result;
}</syntaxhighlight>
}</syntaxhighlight>


This is just a working example. There's no error control and security was not in mind but you can use this code, modify it to suit your needs<br />
This is just a working example. There's no error control and security was not in mind but you can use this code, modify it to suit your needs<br />
Line 180: Line 190:
*$url : string, url to call. Ex : "<nowiki>http://<my_server>/api/index.php/invoices</nowiki>"
*$url : string, url to call. Ex : "<nowiki>http://<my_server>/api/index.php/invoices</nowiki>"
*$data : string, datas in json format. This parameter is not mandatory.
*$data : string, datas in json format. This parameter is not mandatory.
===Javascript Ajax===
<syntaxhighlight lang="javascript">
<script>
$.ajax({
  type: 'GET',
  async: true,
  contentType: "application/json; charset=utf-8",
  data: { 'lang': 'en_US' },
  dataType: "json",
  cache: false,
  jsonp: false,
  headers: {
    'DOLAPIKEY': 'abcdef123456'
  },
  url: 'https://myserver/api/index.php/theapi',
  success: function(rep) {
    console.log("API call success");
    console.log(rep);
  },
  error: function(rep) {
    console.log("API call error");
    console.log(rep);
  }
});
</script>
</syntaxhighlight>


==Accepted parameters==
==Accepted parameters==
Line 190: Line 228:
*(t.fk_product_type: = :'0') and (t.tosell: = :'1') and (t.label: ilike :'%string')
*(t.fk_product_type: = :'0') and (t.tosell: = :'1') and (t.label: ilike :'%string')


==Date==
===Date===
The ISO date format is accepted: %Y-%m-%d e.g. 2020-07-14. yymmdd is not accepted.
The ISO date format is accepted: %Y-%m-%d e.g. 2020-07-14. yymmdd is not accepted.


Line 369: Line 407:
"email" => "customer company email",
"email" => "customer company email",
"client" => "1",
"client" => "1",
"code_client" => "-1"
"code_client" => "auto"
];
];
$newClientResult = CallAPI("POST", $apiKey, $apiUrl."thirdparties", json_encode($newClient));
$newClientResult = CallAPI("POST", $apiKey, $apiUrl."thirdparties", json_encode($newClient));
Line 375: Line 413:
$clientDoliId = $newClientResult;
$clientDoliId = $newClientResult;
</syntaxhighlight>
</syntaxhighlight>
Comments :


*client => 1 He is a customer (not a supplier)
Comments:
*code_client => -1 so the customer code will be generated automatically.
*client => 1, he is a customer.
*code_client => 'auto' so the customer code will be generated automatically.
*we get the customer ID in $clientDoliId
*we get the customer ID in $clientDoliId


=Examples with Python=
=Examples with Python=
See https://pypi.org/project/dolipy/ and https://pypi.org/project/dolibarr/
See https://pypi.org/project/dolipy/ (2021) or https://pypi.org/project/dolibarr/ (2019) or https://pypi.org/project/dolibarrpy/ (2024)
 
First you can install the python-module with "pip install dolibarr" or pypi install dolibarrpy
 
<syntaxhighlight lang="python">
from dolibarr import Dolibarr
 
api_url = '<nowiki>http://your-url/dolibarr/htdocs/api/index.php/'</nowiki>
api_key = 'custom_API-Key'
 
# Connection to dolibarr
dolibarr_inst = Dolibarr(api_url, api_key)
 
# create Product
params = {'ref': 'Product_Reference', 'status': '1', 'barcode_type': '6', 'note_public': None,         
 
          'note_private': <nowiki>''</nowiki>, 'specimen': 0, 'label': 'Product_Label',
 
          'description': <nowiki>''</nowiki>, 'type': '0', 'price': <nowiki>''</nowiki>, 'price_ttc': '15.6000000', 'price_base_type': 'TTC',  # excl. tax = HT, incl. tax = TTC
 
          'tva_tx': '19.0000', 'seuil_stock_alerte': '0', 'desiredstock': '0', 'status_buy': '1', 'barcode': 'barcode'}
 
ret_val = dolibarr_inst.call_create_api('products', params)
print(ret_val)
 
# get product list
product_dict = dolibarr_inst.call_list_api('products')
print(product_dict)
</syntaxhighlight>


=Develop your own service / API=
=Develop your own service / API=
Adding a new REST service is as easy than adding a file called '''api_mymoduleobject.class.php''' into the directory '''htdocs/mymodule/class'''.
Adding a new REST service is as easy than adding a file called '''api_mymoduleobject.class.php''' into the directory '''htdocs/mymodule/class'''.
You take the example into '''htdocs/commande/class/api_orders.class.php'''
You can take an example into '''htdocs/commande/class/api_orders.class.php'''


Note that if you use the '''modulebuilder''' tool, the file may be generated for you.
Note that if you use the '''modulebuilder''' tool, this file may be generated for you.


The framework detects automatically the API and it should be visible into the explorer.
The framework detects automatically the API files and it should be visible into the explorer.


Method and parameters are detected according to introspection done into PHP class of the object ('''htdocs/mymodule/class/object.class.php''') using the '''annotations''' found into the class.
Method and parameters are detected according to introspection done into PHP class of the object ('''htdocs/mymodule/class/object.class.php''') using the '''annotations''' found into the class.
Line 397: Line 463:
These are just the basics.
These are just the basics.


Some more informations in the Dolibarr code. You can look here : htdocs/<directory>/class/api_xxx_class.php<br />
To find all existing API files in Dolibarr, you can search all files htdocs/<directory>/class/api_xxx_class.php
Ex : htdocs/societe/class/api_thirdparties.class.php for thirdparties.<br />
Ex : htdocs/societe/class/api_contacts.class.php for contacts.<br />
Ex : htdocs/compta/facture/class/api_invoice_class.php for invoices.<br />
Ex : htdocs/mrp/class/api_mos_class.php for manufacturing orders.<br />
Ex : htdocs/product/class/api_products.class.php for contacts.<br />
Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/52477...67206"

Navigation menu