Message-ID: <250911024.375734.1710811241741.JavaMail.root@confluence-doc2-production> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_375733_1918769055.1710811241737" ------=_Part_375733_1918769055.1710811241737 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Table of contents
This chapter aims at grouping all the information from the webservice tutorial into = a handy one-page doc that you can print and keep at hand.
In order for you to view, edit and delete the data on your PrestaShop st= ore through its webservice, you first need to enable the webservice feature= , and then create an access key.
Configure your PHP installation so that it has the cURL extension instal= led and enabled:
With Windows, place this line in your php.ini
file:
extensio= n=3Dphp_curl.dll=20
With Linux/Mac, install the cURL extension:
sudo apt= -get install php5-curl=20
Go in the PrestaShop back-office, open the "Webservice" page under the "= Advanced Parameters" menu, and then choose "Yes" for the "Enable PrestaShop= 's webservice". Save your change: you're done!
Open the "Webservice" page under the "Advanced Parameters" menu, and the= n click the "Add New" button to access the account configuration section. A= long form appears:
If you choose to use a custom passkey instead of a generated one, make s= ure it is very secure and that its rights are limited =E2=80=93 and that it= is 32characters long!
The endpoint to your store's webservice is located in the /api/ folder at the root of your installation of Prestashop:
To access it, you need to provide your API key when request. There is no= password, providing your API key is enough =E2=80=93 and therefore the key= should be kept secret by the user!
You can either type the API endpoint address directly then enter your AP= I key, or indicate your API key in the address. Here is an example, with "U= CCLLQ9N2ARSHWCXLT74KUKSSK34BFKX" being the API key.
You can test this with any browser that supports XML.
If no permission has been set for the key, then the browser will keep as= king you to enter the key indefinitely.
If you cannot access some resources, the API might answer with this XML = response:
<?xml= version=3D"1.0" encoding=3D"UTF-8"?> <prestashop xmlns:xlink=3D"http://www.w3.org/1999/xlink"> <errors> <error> <message><![CDATA[Internal error. To see this error please d= isplay the PHP errors.]]></message> </error> </errors> </prestashop>=20
Using XLink, you will then be able to access your various resources. XLi= nk associates an XML file to another XML file via a link.
You will need the latest version of the PSWebServiceLibrary.php file, which can be found on our code repository: https://github.com/PrestaS=
hop/PrestaShop-webservice-lib/blob/master/PSWebServiceLibrary.php
T=
o download the file:
PSWebServiceLibrary.php
.You can also directly download a zip archive of all the files in this re= pository, including the example files, by clicking here: https://github.com/PrestaShop/PrestaShop= -webservice-lib/archive/master.zip
Put PSWebServiceLibrary.php
at the root of your web server,=
and add this line at the beginning of any PHP file that needs to use your =
store's webservice.
Then, you must create an instance of the PrestaShopWebservice object, which takes 3 parameters in its constructor:
Here's how you create a webservice call:
$webServ= ice =3D new PrestaShopWebservice('http://example.com/', 'UCCLLQ9N2ARSHWCXLT= 74KUKSSK34BFKX', false);=20
It is essential that you understand how to handle errors with the webser= vice library. By implementing error-catch method early, you will more easil= y detect issues, and be able to correct them on the go.
Error handling with the webservice library is done using PHP exceptions.= If you do not know about them, you should read = http://php.net/manual/en/language.exceptions.php, as exceptions are an = essential part of good coding practice.
The error handling is done within a try..catch
block, with =
the webservice processing being done in the try section, the catch one cont=
aining the error handling code.
try { // Execution ( if an error occurs in this code, stops and goes in the cat= ch block) } catch { // Error handling (tries to catch the error or the error display) }=20
That means each creation or use of the library must be located within a =
"try" block. The "catch" block can then handle the error if it occurs durin=
g the execution of the try block.
Now we'll see how to list all custome=
rs via the webservice, and then we will see the four CRUD methods.
In the following code sample, we want to get the list of all customers:<= /p>
PrestaShopWebservice
=
object with the necessary parameters and retrieve the customer resource XML=
in a variable.try { // creating webservice access $webService =3D new PrestaShopWebservice('http://example.com/', 'UCCLLQ9= N2ARSHWCXLT74KUKSSK34BFKX', false); =20 // call to retrieve all clients $xml =3D $webService->get(array('resource' =3D> 'customers')); } catch (PrestaShopWebserviceException $ex) { // Shows a message related to the error echo 'Other error: <br />' . $ex->getMessage(); }=20
All the example files can be found on our code repository: https://github.com/PrestaShop/Pre= staShop-webservice-lib/tree/master/examples
As shown above, you have to instantiate the PrestaShopWebservice=
code> object in order to use its methods:
add()
, get()=
code>,
edit()
and delete()
.
You can also dire=
ctly use call the REST API and get XML results, as this correspondence table =
shows:
CRUD operations |
SQL statements |
PrestaShopWebservice methods |
HTTP methods |
---|---|---|---|
Create |
INSERT |
add() |
POST |
Read |
SELECT |
get() |
GET |
Update |
UPDATE |
edit() |
PUT |
Delete |
DELETE |
delete() |
DELETE |
Let's see how to view a full list of client IDs. As you can see from the=
table above, we need the get()
method in order to retrieve a =
XML file containing all the customers. The parameter has to be a key-value =
array, where we define the resource we want:
Key |
Value |
---|---|
resource |
customers |
The value defines the resource that the webservice will use in a future = call. The value could be carrier types, countries or any other type of reso= urce that can be found in the "Available resources" section of this guide.<= /p>
In order to retrieve a list of customers in XML format, you only need to=
instantiate PrestaShopWebservice
(a seen earlier) and use thi=
s code:
// The k= ey-value array $opt['resource'] =3D 'customers'; =20 Retrieving the XML data $xml =3D $webService->get($opt);=20
Launching the code above will return a XML object containing all the cur= rent customer IDs on the store:
<?xml= > <prestashop> <customer id=3D"1" xlink:href=3D"http://example.com/api/customers/1"/&= gt; <customer id=3D"2" xlink:href=3D"http://example.com/api/customers/2"/&= gt; <customer id=3D"3" xlink:href=3D"http://example.com/api/customers/3"/&= gt; <customer id=3D"4" xlink:href=3D"http://example.com/api/customers/4"/&= gt; </prestashop>=20
With this information, you can access the customer that interests you by=
using the value in the id
attribute:
$opt['re= source'] =3D 'customers'; $opt['id'] =3D 1; $xml =3D $webService->get($opt);=20
As you can see in the result in the previous section, the data returned =
by calling $webService->get()
puts you at the root of the X=
ML document, in the context you requested.
To access the fields of clients who are children of the <custom=
ers>
tag, we only need to retrieve all fields in an associative a=
rray in XML, like this:
$resourc= es =3D $xml->customers->children();=20
From there, you can easily access client IDs. Here's an example with a p= ath from identifiers:
foreach = ($resources as $resource) echo $resource->attributes() . '<br />';=20
Thanks to these elements, you can create a HTML table containing all the= client IDs =E2=80=93 or anything that displays this information in your in= terface.
If you would rather not use the PrestaShopWebservice
object=
, note that PrestaShop's webservice is RESTful, in that you can work with i=
ts data using the known HTTP verbs just as easily as you would use the meth=
ods of the PrestaShopWebservice
object.
Viewing your data follows the same rule, but with a HTTP GET request on =
the same URL:
To view your data you simply have to launch an HTTP GET r=
equest on the following URL:
http://U= CCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/customers/=20
The resulting XML document is the same as the one obtained using P=
restaShopWebservice
's get()
method.
Creating and adding data takes a bit more work. Indeed, in order to crea=
te a new entry or edit an existing one, you need to send a fully formed and=
complete XML document, whether you use PrestaShopWebservice
o=
r the HTTP methods.
When you need to create a new entry, the API can help you by providing a= blank schema for any resource, or even a synopsis with indications of the = meaning for each tag:
// Retur= ns a blank XML document, with all the tags ready to fill http://UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/manufacturers?schem= a=3Dblank // Returns a blank XML document, with all the tags ready to fill and indica= tion of the expected value for each http://UCCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/manufacturers?schem= a=3Dsynopsis=20
When a client is created from within PrestaShop's administration interfa= ce, a confirmation e-mail is sent to the client. This cannot be done direct= ly with the webservice: there is no way to trigger the sending of that conf= irmation e-mail.
However, you can create an override file for the Customer
c=
lass and override the addWs()
method. This method is similar t=
o ObjectModel::add()
but is only called from the webservice. Y=
ou can find examples of its use in the Product
and Order=
classes.
The RESTful-ness of the API goes all the way: in order to delete the pro= duct with an ID of 12, you simply have to launch an HTTP DELETE request on = the following URL:
http://U= CCLLQ9N2ARSHWCXLT74KUKSSK34BFKX@example.com/api/products/12/=20
The /api/
URL gives you the root of all the resources, in t=
he form of an XML file.
Here it is, extremely simplified. This list is current as of version 1.5= .4.1 of PrestaShop. Note that we only show the API resources available for = one of the available stores.
<?xml= version=3D"1.0" encoding=3D"UTF-8"?> <prestashop xmlns:xlink=3D"http://www.w3.org/1999/xlink"> <api shop_name=3D"MYSHOP"> <addresses>...</addresses> <carriers>...</carriers> <cart_rules>...</cart_rules> <carts>...</carts> <categories>...</categories> <combinations>...</combinations> <configurations>...</configurations> <contacts>...</contacts> <content_management_system>...</content_management_system> <countries>...</countries> <currencies>...</currencies> <customer_messages>...</customer_messages> <customer_threads>...</customer_threads> <customers>...</customers> <deliveries>...</deliveries> <employees>...</employees> <groups>...</groups> <guests>...</guests> <image_types>...</image_types> <images>...</images> <languages>...</languages> <manufacturers>...</manufacturers> <order_carriers>...</order_carriers> <order_details>...</order_details> <order_discounts>...</order_discounts> <order_histories>...</order_histories> <order_invoices>...</order_invoices> <order_payments>...</order_payments> <order_states>...</order_states> <orders>...</orders> <price_ranges>...</price_ranges> <product_feature_values>...</product_feature_values> <product_features>...</product_features> <product_option_values>...</product_option_values> <product_options>...</product_options> <product_suppliers>...</product_suppliers> <products>...</products> <search >...</search> <shop_groups>...</shop_groups> <shops>...</shops> <specific_price_rules>...</specific_price_rules> <specific_prices>...</specific_prices> <states>...</states> <stock_availables>...</stock_availables> <stock_movement_reasons>...</stock_movement_reasons> <stock_movements>...</stock_movements> <stocks>...</stocks> <stores>...</stores> <suppliers>...</suppliers> <supply_order_details>...</supply_order_details> <supply_order_histories>...</supply_order_histories> <supply_order_receipt_histories>...</supply_order_receipt_hist= ories> <supply_order_states>...</supply_order_states> <supply_orders>...</supply_orders> <tags>...</tags> <tax_rule_groups>...</tax_rule_groups> <tax_rules>...</tax_rules> <taxes>...</taxes> <translated_configurations>...</translated_configurations> <warehouse_product_locations>...</warehouse_product_locations&= gt; <warehouses>...</warehouses> <weight_ranges>...</weight_ranges> <zones>...</zones> </api> <api shop_name=3D"MYOTHERSHOP">...</api> <api shop_name=3D"YETANOTHERSHOP">...</api> </prestashop>=20
As with any XLink-bearing XML file, each resource element leads to more =
resources, linked from the xlink
attribute.
<cust= omers xlink:href=3D"http://example.com/api/customers" get=3D"true" put=3D"t= rue" post=3D"true" delete=3D"true" head=3D"true"> <description xlink:href=3D"http://example.com/api/customers" get=3D"tr= ue" put=3D"true" post=3D"true" delete=3D"true" head=3D"true">The e-shop'= s customers</description> <schema xlink:href=3D"http://example.com/api/customers?schema=3Dblank"= type=3D"blank"/> <schema xlink:href=3D"http://example.com/api/customers?schema=3Dsynops= is" type=3D"synopsis"/> </customers>=20
In addition, the element contains a description of the resource, and two= schemas: a blank one, which you can use to create a new item, and a synops= is one, which is just like the blank one but with a detailed description of= what type of data is expected in each element.
Here is an extract of the Customer blank schema:
<?xml= version=3D"1.0" encoding=3D"UTF-8"?> <prestashop xmlns:xlink=3D"http://www.w3.org/1999/xlink"> <customer> <id></id> <id_default_group></id_default_group> <id_lang></id_lang> <newsletter_date_add></newsletter_date_add> <ip_registration_newsletter></ip_registration_newsletter> <last_passwd_gen></last_passwd_gen> <secure_key></secure_key> <deleted></deleted> <passwd></passwd> <lastname></lastname> <firstname></firstname> <email></email> ... </customer> </prestashop>=20
Here is an extract of the Customer synopsis schema:
<?xml= version=3D"1.0" encoding=3D"UTF-8"?> <prestashop xmlns:xlink=3D"http://www.w3.org/1999/xlink"> <customer> <id_default_group></id_default_group> <id_lang format=3D"isUnsignedId"></id_lang> <newsletter_date_add></newsletter_date_add> <ip_registration_newsletter></ip_registration_newsletter> <last_passwd_gen></last_passwd_gen> <secure_key format=3D"isMd5"></secure_key> <deleted format=3D"isBool"></deleted> <passwd required=3D"true" maxSize=3D"32" format=3D"isPasswd"><= /passwd> <lastname required=3D"true" maxSize=3D"32" format=3D"isName"><= /lastname> <firstname required=3D"true" maxSize=3D"32" format=3D"isName"><= ;/firstname> <email required=3D"true" maxSize=3D"128" format=3D"isEmail"></= email> ... </customer> </prestashop>=20
The value types can be found in the webservice reference: http://doc.prestashop.com/display/PS15/Web+s= ervice+reference.