API Basics

Authentication and method calling

In order to use the API you need to be subscribed to a package that supports it and to obtain API Key and Secret. To do this after you login click on the API link from the sidebar.

The calling of a method of the API is done by posting and XML to the server. The response from the server is also in XML.

The API calls endpoint is:

http://azonmobile.com/xml_server.php

or

https://azonmobile.com/xml_server.php

All XML requests you should send to this URL by using the HTTP method POST. To do this you can use the Curl library or the capabilities of your programming language of choice.

 

Here is a sample XML request:

<request>
    <application>tracking</application>
    <package>qrcodes</package>
    <controller>generator</controller>
    <action>generate</action>
    <key>YOUR_API_KEY_HERE</key>
    <timestamp>1337325750</timestamp>
    <hash>32_CHARS_HASH_HERE</hash>
    <arguments>......</arguments>                  
</request>

Where:

  • application, package, controller and action arguments describe the specific controller and method you want to invoke based on thecific platform function you need.
  • key is your API key
  • timestamp - the unix timestmap of the request
  • hash - this hash is used to sign your request. See below how it is constructed
  • arguments - an optional argument that is an array of arguments provided to the controller. Thwith arguments is available in the documentation for each method.

The hash is constructed by putting the timestamp used in the <timestamp> field in a string with your API secret and then passing them throught the sha256 algorithm. A sample code in PHP would be:

$hash  = hash('sha256' , $timestamp.$api_secret);

Providing arguments

The arguments can be of type string, integer or float (double). They have to be declared this way in the in the posted XML - set the attribute type to the appropriate type. Here is a sample call:

    <arguments>
        <campaign_id type="integer">61</campaign_id>
        <campaign_name type="string">campaign1</campaign_name>
    </arguments>

Certain methods accept associative arrays as arguments. In this case the request would look as:

    <arguments>       
        <qrcode_type type="integer">8</qrcode_type>
        <qrcode_arg arrindex="[map_lat]" type="double">60.02</qrcode_arg>
        <qrcode_arg arrindex="[map_lng]" type="double">30.03</qrcode_arg>
    </arguments>

There are also methods that accept file uploads. To provide a file as an argument you need to provide the following:

    <arguments>
        <qrcode_background_image filename="image.png">base64-data</qrcode_background_image>
    </arguments>

Where the base64-data is you need to provide the content of the file encoded with base64. In PHP this can be done with: "base64_encode(file_get_contents('./image.png'));"

Server response

The server returns XML including in the event of an error. Follows a sample response with an error:

<ctrl_data>
    <message>The provided hash is not correct.</message>
    <code>-105</code>
</ctrl_data>

The response always has a message and code sections. Depending on the specific request it may contain additional sections that are documented for each method.

A negative exit code means failure. In this event the methods will usually return -1 and in event of success the return code will be positive (usually 1). Each method has these documented. Below are listed the special error codes that would indicate that there is some problem with your request:

Code Description
-101 API key not provided
-102 Hash not provided
-103 Timestamp not provided
-104 Invalid API key provided
-105 Wrong hash provided
-106 Invalid timestamp provided
-107 Invalid XML provided
-201 Invalid controller/action called
-202 You are not authorized to invoke the requested controller/action
-203 The requested object/record does not exist.
-204 You are not authorized to access the requested object/record.
-205 No object/record requested (certain controllers/actions require at least one argument)