Examples

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

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.

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:

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():

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

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

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

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] =>
)