Powered by Olark

InventoryAPI by Erply is a powerful backend for web shops, and more.

  • Use as a backbone for any web shop
  • Plug into your existing software
  • Connect inventory with POS and accounts
Developer
competition

Erply Inventory API

Examples

Here are some examples that show how to send requests to Erply API. See also the Getting Started page.

Input Output
HTTP POST request XML / JSON document

Some simple requests

Let us assume that our Erply account number is 2881 and we have a user with username "apiuser" and password "myapiaccess".

We will start an API session by calling verifyUser() first.

Input parameter Value
clientCode 2881
request verifyUser
version 1.0
responseType XML
username apiuser
password myapiaccess

Server will return an XML document:

<?xml version="1.0" encoding="UTF-8"?>
<document>
        <status>
            <request>verifyUser</request>
            <requestUnixTime>1274274215</requestUnixTime>
            <responseStatus>ok</responseStatus>
            <errorCode>0</errorCode>
            <generationTime>0.0115809440613</generationTime>
            <recordsTotal>1</recordsTotal>
            <recordsInResponse>1</recordsInResponse>
        </status>
        <records>
            <item>
                <userID>3</userID>
                <userName>apiuser</userName>
                <employeeID>10</employeeID>
                <employeeName>API User</employeeName>
                <groupID>7</groupID>
                <groupName>limited-access users</groupName>
                <sessionKey>d26:d4bd632a4164495229299ff015bebc02e30083b3</sessionKey>
                <sessionLength>3600</sessionLength>
            </item>
        </records>
    </document>

This response gives us some additional information about the user and also a session key that must be used for all subsequent API calls.

Now let us retrieve some information through the API — product groups, for example:

Input parameter Value
clientCode 2881
request getProductGroups
version 1.0
responseType XML
sessionKey d26:d4bd632a4164495229299ff015bebc02e30083b3

The response will be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<document>
	<status>
		<request>getProductGroups</request>
		<requestUnixTime>1274277783</requestUnixTime>
		<responseStatus>ok</responseStatus>
		<errorCode>0</errorCode>

		<generationTime>0.00125312805176</generationTime>
		<recordsTotal>5</recordsTotal>
		<recordsInResponse>5</recordsInResponse>
	</status>
	<records>
		<item>
			<id>8</id>
			<name>Drinks</name>
			<subGroups>
				<item>
					<id>11</id>
					<name>Coffee</name>
					<subGroups></subGroups>
				</item>
				<item>
					<id>12</id>
					<name>Other beverages</name>
					<subGroups></subGroups>
				</item>
			</subGroups>
		</item>
		<item>
			<id>2</id>
			<name>Sandwiches</name>
			<subGroups></subGroups>
		</item>
		<item>
			<id>6</id>
			<name>Pizza</name>
			<subGroups></subGroups>
		</item>
	</records>
</document>

Instead of XML, we might want to use JSON. If we had omitted input parameter responseType=XML, response would have been as follows:

{
"status": {
    "request":"getProductGroups",
    "requestUnixTime":1274278311,
    "responseStatus":"ok",
    "errorCode":0,
    "generationTime":0.0028989315033,
    "recordsTotal":6,
    "recordsInResponse":6
},
"records":[
    {
        "id":"8",
        "name":"Drinks",
        "subGroups":[
            {
                "id":"11",
                "name":"Coffee",
                "subGroups":[]
            },
            {
                "id":"12",
                "name":"Other beverages",
                "subGroups":[]
            }
        ]
    },
    {
        "id":"2",
        "name":"Sandwiches",
        "subGroups":[]
    },
    {
        "id":"6",
        "name":"Pizza",
        "subGroups":[]
    }
]
}

Let us also try creating some new entries in the database. Function saveProduct():

Input parameter Value
clientCode 2881
request getProductGroups
version 1.0
responseType XML
sessionKey d26:d4bd632a4164495229299ff015bebc02e30083b3
groupID 6 (We are using one of the product group IDs returned by getProductGroups())
name Pizza Pepperoni, large
code 181
netPrice 12.50

And the response:

<?xml version="1.0" encoding="UTF-8"?>
<document>
	<status>
		<request>saveProduct</request>
		<requestUnixTime>1274279473</requestUnixTime>
		<responseStatus>error</responseStatus>
		<errorCode>1012</errorCode>
		<errorField>code</errorField>
		<generationTime>0.145617961884</generationTime>
		<recordsTotal>0</recordsTotal>
		<recordsInResponse>0</recordsInResponse>
	</status>
</document>

An error?!

ERPLY requires, among other things, that SKUs have unique codes. Error 1012 means that one of the input parameters does not have a unique value; attribute "errorField" clarifies that problem lies with input parameter "code". See the list of all possible error codes.

If we assign our new product another code and resend the request, the response will be:

<?xml version="1.0" encoding="UTF-8"?>
<document>
	<status>
		<request>saveProduct</request>
		<requestUnixTime>1274279459</requestUnixTime>
		<responseStatus>ok</responseStatus>
		<errorCode>0</errorCode>
		<generationTime>0.0458831787109</generationTime>
		<recordsTotal>1</recordsTotal>
		<recordsInResponse>1</recordsInResponse>
	</status>
	<records>
		<item>
			<id>67</id>
		</item>
	</records>
</document>

Now everything is OK; our product was saved and assigned an ID of 67.

Sample PHP API class

First let us define a simple PHP class for preparing and sending POST requests using CURL

EAPI.class.php   download PHP code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
<?php

class EAPI {

    public 
$url;
    public 
$clientCode;
    public 
$username;
    public 
$password;

    
// Sends POST request to API
    
public function sendRequest($request$parameters = array()){

        
// Check if all nessecary parameters are set up
        
if(!$this->url OR !$this->clientCode OR !$this->username OR !$this->password)
            return 
false;

        
// Include clientcode and request name to POST parameters
        
$parameters['request'] = $request;
        
$parameters['version'] = "1.0";
        
$parameters['clientCode'] = $this->clientCode;

        
// Get session KEY
        
if($request != "verifyUser"){

            
$parameters['sessionKey'] = $this->getSessionKey($keyRequestResult);

            
// Instead of a KEY we got an array which contains error code, let's return in
            
if(!$parameters['sessionKey'])
                return 
$keyRequestResult;
        }

        
// Prepare POST request
        
$ch curl_init();
        
curl_setopt($chCURLOPT_URL$this->url);
        
curl_setopt($chCURLOPT_HEADER,1);
        
curl_setopt($chCURLOPT_HTTPAUTHCURLAUTH_ANY);
        
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
        
curl_setopt($chCURLOPT_SSL_VERIFYHOSTfalse);
        
curl_setopt($chCURLOPT_RETURNTRANSFER1);
        
curl_setopt($chCURLOPT_POST,true);
        
curl_setopt($chCURLOPT_SSLVERSION3);
        
curl_setopt($chCURLOPT_POSTFIELDS$parameters);

        
// call POST request
        
if(curl_exec($ch) === false)
            return 
false;

        
// get response content
        
$content curl_multi_getcontent($ch);
        
curl_close($ch);

        
// remove heders
        
list($header1,$header2,$body) = explode("\r\n\r\n",$content,3);

        
// return response body
        
return $body;

    }

    private function 
getSessionKey(&$result) {

        
// Session KEY is active, return active KEY
        
if(isset($_SESSION['EAPISessionKey'][$this->username]) AND $_SESSION['EAPISessionKey'][$this->username] AND $_SESSION['EAPISessionKeyExpires'][$this->username] > time())
            return 
$_SESSION['EAPISessionKey'][$this->username];

        
// New session KEY must be obtained
        
else {

            
// Perform API request to get session KEY
            
$result $this->sendRequest("verifyUser", array("username" => $this->username"password" => $this->password) );

            
// JSON response into PHP array
            
$response json_decode($resulttrue);

            
// If user has been changed
            
if (!isset($response['records'][0]['sessionKey'])) {
                unset(
$_SESSION['EAPISessionKey'][$this->username]);
                return 
false;
            }

            
// Session KEY was successfully received
            
if($response['records'][0]['sessionKey']) {

                
// Set session KEY in client session and set KEY expiration time
                
$_SESSION['EAPISessionKey'][$this->username] =
                        
$response['records'][0]['sessionKey'];
                
$_SESSION['EAPISessionKeyExpires'][$this->username] =
                        
time() + $response['records'][0]['sessionLength'] - 30;

                
// Return obtained new session KEY
                
return $_SESSION['EAPISessionKey'][$this->username];
            }

            
// Session KEY was not received
            
else {

                
// Return API response which includes error code
                
unset($_SESSION['EAPISessionKey'][$this->username]);
                return 
false;
            }
        }
    }
}

?>

PHP sample 1, calls getClientGroups()

Using previous PHP API sample class, we can call an API function using the following example code:

See working example output: sample1.php   download PHP code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php
session_start
();

// include ERPLY API class
include('EAPI.class.php');

// Initialise class
$api = new EAPI();

// Configuration settings
$api->clientCode "eng";
$api->username "demo";
$api->password "demouser";
$api->url "https://".$api->clientCode.".erply.com/api/";

// Get client groups from API
// No input parameters are needed
$result $api->sendRequest("getClientGroups", array());

// Default output format is JSON, so we'll decode it into a PHP array
$output json_decode($resulttrue);

print 
"<pre>";
print_r($output);
print 
"</pre>";

?>

This call will give us the following result. A header tells whether the call succeeded or failed and tells how many records were returned. This is followed by an array of records.


Array
(
        [status] => Array
        (
                [request] => getClientGroups
                [requestUnixTime] => 1271144947
                [responseStatus] => ok
                [errorCode] => 0
                [generationTime] => 0.0235800743103
                [recordsTotal] => 3
                [recordsInResponse] => 3
        )

        [records] => Array
        (
        [0] => Array
                (
                        [clientGroupID] => 14
                        [parentID] => 0
                        [name] => Default customer group
                        [added] => 1160598110
                        [lastModified] => 1205604150
                )

        [1] => Array
                (
                        [clientGroupID] => 17
                        [parentID] => 0
                        [name] => Primary partners
                        [added] => 1262700263
                        [lastModified] => 0
                )

        [2] => Array
                (
                        [clientGroupID] => 18
                        [parentID] => 0
                        [name] => Possible leads
                        [added] => 1262700281
                        [lastModified] => 0
                )
        )
)

    

PHP sample 2, calls createProduct()

Next let us call a function that also needs some input parameters - for example, createProduct():

download PHP code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?php

// include ERPLY API class
include('EAPI.class.php');

// Initialise class
$api = new EAPI();

// Configuration settings
$api->clientCode "eng";
$api->username "demo";
$api->password "demouser";
$api->url "https://".$api->clientCode.".erply.com/api/";

// Create a new product.

$inputParameters = array(
    
"userID"   => 4,
    
"groupID"  => 1,
    
"name"     => "Pizza Pepperoni, large",
    
"code"     => "181",
    
"netPrice" => 12.50,
);

// Sales price of the item is expressed in the default currency of given ERPLY account.
// Let us assume that the default currency is USD.
// Since we do not specify a VAT rate, default VAT rate will be attached to the new product.

$result $api->sendRequest("createProduct"$inputParameters);
$output json_decode($resulttrue);

print_r($output);

?>

If the call is successful, the result will be as follows:


Array
(
        [status] => Array
        (
                [request] => createProduct
                [requestUnixTime] => 1271145848
                [responseStatus] => ok
                [errorCode] => 0
                [generationTime] => 0.0798168182373
                [recordsTotal] => 1
                [recordsInResponse] => 1
        )

        [records] => Array
        (
                [id] => 20
        )
)

    

System returns the ID of newly-created item.

However, Erply requires that SKU codes, if specified, must be unique. If supplied code is not unique, then the call will fail and result will look as follows. (Error code 1012 means "Supplied parameter is not unique").


Array
(
        [status] => Array
                (
                        [request] => createProduct
                        [requestUnixTime] => 1271146044
                        [responseStatus] => error
                        [errorCode] => 1012
                        [generationTime] => 0.0445239543915
                        [recordsTotal] => 0
                        [recordsInResponse] => 0
                )

        [records] =>
)

    
 
Ask your question and we will contact you
*
*
*
*
Erply is a service of Erply Ltd © 2010 Erply.
9th floor 107 Cheapside London
Company No. 07043823