Zoined API (ZAPI)
Zoined API enables customers or third parties to send their data to Zoined using RESTful HTTP API. Uploaded data will be processed and stored to our data warehouse and used for generating analytic reports for the retailers. API service has end points for almost every facet of a retail business be it sales, inventory or even employee time keeping.
This document contains instructions on how to access the Zoined API. This document contains two parts: introduction and reference. Introduction walks you through the general structure of the API and how to use it. Reference contains detailed documentation for each API end point including code examples for multiple programming languages, and live in-browser testing tool for the API end points.
If you have any questions related to Zoined API, don't hesitate to contact Zoined support.
Every client must authenticate itself to send data towards any end points in Zoined API service. This means that every request to the service must have an authorization header with an identification token. Token is unique to every customer and can be obtained by contacting Zoined support services.
An example of the header would be:
Authorization: Bearer dGVzdGlhc2lha2FzOnZhaWtlYXBhc3N1All traffic to Zoined API is sent with HTTPS and protected with TLS.
API service uses JSON data format to exchange data with clients. This means all replies to clients will be delivered in JSON (including all possible error messages). The successful requests; i.e. the requests which delivered data in the correct format and thereby resulted in successful archiving of data will get 200 OK response with a JSON message conveying number of records and the model to which it has been been added. This message looks like:
{
status: OK
msg: "1 Customer added"
}Error handling is done through standard HTTP status codes where code 200 means successful reply (no errors) and any other code describes error conditions while executing the service. Usually error code is accompanied by JSON reply that further describes what went wrong. Generally following error codes are used:
- 400 – Means that there is something wrong with the request submitted by the client. Usually there is JSON-reply describing the error. In most cases it is caused by missing or malformed request body (JSON), missing mandatory fields in the JSON or Type errors, e.g character instead of number, date/time format issues etc. Below is an example of visitors end point if an empty request body was sent.
{
"status": "NOT OK",
"msg": [
"/visitors: error.path.missing",
"/date: error.path.missing",
"/organisation_id: error.path.missing",
"/time: error.path.missing"
]
}- 401 – This code means that authentication has failed, due to missing or incorrect access token in authorization header. The response JSON body would be:
{
"status":"NOT OK",
"msg":"Unauthorized"
}- 404 – Requested service does not exist or request method (eg. GET vs. POST) is incorrect. The response JSON in this case would be:
{
"status":"NOT OK",
"msg":"End point requested does not exist"
}- 500 – There was an internal error while processing the request. This is often a problem with the service itself. If this persists please contact Zoined service team with detailed information about the error
{
"status":"NOT OK",
"msg":"An Exception Occurred"
}- 503 – Service is entirely offline. This indicates maintenance break or problem with the infrastructure. If error persists, please contact support.
Q: How do I choose data format to send my data?
A: You need to set Content-Type header in your request to correct value. Zoined API currently supports either JSON or CSV data formats. Any other format is NOT supported and will cause error reply. By default we assume content is application/json but it can be changed to CSV by adding header:
Content-Type: application/csvQ: What is the number format?
No thousand separators. Use dot . as decimal separator.
Q: What is the date format?
A: All dates should be in ISO-format "YYYY-MM-DD".
Q: How do I enter the time? What is "Z" at the end of the time example?
A: Enter the time in 24 hour format "H24:Mi:ss". 'Z' stands for UTC time zone and is optional like all time zone information. Zoined will always use local time so any time zone information is just ignored and no time zone conversions are done.
Q: Do I enter values and headers with quotes (single or double) or without?
A: For JSON, use double quotes for all headers and values. For CSV, do not use anything for either except when escaping special characters (see below).
Q: How do I escape special characters in CSV?
A: If field value has separator character (eg. ;) backslash \ or double quote " in it, you'll need to escape it by wrapping the field value with double quotes " and prefixing any double quotes and backslashes with backslash. For example value example;\"value" should be converted to "example;\\\"value\"". Separator character can be specified with separator query string parameter. By default we assume semicolon ';'. Escape characters ('' and '"') cannot be changed.
Q: What character encoding should be used?
A: For JSON the standard specifies that character set should be Unicode with either UTF-8, UTF-16 or UTF-32 encoding. For CSV you can use any character encoding where separators and other special characters are encoded with single byte. Hence pure multi-byte encodings like UTF-16 are NOT supported with CSV format but mixed ones like UTF-8 are as long as special characters are encoded with single byte. Encoding should be specified with encoding query string parameter and it must correspond to encoding used in actual data. If unspecified then by default UTF-8 is assumed.
Q: How to get best performance for bigger data volume uploads?
A: First of don't send your data one row at a time by making separate API call for each row. That will severely degrade performance of overall data load causing it to take significantly longer time to complete. Instead use fixed size chunks of suitable size (eg. 100000 rows per chunk) for each API call. Json format is also generally slightly faster to process than csv data format.