JoomShopping API Documentation

Summary
Version 1.0.3
Date 01.11.2018
Author MAXXmarketing GmbH
Author's email marketing@maxx-marketing.net
Author's website https://www.webdesigner-profi.de
License GNU/GPL
Copyright Copyright (C) 2010 webdesigner-profi.de. All rights reserved
Introduction

The JoomShopping API is the RESTful system that allows to use JoomShopping capabilities. Before using the API need to get authorization data (email, password) of an API user from the administrator of a site, where the API is installed. All code snippets are on PHP.

Technical requirements
PHP 7.0+
MySQL 5.5.3+
or SQL Server 10.50.1600.1+
or PostgreSQL 9.1+
Joomla! 3.8.0+
JoomShopping 4.16.3+
Version history
  • 1.0.3
    |
    01.11.2018
    1. Fixed HTTP authorization errors reporting
    2. Added Example documentation subsection
  • 1.0.2
    |
    30.10.2018
    1. Standardized the basic features
  • 1.0.1
    |
    18.10.2018
    1. Integrated the support of addons
    2. Added content section
  • 1.0.0
    |
    22.02.2018
    1. Integrated the support of PHP version 7.1
    2. Integrated the support of PHP version 7.2
    3. Renamed fromWishlistToCart task to toCart in wishlist section
  • 0.2.6
    |
    08.12.2017
    1. Added update task in cart section
    2. Added update task in wishlist section
    3. Added group task in product section
    4. Added search task in product section
    5. Added searchInfo task in product section
    6. Separated cart and wishlist reports and tasks
    7. Changed parameters of item task in category section
  • 0.2.5
    |
    01.12.2017
    1. Deleted user return parameter of createInfo task of user section
    2. Deleted user_id parameter of changePassword task of user section
    3. Added edit task in user section
    4. Added editInfo task in user section
    5. Added groups task in user section
    6. Added order task in user section
    7. Added orders task in user section
    8. Added ordersAll task in user section
Request

Requests to the API are performing through POST request method with help of cURL or another same software. Here is a structure of a request:

$curl = curl_init('%site_url%/index.php?option=com_jshopping&controller=addon_api'); curl_setopt($curl, CURLOPT_HTTPHEADER, [ '%authorization_header%' ]); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([ '%arg1_name%' => '%arg1_value%', '%arg2_name%' => '%arg2_value%', '%arg3_name%' => '%arg3_value%', ... ])); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $res = curl_exec($curl); curl_close($curl); if ($res !== false) { $res = json_decode($res, true); } exit(var_dump($res));

Where %site_url% is the base URL of a website where the API is installed, https://www.example.com for example.

%authorization_header% is the authorization data, sent in headers.

%argN_name% and %argN_value% are keys and values of the request parameters array, wrapped with http_build_query function, because they are must be sent as array only.

The API returns the result in a format, specified in a request, by default it is json.

Authorization data

The authorization data is sent in headers. It is required for every request. At very first request this header should be like this:

Authorization: Basic %email%:%password%

Where %email%:%password% is base64 encoded line with email and password of an API user, concatenated with a colon.

After this request the token will be returned. In all next requests send it in headers like this:

Authorization: Bearer %token%

The HTTP authorization must be switched on at a server of a website where the API is installed. If not, it can be switched on by adding the next string into .htaccess file at the website

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
Request parameters
Name Type Default value Description
section string The API section
task string The action, what need to do
format string json The format of reply
args array Arguments, needed for specified action
Connection

To connect to the API send open task to connection section like this:

$curl = curl_init('%site_url%/index.php?option=com_jshopping&controller=addon_api'); curl_setopt($curl, CURLOPT_HTTPHEADER, [ '%authorization_header%' ]); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([ 'section' => 'connection', 'task' => 'open' ])); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $res = curl_exec($curl); curl_close($curl); if ($res !== false) { $res = json_decode($res, true); } $token = $res['result'];

After this request the token will be returned as a result. Use it for all next requests.

Authorization: Bearer %token%

Note that the token has the time limit, 60 minutes by default. The token's timestamp is updated after every new request, but if there are no activity during this time, the token will expire. In this case need to get a new token again to continue to use the API. The time limit can be changed by the site administrator.

Disconnection

Always close the connection after finish of work with the API. Call close task of connection section to do this.

Example
Initializing access data: $site_url = 'https://example.com'; $email = 'example@email.com'; $password = 'example_password'; Opening a connection and getting the token: $curl = curl_init($site_url . '/index.php?option=com_jshopping&controller=addon_api'); curl_setopt($curl, CURLOPT_HTTPHEADER, [ 'Authorization: Basic ' . base64_encode($email . ':' . $password) ]); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([ 'section' => 'connection', 'task' => 'open' ])); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $res = curl_exec($curl); curl_close($curl); if ($res !== false) { $res = json_decode($res, true); } $token = $res['result']; Getting information about the connection: $curl = curl_init($site_url . '/index.php?option=com_jshopping&controller=addon_api'); curl_setopt($curl, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer ' . $token ]); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([ 'section' => 'connection', 'task' => 'info' ])); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); $res = curl_exec($curl); curl_close($curl); if ($res !== false) { $res = json_decode($res, true); } $info = $res['result']; Closing the connection: $curl = curl_init($site_url . '/index.php?option=com_jshopping&controller=addon_api'); curl_setopt($curl, CURLOPT_HTTPHEADER, [ 'Authorization: Bearer ' . $token ]); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([ 'section' => 'connection', 'task' => 'close' ])); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); curl_exec($curl); curl_close($curl);
Sections and tasks
Task
Arguments
Name Type Default value
Result type Details
addon
ids array
Name

ids

Description

Returns aliases of all addons

Return type

array

item
id string
array
Name

item

Description

Returns the information about an addon

Parameters
Name Type Default value Description
id string Addon's alias
Return type

array

items
ids string array
array
Name

items

Description

Returns the information about addons

Parameters
Name Type Default value Description
ids string array Addons' aliases
Return type

array

cart
add
product_id int
quantity int
attributes array
freeattributes array
additional_fields array
bool
Name

add

Description

Adds a product into the cart

Parameters
Name Type Default value Description
product_id int Product's identifier
quantity int Product's quantity
attributes array An array of attributes in format
int attribut_idstring attribut_value
freeattributes array An array of free attributes in format
int free_attribut_idstring free_attribut_value
additional_fields array An array of additional fields in format
string field_keystring field_value
Return type

bool

clear bool
Name

clear

Description

Clears all the data of the cart

Return type

bool

delete
index int
bool
Name

delete

Description

Deletes a product from the cart

Parameters
Name Type Default value Description
index int Product's index number in the cart
Return type

bool

discount
code string
bool
Name

discount

Description

Applies a discount to the cart

Parameters
Name Type Default value Description
code string Discount code
Return type

bool

info array
Name

info

Description

Returns the information about the cart

Return type

array

update
quantities int array
bool
Name

update

Description

Updates products' quantities in the cart

Parameters
Name Type Default value Description
quantities int array An array of new quantities in format
int product_indexint product_quantity
Return type

bool

category
ids array
Name

ids

Description

Returns identifiers of all categories

Return type

array

item
id int
array
Name

item

Description

Returns the information about a category

Parameters
Name Type Default value Description
id int Category identifier. Use search task of product section to get category products
Return type

array

items
ids int array
array
Name

items

Description

Returns the information about categories

Parameters
Name Type Default value Description
ids int array Categories' identifiers
Return type

array

tree array
Name

tree

Description

Returns the categories tree

Return type

array

checkout
step2 array
Name

step2

Description

Returns the information, needed for making step #2. Start from this step to make an order. Then call saving task. Repeat this procedure for all steps until the last. Note that some steps can be disabled, so before making the next step always check its number by returned parameter next_step or using tasks stepNumber or steps

Return type

array

step2save
input array
bool
Name

step2save

Description

Makes step #2

Parameters
Name Type Default value Description
input array User's input in format
string field_keystring field_value
Return type

bool

step3 array
Name

step3

Description

Returns the information, needed for making step #3

Return type

array

step3save
payment_id int
extra_params array []
bool
Name

step3save

Description

Makes step #3

Parameters
Name Type Default value Description
payment_id int Payment's identifier
extra_params array [] Extra parameters
Return type

bool

step4 array
Name

step4

Description

Returns the information, needed for making step #4

Return type

array

step4save
shipping_id int
extra_params array []
bool
Name

step4save

Description

Makes step #4

Parameters
Name Type Default value Description
shipping_id int Shipping's identifier
extra_params array [] Extra parameters
Return type

bool

step5 array
Name

step5

Description

Returns the information, needed for making step #5

Return type

array

step5save
confirmation int
payment_back_link string
extra_params array []
array
Name

step5save

Description

Makes step #5. This task returns filled parameter payment_form if payment is needed and empty otherwise. To make the payment display the contents of this parameter as HTML of version 5 on a needed page of the application. In most cases an application user will be automatically redirected to a web page of a payment system, chosen in step3save task. In some cases ('Pay Pal PLUS' for example) the user need to choose some parameters before the redirect. At that web page the user need to make a payment in a standard way. After the payment or cancellation the user will be redirected back to the application by the link passed in step5save task as payment_back_link parameter. GET parameter act also will be added to the back link. In most cases it will be equals to return if the payment was suuccessful, cancel if the payment was cancelled and error if some error has occurred. Later on, if the payment was successful, the payment system will send the confirmation request to the shop by its own

Parameters
Name Type Default value Description
confirmation int User's confirmation
payment_back_link string URL, where a user will be redirected after the completion or cancellation of the payment
extra_params array [] Extra parameters
Return type

array

stepNumber int
Name

stepNumber

Description

Get the number of the current step

Return type

int

steps array
Name

steps

Description

Returns numbers of all steps

Return type

array

connection
close bool
Name

close

Description

Closes the current connection with the API. Call it always after end of work with the API

Return type

bool

info array
Name

info

Description

Returns the information about the current connection with the API

Return type

array

open string
Name

open

Description

Opens a new connection with the API and returns the token of it

Return type

string

user array
Name

user

Description

Returns the information about the currently connected API user

Return type

array

content
cartReturnPolicy array
Name

cartReturnPolicy

Description

Returns the information about cart's return policy

Return type

array

ids array
Name

ids

Description

Returns aliases of all shop content pages

Return type

array

item
id string
array
Name

item

Description

Returns the information about a shop content page

Parameters
Name Type Default value Description
id string Shop content page alias
Return type

array

items
ids string array
array
Name

items

Description

Returns the information about shop content pages

Parameters
Name Type Default value Description
ids string array Shop content pages' aliases
Return type

array

orderReturnPolicy
order_id int
array
Name

orderReturnPolicy

Description

Returns the information about order's return policy

Parameters
Name Type Default value Description
order_id int Order identifier
Return type

array

order
ids array
Name

ids

Description

Returns identifiers of all orders

Return type

array

item
id int
array
Name

item

Description

Returns the information about an order

Parameters
Name Type Default value Description
id int Order's identifier
Return type

array

items
ids int array
array
Name

items

Description

Returns the information about orders

Parameters
Name Type Default value Description
ids int array Orders' identifiers
Return type

array

states array
Name

states

Description

Returns the information about orders' states

Return type

array

product
group
group string
array
Name

group

Description

Returns the information about products of a specified group

Parameters
Name Type Default value Description
group string Products' group:
bestsellerThe best-selling products
lastThe last-added products
randomA random set of products
tophitsThe most-viewed products
topratingThe most rated products
Return type

array

ids array
Name

ids

Description

Returns identifiers of all products

Return type

array

item
id int
attributes array []
array
Name

item

Description

Returns the information about a product

Parameters
Name Type Default value Description
id int Product's identifier
attributes array [] An array of attributes in format
int attribut_idstring attribut_value
Return type

array

items
ids int array
array
Name

items

Description

Returns the information about products

Parameters
Name Type Default value Description
ids int array Products' identifiers
Return type

array

search
search string ''
search_type string any
categories int array []
include_subcat bool true
manufacturers int array []
vendors int array []
labels int array []
price_from float string 0
price_to float string 0
date_from string ''
date_to string ''
extra_fields array []
order int 1
orderby int 0
limit int 12
limitstart int 0
array
Name

search

Description

Returns the list of found products

Parameters
Name Type Default value Description
search string '' A search query
search_type string any Search by:
allAll parts of the search query
anyAny part of the query
exactExact match with the query

Has a matter only when a search query is not empty

categories int array [] Categories' identifiers
include_subcat bool true Whether to search in subcategories
manufacturers int array [] Manufacturers' identifiers
vendors int array [] Vendors' identifiers
labels int array [] Labels' identifiers
price_from float string 0 Minimum product price
price_to float string 0 Maximum product price
date_from string '' Minimum product creation date in format YYYY-MM-DD HH:MM:SS
date_to string '' Maximum product creation date in format YYYY-MM-DD HH:MM:SS
extra_fields array [] Products' extra fields in format
int extra_field_idstring extra_field_value
or
int extra_field_idint array extra_field_values_ids

The support of extra fields can be switched off by the site administrator

order int 1 Identifier of a property by which to order products. One of keys of sorting_products_field_s_select parameter of the shop configuration. The default value is stored in the shop configuration under product_sorting key and can be changed by the site administrator
orderby int 0 Products order direction:
0Ascending
1Descending

The default value is stored in the shop configuration under product_sorting_direction key and can be changed by the site administrator

limit int 12 Number of products to return. The default value is stored in the shop configuration under count_products_to_page key and can be changed by the site administrator
limitstart int 0 Start position of products. Used for pagination
Return type

array

searchInfo array
Name

searchInfo

Description

Returns the information, needed for the products searching

Return type

array

shop
config array
Name

config

Description

Returns the shop configuration

Return type

array

user
activate
token string
array
Name

activate

Description

Activates a new user account. Returns the information about the just activated user

Parameters
Name Type Default value Description
token string Activation token
Return type

array

cancelOrder
id int
order_id int
bool
Name

cancelOrder

Description

Cancels an order

Parameters
Name Type Default value Description
id int User's identifier
order_id int Order's identifier
Return type

bool

changePassword
id int
old_password string
new_password string
bool
Name

changePassword

Description

Changes the password of a user

Parameters
Name Type Default value Description
id int User's identifier
old_password string User's current password
new_password string User's new password
Return type

bool

create
input array
array
Name

create

Description

Registers a new user. Returns the information about the just registered user

Parameters
Name Type Default value Description
input array Registration data in format
string field_keystring field_value
Return type

array

createInfo array
Name

createInfo

Description

Returns the information, needed for a new user registration

Return type

array

edit
id int
input array
bool
Name

edit

Description

Edits the information about a user

Parameters
Name Type Default value Description
id int User's identifier
input array New user's data in format
string field_keystring field_value
Return type

bool

editInfo array
Name

editInfo

Description

Returns the information for editing of user's data

Return type

array

groups array
Name

groups

Description

Returns the information about user groups

Return type

array

ids array
Name

ids

Description

Returns identifiers of all users

Return type

array

item
id int 0
array
Name

item

Description

Returns the information about a user

Parameters
Name Type Default value Description
id int 0 User's identifier. The current user's identifier will be used if id is 0
Return type

array

items
ids int array
array
Name

items

Description

Returns the information about users

Parameters
Name Type Default value Description
ids int array Users' identifiers
Return type

array

login
username string
password string
bool
Name

login

Description

Logs a user in

Parameters
Name Type Default value Description
username string User's name
password string User's password
Return type

bool

logout bool
Name

logout

Description

Logs the current user out

Return type

bool

order
id int
order_id int
array
Name

order

Description

Returns the information about a user's order

Parameters
Name Type Default value Description
id int User's identifier
order_id int Order's identifier
Return type

array

orders
id int
orders_ids int array
array
Name

orders

Description

Returns the information about user's orders

Parameters
Name Type Default value Description
id int User's identifier
orders_ids int array Orders' identifiers
Return type

array

wishlist
add
product_id int
quantity int
attributes array
freeattributes array
additional_fields array
bool
Name

add

Description

Adds a product into the wishlist

Parameters
Name Type Default value Description
product_id int Product's identifier
quantity int Product's quantity
attributes array An array of attributes in format
int attribut_idstring attribut_value
freeattributes array An array of free attributes in format
int free_attribut_idstring free_attribut_value
additional_fields array An array of additional fields in format
string field_keystring field_value
Return type

bool

clear bool
Name

clear

Description

Clears all the data of the wishlist

Return type

bool

delete
index int
bool
Name

delete

Description

Deletes a product from the wishlist

Parameters
Name Type Default value Description
index int Product's index number in the wishlist
Return type

bool

info array
Name

info

Description

Returns the information about the wishlist

Return type

array

toCart
index int
bool
Name

toCart

Description

Sends a product from the wishlist to the cart

Parameters
Name Type Default value Description
index int Product's index number in the wishlist
Return type

bool

update
quantities int array
bool
Name

update

Description

Updates products' quantities in the wishlist

Parameters
Name Type Default value Description
quantities int array An array of new quantities in format
int product_indexint product_quantity
Return type

bool

Reply

The API returns the array with status, code, report and result of a request. This array is returned in a format, specified in a request, by default it is json. Here is an example of a reply:

array (size=4) 'status' => string 'ok' (length=2) 'code' => int 1 'report' => string 'No errors. Success' (length=18) 'result' => string 'KfAl9WMorrEjKtCPS7M1FHo1szhOlxS4' (length=32)

The status is the title of a reply. Each status has it's own set of codes and reports. Here is the list of possible reports.

The code is for identify a reply programmatically.

The report describes a reply more detailed.

The result is directly the result of a reply.

A reply is successful only when it's status is ok, otherwise — it has an error.

Formats

The API returns the result in a format, specified in a request, by default it is json. Here is the list of available formats:

Name Description
json Reply will be JSON-encoded
var_dump Reply will be shown as result of var_dump PHP function. Useful while testing
Reports
Code Report
addon_error
1 Unknown addon alias
cart_error
1 Wrong quantity
2 Quantity less than minimal
3 Quantity more than maximal
4 Not enough products in stock
5 No required product attribute(s)
6 No required product free attribute(s)
7 Unknown atribute id
8 Unknown atribute value
9 Unknown free atribute id
10 Unknown product index
11 Wrong discount code
category_error
1 Unknown category id
checkout_error
1 The cart is empty
2 Sum less than minimal
3 Sum more than maximal
4 Step(s) missed
5 Step is disabled by the site administrator
6 No payment
7 Payment error
8 No shipping
9 Shipping error
10 No user confirmation
connection_error
1 No authorization header
2 Wrong type of authorization header
3 No email address
4 No password
5 Unknown email address
6 Wrong password
7 Wrong token
8 Expired token
9 You are blocked by the site administrator
content_error
1 Unknown alias
ok
1 Success
2 Notice
3 Warning
order_error
1 Unknown order id
2 Need to pay the order first
3 Failed to cancel the order
4 Order already cancelled
payment_error
1 Unlicensed payment system
2 Failed to create payment form
product_error
1 Unknown product id
2 Unknown product group
request_error
1 Unknown format
2 No section
3 No task
4 Unknown section
5 Unknown task
6 No required argument(s)
7 Wrong argument(s)
8 Access denied
server_error
1 Internal server error
2 Failed to save data to the database
3 Failed to update data in the database
4 Failed to get data from the database
user_error
1 Unknown user id
2 Need to login first
3 Username and password do not match
4 Wrong old password
5 No required field
6 No required field 'title'
7 No required field 'f_name'
8 No required field 'l_name'
9 No required field 'm_name'
10 No required field 'firma_name'
11 No required field 'client_type'
12 No required field 'firma_code'
13 No required field 'tax_number'
14 No required field 'email'
15 No required field 'birthday'
16 No required field 'u_name'
17 Invalid symbols in field 'u_name'
18 Such user name is already in use
19 Password is too long
20 Password must not contain spaces at the beginning or end
21 Password does not contain enough digits
22 Password does not contain enough symbols
23 Password does not contain enough uppercase characters
24 Password is too short
25 No required field 'password'
26 No required field 'password2' or passwords do not match
27 No required field 'email'
28 No required field 'home'
29 No required field 'apartment'
30 No required field 'street' or 'street_nr'
31 No required field 'zip'
32 No required field 'city'
33 No required field 'state'
34 No required field 'country' or unknown country identifier
35 No required field 'phone'
36 No required field 'mobil_phone'
37 No required field 'fax'
38 No required field 'ext_field_1'
39 No required field 'ext_field_2'
40 No required field 'ext_field_3'
41 No required field 'd_title'
42 No required field 'd_f_name'
43 No required field 'd_l_name'
44 No required field 'd_m_name'
45 No required field 'd_firma_name'
46 No required field 'd_firma_code'
47 No required field 'd_tax_number'
48 No required field 'd_email'
49 No required field 'd_birthday'
50 No required field 'd_home'
51 No required field 'd_apartment'
52 No required field 'd_street' or 'street_nr'
53 No required field 'd_zip'
54 No required field 'd_city'
55 No required field 'd_state'
56 No required field 'd_country'
57 No required field 'd_phone'
58 No required field 'd_mobil_phone'
59 No required field 'd_fax'
60 No required field 'd_ext_field_1'
61 No required field 'd_ext_field_2'
62 No required field 'd_ext_field_3'
70 Users self-registration or self-activation is disabled
71 Wrong activation token
72 Failed to activate the user
73 User's account is not activated or blocked
74 The order does not belong to the current user
wishlist_error
1 Wrong quantity
2 Quantity less than minimal
3 Quantity more than maximal
4 Not enough products in stock
5 No required product attribute(s)
6 No required product free attribute(s)
7 Unknown atribute id
8 Unknown atribute value
9 Unknown free atribute id
10 Unknown product index