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.
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".
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:
function changelang(area,lang) { document.getElementById(area+"_php").style.display = "none"; document.getElementById(area+"_csharp").style.display = "none"; document.getElementById(area+"_ruby").style.display = "none"; document.getElementById(area+"_"+lang).style.display = "block"; }
<?php
include("EAPI.class.php");
$api = new EAPI();
$api->clientCode = "eng";
$api->username = "demo";
$api->password = "demouser";
$api->sslCACertPath = "/path/to/ErplyCACert/cert.crt"; //this is the important line
$api->url = "https://".$api->clientCode.".erply.com/api/";
$result = $api->sendRequest("getClientGroups", array());
?>
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)
An API request saveProduct() with parameters:
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.
<?php
try {
$response = $eapi->sendRequest('getSalesDocuments', array());
$response = json_decode($response, true);
if(($response['status']['errorCode'] == '0')) {
echo 'Request was succesful';
} elseif($response['status']['errorCode'] == '1061') {
echo 'We do not have sufficient privileges';
} else {
echo 'There was some other error';
}
} catch (Exception $e) {
if($e->getCode() == EAPI::CURL_ERROR) {
echo 'Failed to connect to erply server';
} elseif($e->getCode() == EAPI::PHP_SESSION_NOT_STARTED) {
echo 'PHP session not started.';
} elseif($e->getCode() == EAPI::MISSING_PARAMETERS) {
echo 'Some parameters are missing.';
} elseif($e->getCode() == EAPI::VERIFY_USER_FAILURE) {
echo 'Failed to verify user.';
var_dump($e->response);
}
}
?>
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
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:
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>
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:
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:
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: