IT's Perfect RESTful API
The IT's Perfect API allows you to perform GET, POST, PUT and DELETE requests with the ERP system. Our API is built using REST principles which ensure predictable URLs that make writing applications easy. This API follows HTTP rules, so a wide range of HTTP clients can be used to interact with the API.Authentication
All endpoints need to be authenticated using an authentication token. The authentication token is parsed in the URL, for example:/api/v2/items/&token={token}The auth token should by obtained by the ERP system. There are two kinds of auth tokens:
- General API auth token
The token should be added by Settings > API > Add. The permissions should be selected in the permission tab. - Webshop auth token
Every webshop added in the ERP system has an auth token. The token could be obtained by Settings > Webshops > Details. The webshop auth token gives access to the following endpoints:- products (GET, only the products which are assigned to the webshop)
- customers (PUT)
- orders (GET, only orders which are assigned to the webshop)
- orders (PUT)
- stock (GET, only the webshop warehouse)
- sellingpoints (GET)
Authorization
It is possible to set an optional basic RESTful user authorization. The optional user authorization can be set via the ERP system. If the optional user authorization is enabled, the connection should be secured with a username and password.HTTP methods
Method | Description |
GET | Used for retrieving resources |
POST | Used for creating resources and performing resource actions |
PUT | Used for updating resources |
DELETE | Used for deleting resources |
Response
Responses will be in the JSON format. The API will send a header with one of the following http status codes:
HTTP Code | Description |
200 | OK |
401 | Unauthorized |
404 | Not Found |
405 | Method Not Allowed |
500 | Internal Server Error |
In case of an error, the error description would be returned in JSON, for example:
{"error":"The authentication token () is not correct"}
Pagination
The response headers provide information about the pagination:Header | Description |
X-Pagination-Total-Count | Total number of results |
X-Pagination-Per-Page | Number of results per page |
X-Pagination-Page-Count | Number of pages |
X-Pagination-Current-Page | Current page |
/api/v2/items/&token={token}&page=1&limit=15
Filter syntax
In every request (GET, POST, PUT & DELETE) search parameters are available or even necessary. Every endpoint provide information about the posibility to filter based on an unique identifier, for example:/api/v2/products/{id}It is also possible to add additional parameters in the URL with the form:
name operator 'expression'Filter operators:
Operator | Description |
eq | Equal to |
ne | Not equal to |
gt | Greater than |
lt | Less then |
ge | Greater than or equal to |
le | Less than or equal to |
in | Value is in expression (Only numeric values, all values placed between '', e.g. '101,102') |
search | Search in string with index optimisation, e.g. search '101' |
like | Search in string without index optimisation, e.g. like '101' |
Some filter URL examples:
One filter: /api/v2/products/&filter=item eq 'ED-101' And logic: /api/v2/products/&filter=price qt '100'&filter=price lt '200' Or logic: /api/v2/products/&filter=id eq '101','102' In logic: /api/v2/products/&filter=id in '101,102' *Note: make sure you URL encode the filter variable, for example, the result of urlencode("item eq 'ED-101'") is item+eq+%27ED-101
Selected fields
Specific fields could by selected by adding the GET parameter 'fields', for example:
/api/v2/items/&fields=id,itemNumber,item
PUT variables
Not all the variables could be updated by the PUT request. See the endpoint documentation for the appropriate update variables.
Date and decimals
All timestamps are returned and should be submitted in ISO 8601 format: YYYY-MM-DD AND YYYY-MM-DD hh:mm:ss. All numbers will be returned and should be submitted in ISO 31-0 format: xxxx.xx.Date and decimal examples:
Date: 2016-01-15 Datetime: 2016-01-15 13:25:04 Numbers: 1000.00
API usage limits
The IT's Perfect API enforces a default limit of 750 requests per hour, calculated as the sum of client-side and server-side requests. If your app exceeds the initial limit, the app will start failing. The usage information can by checked via the response headers:
Header | Description |
X-Request-Limit-Date | End date of the usage limit |
X-Request-Limit-Remaining | Remaining number of requests |