This is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.
Want to get started with API integration? Here's a quick check list:
- Register as a partner in Zala
- Once inside your partner's admin panel, go to the "Apps" section and create your app.
- Read up on how to authenticate your app with us.
- Read the API docs to understand what you can do with your app.
All URLs start with https://api.zala.app/v1/{business_id} or with https://sandbox.zala.app/v1/{business_id}. SSL only. The path is prefixed with the business id and
the API version.
If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the
old URLs.
So if you want to access the business with id acme_business via the API the url will
be https://api.zala.app/v1/acme_business.
To make a request for all the business's products you would do the following in curl:
curl -H 'Authentication: bearer ACCESS_TOKEN ' \
-H 'User-Agent: MyApp ([email protected])' \
https://api.zala.app/v1/acme_business/orderswhere ACCESS_TOKEN is the business's access token for your app (see Authentication).
We follow the OAuth 2 framework for letting users authorize your application to use Zala on their behalf. Quite briefly, when a user installs it you can obtain an access token (a secret string denoting your rights over his business), which you have to include in the header of every request (as shown in the above example).
Read the authentication guide to get started.
In every API request, you must include a User-Agent header with the name of your application and a link to it or your
email address so we can get in touch with you. Here's a couple of examples:
User-Agent: Super app (http://superapp.com/contact)
or
User-Agent: Awesome app ([email protected])
If you don't supply this header, you will get a 400 Bad Request response.
All data is sent and received as JSON. Our format is to have no root element and we use camelCase to describe
attribute keys. This means that you have to send Content-Type: application/json; charset=utf-8 when POSTing or PUTing
data into Zala.
You'll receive a 415 Unsupported Media Type response code if you leave out the Content-Type header.
These are the possible types of client errors on API calls that receive request bodies:
- Sending invalid JSON will result in a
400 Bad Requestresponse.
HTTP/1.1 400 Bad Request
Content-Length: 34
{"error": "Failed to read request"}
If Zala is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also
see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It's your responsibility in all of these
cases to retry your request later.
In order to control the incoming traffic from the API, you can perform a limited number of requests in a given period of time. Currently, the approach used to limit the API usage is based on a Leaky Bucket algorithm implementation, where the default bucket size is of 40 requests with a leaky rate of 2 requests per second, which means that you can perform up to 2 requests per second, with bursts of 40 requests, without getting a 429 Too Many Requests error. We use the following headers to provide information about the limit usage:
X-Rate-Limit-Limit: Total requests that can be done in a given period, in the case, the bucket size.X-Rate-Limit-Remaining: Remaining requests to completely fill the bucket.X-Rate-Limit-Reset: Remaining milliseconds to completely empty the bucket.
Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with
the page parameter. You can also set a custom page size up to 200 with the size parameter.
curl -H 'Authentication: bearer ACCESS_TOKEN ' \
-H 'User-Agent: MyApp ([email protected])' \
https://api.zala.app/v1/acme_business/orders?page=2&per_page=100Note that page numbering is 1-based and that omitting the page parameter will return the first page.
To check the total count of the results you can use the X-Total-Count header:
X-Total-Count: 156
To check the next and previous links for pagination you can use the Link header:
Link: <https://api.zala.app/v1/acme_business/orders?page=3&size=100>; rel="next",
<https://api.zala.app/v1/acme_business/orders?page=50&size=100>; rel="last"
The possible rel values are:
next: Shows the URL of the immediate next page of results.last: Shows the URL of the last page of results.first: Shows the URL of the first page of results.prev: Shows the URL of the immediate previous page of results.
You should use the Link URLs instead of building your own.
Where possible, API v1 strives to use appropriate HTTP verbs for each action.
GET: Used for retrieving resources.POST: Used for creating resources.PUT: Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.DELETE: Used for deleting resources.
Being a monthly subscription service, it's possible that a business will not renew its service. In this case, the business will go offline and the API will be inaccessible.
In either case, all API calls will return a 402 Payment Required
response, Webhooks will not be called. Please
make sure you handle this error code to notify the user that he needs to resume his payment instead of displaying a
generic server error.
Once the required payment is made, the API becomes accessible again.
API resources
Please tell us how we can make the API better. If you have a specific feature request or if you found a bug, please use GitHub issues. Feel free to fork these docs and send a pull request with improvements.
To talk with us about the API, feel free to write to mailto:[email protected].