Getting Started

Authentication

A word on some important items on the topic of authentication with your Zaui system:

• User of the API is always through an existing user (contact) in your Zaui system

• There is no special API user

• You are required to add a new contact to your system when you wish to generate a new token

• Each application/service/user must have a single unique token

• All requests must come through POST HTTPS

• Security is provided through your existing SSL certificate and is the only means of communicating with your Zaui system.

Any organization wishing to use this API must be provided with authentication credentials.

Creating an API Token

Once you have created the contacts within your system, you can now create and manage their ZAPI tokens. Tokens are managed from Resellers -> API Integrations from within your Zaui system.

To create a new token:

1. Resellers -> API Integrations

2. Create ZAPI Partner from the left menu

3. Select the Affiliate User

4. Save

Once you have added your new service to the system, you’re not able to bring up the “details” for this particular partner. Some of the details include the following:

• Affiliate username – this is the contact's name as you had created it.

• Company/Organization – this is the parent organization that your contact is associated with.

• ZAPI Token – the token that must be used for a partner to communicate with your Zaui system.

• Account Id: the account Id generated by your Zaui system. If your contact has a parent organization then this will have a value greater than zero.

• User Id: this is the unique Id generated by your Zaui system when you created the new contact in your system.

• The last 20 ZAPI requests and responses from this client – see a detailed breakdown of the last 20 communications between the systems.

Submitting to the API

​Ping

POST https://{yourdomainname}.zaui.net/zapi/

A simple ping test to ensure your token and API test is working

Request Body

Name	Type	Description
zapiToken	string	The token
zapiAccountId	integer	The account ID for the user
zapiUserId	integer	The contact ID
zapiMethod.methodName	string	The method name you wish to call

200 XML Response

{
    "response": {
        "zapiVersion": "2.1",
        "error": "0",
        "message": "OK",
        "methodResponse": {
            "methodName": "zapiPing",
            "methodErrorCode": "0",
            "methodErrorMessage": "Pong"
        }
    }
}

​API Throttle and Exponential Back-Off

To ensure continuous quality of service, API usage can be subjected to throttling. The throttle will be applied once an API client reaches a certain threshold. Zaui reserves the right to throttle any and all API clients to ensure the quality of service for all Zaui Software customers.

We return an HTTP 503 Response with the error node populated with expected back-off wait times.

We encourage all API developers to anticipate this error and take appropriate measures like:

• using a cached value from a previous call

• passing on a message to the end-user that is subjected to this behaviour (if any)

• implement exponential back-off in your logic