Getting Started Guide

This Getting Started Guide contains general information that is applicable to the entire API. Following topics are covered:

  • API URL
  • Authentication
  • Making Requests
  • Rate Limit
  • Security
  • Data Format

API URL

Your API URL is the base URL for your API. It is normally in the following 2 formats:

https://{your account id}.imonggo.com 
https://{your account id}.c{n}.imonggo.com

You can find out your API url by sending a GET request to

http://secure.imonggo.com/system/api_url?account_id={your account id}

For all the examples in this documentation, you need to replace the API url with your own.

API Token

Your API token is the needed to access the API. It works as the "password" to access the API.

Your API token can be found by logging into your Imonggo account, clicking on the "My Info" link in the upper-right, and then clicking the "show" under "API token". Please note that "API token" section will only be shown if API Interface is enabled (from Control Center > Premium Features).

It is also possible to retrieve the API token programmatically by passing your email and password. Please refer to Token API article for more information.

Authentication

Authentication is managed using HTTP basic authentication. Every request must include the Authorization HTTP header. Use your API token as the username, and "X" (or some otherwise bogus text) as the password (only the API token is used for authenticating API requests).

Below example shows you how you can access list of products using Linux curl command utility.

curl -u b3288678ba5a1b81a504e2921b4ed96b9eacb561:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
https://test_account.imonggo.com/api/products.xml

Making Requests

Be sure to set both the 'Content-Type' and 'Accept' headers to 'application/xml' to identify the request and response format. See example above.

If a request succeeds, it will return a status code in the 200 range and often, an XML-formatted response. Note that, in general, if a request causes a new record to be created, the response will use the "201 Created" status. Any other successful operation (like a successful query, delete, or update) will return a 200 status code.

If a request fails, a non-200 status code will be returned, possibly with error information in XML format as the response's content.

Rate Limit

You can perform up to 100 requests per hour for the same account. If you exceed this limit, you'll get a 503 response for subsequent requests.

Security

You can use either plain HTTP or HTTPS with Imonggo. For security purpose, we recommend that you use HTTPS.

It is important to understand that Imonggo currently does not distinguish user roles in API. Anyone regardless the role (cashier, supervisor, manager or owner) who has the API token has access to entire API. It is up the application to implement application level restrictions.

Data Format

Date Field

When communicating with the server, you should use UTC date and time format (YYYY-MM-DDTHH:HH:SSZ). Although server is smart enough to parse other date formats, it is recommended that you use UTC date format to ensure future compatibility.

Boolean Field

When passing boolean fields server, Imonggo accepts both "true" and "1" as true and "false" and "0" as false.

Text Field

All text fields have maximum width as indicated in the documentation. If you submit to the server a string with length more than the maximum width, the excess is truncated without any warning.

Back to Contents Page