Limits

API allows at most 1000 requests per hour, per account. Once you reach that limit, all API calls will start returning error code 1002.

If your application hits the limit, the recommended course of action is to wait until the beginning of next hour and resume operations. For example, you may configure your application to retry every 10 minutes until the limit clears.

Detailed response

API queries getCustomers(), getSuppliers() and getEmployees() have an option to get an extended response. Detailed response also includes fields from normal response. To get detailed response set input parameter "responseMode" as "detail".

Security

It is recommended to create a separate user account for API communication.

To enable maximum security it is important to set CA certificate location. The CA cert will then be used to validate that Erply certificate is not being spoofed.

Below is an example for setting the CA cert location:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

// Include json parser
using Newtonsoft.Json.Linq;

namespace apiExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize class
            EAPI api = new EAPI();

            // Configuration settings
            api.clientCode = "eng";
            api.username = "demo";
            api.password = "demouser";
            api.sslCACertPath = "/path/to/ErplyCACert/cert.crt";
            api.url = "https://" + api.clientCode + ".erply.com/api/";

            try
            {
                JObject json = api.sendRequest("getClientGroups");
                Console.WriteLine(json.ToString());
            }
            catch (Exception e)
            {
                // Handle exceptions
            }
            Console.ReadKey();
        }
    }
}

## load ERPLY API class
load "EAPI.class.rb"

## Initialise class 
api = EAPI.new()

# Configuration settings 
api.clientCode = "eng"
api.username = "demo"
api.password = "demouser"
api.url = "https://"+api.clientCode+".erply.com/api/"
api.sslCACertPath = "/path/to/ErplyCAcert/cert.crt"

result = api.sendRequest("getClientGroups")

require 'pp' # Only for test purposes
fr87pp JSON.parse(result)

Error handling

An API request saveProduct() with parameters:

• clientCode = eng
• request = saveProduct
• name = Pizza Pepperoni

will get a response like this:

{
	"status":{
		"request":"saveProduct",
		"requestUnixTime":1370604415,
		"responseStatus":"error",
		"errorCode":1061,
		"errorField":null,
		"generationTime":0.097069025039673,
		"recordsTotal":0,
		"recordsInResponse":0
	},
	"records":null
}

If responseStatus is "error", the call has failed. For reference, all possible error codes are listed here.

In current case, the authenticated user does not have rights to add new products.

Your API class may also rise additional Exceptions. Be sure to handle these also.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

// Include json parser
using Newtonsoft.Json.Linq;

namespace apiExample
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize class
            EAPI api = new EAPI();

            // Configuration settings
            api.clientCode = "eng";
            api.username = "demo";
            api.password = "demouser";
            api.url = "https://" + api.clientCode + ".erply.com/api/";

            try
            {
                JObject json = api.sendRequest("getClientGroups");
                if (json["status"]["errorCode"].ToString().Equals("0"))
                {
                    Console.WriteLine("Request was successful");
                }
                else if(json["status"]["errorCode"].ToString().Equals("1061")) {
                    Console.WriteLine("We do not have sufficient privileges");
                }
                else
                {
                    Console.WriteLine("There was some other error");
                }
            }
            catch (EAPIException e)
            {
                if (e.errorCode == EAPI.MISSING_PARAMETERS)
                {
                    Console.WriteLine("Some parameters are missing");
                }
                else if (e.errorCode == EAPI.WEBREQUEST_ERROR)
                {
                    Console.WriteLine("Failed to connect to erply server");
                }
                else if (e.errorCode == EAPI.VERIFY_USER_FAILURE)
                {
                    Console.WriteLine("Failed to verify user");
                }
            }
            catch (Exception e)
            {
                // other exceptions
            }
            Console.ReadKey();
        }
    }
}

## load ERPLY API class
load "EAPI.class.rb"
require 'json'

## Initialise class 
api = EAPI.new()

# Configuration settings 
api.clientCode = "eng"
api.username = "demo"
api.password = "demouser"
api.url = "https://"+api.clientCode+".erply.com/api/"

begin
	result = api.sendRequest("getSalesDocuments")
	json = JSON.parse(result);

	if(json["status"]["errorCode"] == 0) 
		print "Request was successful"
	elsif(json["status"]["errorCode"] == 1061) 
		print "We do not have sufficient privileges" 
	else 
		print "There was some other error"
	end

rescue MissingArgumentsException => e
	print "Some parameters are missing."
rescue VerifyUserException => e
	print "Failed to verify user."
rescue Exception => e
	print "Other exception: " + e.message
end

Response type

Default response format is JSON. If we send a parameter responseType with value "XML", the API response will be in XML format.

For example, an api request verifyUser() with wollowing parameters:

• clientCode = eng
• username = demo
• password = demouser
• responseType = XML

will return a XML document:

<?xml version="1.0" encoding="UTF-8"?>
<document>
	<status>
		<request>verifyUser</request>
		<requestUnixTime>1370598320</requestUnixTime>
		<responseStatus>ok</responseStatus>
		<errorCode>0</errorCode>
		<generationTime>0.079717874526978</generationTime>
		<recordsTotal>1</recordsTotal>
		<recordsInResponse>1</recordsInResponse>
	</status>
	<records>
		<item>
			<userID>6</userID>
			<userName>demo</userName>
			<employeeID>4</employeeID>
			<employeeName>Clara Smith</employeeName>
			<groupID>7</groupID>
			<groupName>sales representatives</groupName>
			<sessionKey>xtSm9aff4ca870df9dba6381a2b539f0a409d3585e77</sessionKey>
			<sessionLength>3600</sessionLength>
			<loginUrl>https://s3.erply.com/eng/</loginUrl>
		</item>
	</records>
</document>

Bulk API calls

It is possible to send API calls in bulk. In other words, you can compose an HTTP request that contains many API calls; API will process all the calls and return all results simultaneously.

Bulk calls must be independent of each other. The bulk feature is suitable for imports (eg. sending many saveProduct calls), but not for combining a saveSalesDocument and a savePayment call — because for storing the payment, you need to know the ID of the invoice that you just created.

In case of bulk API calls, input parameters must be sent not as POST parameters, but as a JSON structure, named “requests”. (You can still retrieve results as JSON or XML as needed, but input must always be JSON.)

"[
	{"requestName":"getProducts","recordsOnPage":1,"requestID":1},
	{"requestName":"getSalesDocuments","recordsOnPage":1,"requestID":2}
]"

Sending just these three POST parameters should be sufficient:

• sessionKey
• clientCode
• requests

The response structure will look like this. There is a general header (which may contain a general error code that applies to the whole request), and there are sub-structures for each individual request.

{
	"status":
	{
		"requestUnixTime":1369410559,
		"responseStatus":"ok",
		"errorCode":0,
		"generationTime":0.58838200569153
	},
	"requests":
	[
		{
			"status":
			{
				"requestName":"getProducts",
				"requestID":1,
				"requestUnixTime":1369410559,
				"responseStatus":"ok",
				"errorCode":0,
				"generationTime":0.1500449180603,
				"recordsTotal":76,
				"recordsInResponse":1
			},
			"records":
			[
				{...}, ...
			]
		},
		{
			"status":
			{
				"requestName":"getSalesDocuments",
				"requestID":2,
				"requestUnixTime":1369410559,
				"responseStatus":"ok",
				"errorCode":0,
				"generationTime":0.58054494857788,
				"recordsTotal":166,
				"recordsInResponse":1
			},
			"records":
			[
				{...}, ...
			]
		}
	]
}

A bulk call may contain at most 100 requests. If you send more requests, API will return error code 1020 and will not process any of the calls.

If there is an error code in the general header, API will most likely return no results at all. As a general error, API may return:

1. a 100x error (an issue with API, the account, request parameters missing etc.)
2. a 105x error (authentication)

In any other case, API will make an effort to return a response for each of the requests — but it is not guaranteed. The requests are processed in the same order as specified in input. For additional verification, you may assign a requestID to each of the sub-requests; the same value will be returned in response header.

Some usage notes and tips:

1. Processing bulk calls will take considerably longer that processing a single call. Use a longer request timeout.
2. The following input parameters must be sent as top-level parameters and apply to the whole request. You cannot vary these input parameters from one request to another:
   • lang
   • clientCode
   • sessionKey
   • responseType