Partner API

[DRAFT] - This article is still in draft mode. It is only shown here for informational purpose.

This article is exclusive for Imonggo trusted partners.

Partner Account API allows partners to direct create and manage accounts via API. Partners can also directly create or delete branches, switch account from free, to trial, to premium.

API URL:

https://api.imonggo.com/api/partner/accounts

API Functions Supported

SN API Function Description
1 create create a new account (POST)
2 delete delete an account (DELETE)
3 show retrieve account information (GET)
6 subscribe_trial upgrade account to trial (PUT)
7 subscribe_premium subscribe account and all branches to premium membership (PUT)
8 unsubscribe_premium cancel premium subscription (PUT)
9 show_subscriptions retrieve list of subscriptions under an account (GET)
10 show_branches retrieve list a branches under an account (GET)
11 create_branch create a new branch, an associated subscription will be added (PUT)
12 delete_branch delete a branch and its associated subscription (PUT)
13 create_user create a new user
14 update_user update a user
15 delete_user delete an existing user
16 show_users shows a list of users under this account
17 show_user_api_token show user api token

Terms and Definitions

  • Account - an account can have multiple branches and multiple subscriptions
  • Branch - a retail branch where sales can be recorded and inventories tracked
  • Subscription - premium subscription, each premium branch will have a corresponding subscription
  • Free Account - Imonggo free account has limitation of 1 user, 1 branch, as well other feature limitations
  • Trial Account - Imonggo trial account has all the functions and features of premium account, but only supports up to 1000 products
  • Premium Account - Imonggo premium account can have multiple users, multiple branches and has the full feature and functions

Statuses

  • A - Active
  • I - Inactive
  • D - Deleted

This flag can be applicable to account, branch and subscription.

Subscription Type

  • 0 - Free
  • 1 - Trial
  • 2 - Premium

Return Codes

  • 200 OK - if successful
  • 404 Not found - if no account matches the id
  • 422 Un-processable Entity - if validation error occurred
  • 500 Internal Server Error - if unexpected error occurred

Create (POST)

Create a new account.

Required Fields:

  • name - account name - a-z, 0-9 only, 5 to 30 characters
  • email - email valid email, must not own any existing imonggo account
  • user_name - account owner name
  • user_password - account owner password

Optional Fields

  • street
  • city
  • zipcode
  • state
  • country
  • telephone

The country codes and US states can be found here.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts.xml" \
-X POST \
-d "<account><name>test119</name><user_name>John Smity</user_name><user_password>12345</user_password><email>john@smith.com</email></account>"

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <city nil="true"></city>
  <country nil="true"></country>
  <email>john@smith.com</email>
  <id>1051</id>
  <name>test119</name>
  <state nil="true"></state>
  <street nil="true"></street>
  <subscription_type>0</subscription_type>
  <telephone nil="true"></telephone>
  <user_name>John Smity</user_name>
  <zipcode>NA</zipcode>
  <utc_created_at nil="true"></utc_created_at>
  <utc_updated_at nil="true"></utc_updated_at>
</account>

You should take note of the account id.

Show (GET)

Returns information about an account.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1051.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <city nil="true"></city>
  <country nil="true"></country>
  <email>john@smith.com</email>
  <id>1051</id>
  <name>test119</name>
  <state nil="true"></state>
  <street nil="true"></street>
  <subscription_type>0</subscription_type>
  <telephone nil="true"></telephone>
  <user_name>John Smity</user_name>
  <zipcode>NA</zipcode>
  <utc_created_at>2013-07-28T23:11:25Z</utc_created_at>
  <utc_updated_at>2013-07-28T23:11:25Z</utc_updated_at>
</account>

Subscribe Trial (PUT)

Upgrade an existing free account to trial. After account is upgraded, you can create additional branches.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/subscribe_trial.xml" \
-X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <city nil="true"></city>
  <country nil="true"></country>
  <email>john@smith.com</email>
  <id>1053</id>
  <name>test119</name>
  <state nil="true"></state>
  <street nil="true"></street>
  <subscription_type>1</subscription_type>
  <telephone nil="true"></telephone>
  <user_name>John Smity</user_name>
  <zipcode>NA</zipcode>
  <utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
  <utc_updated_at>2013-07-28T23:35:38Z</utc_updated_at>
</account>

*Note: notice the resulting subscription_type is now 1.

Reset Trial (PUT)

Trial status will only be active for 30 day; then the account will automatically be downgraded to free account if not upgraded to premium. Second trial will not be allowed unless you reset the internal trial flag. Reset trial allows you to reset the internal trial flag to allow another trial.

During the trial period, the users can create any number of branches.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/reset_trial.xml" \
-X PUT

Subscribe Premium (PUT)

Subscribe an existing free or trial account to premium membership.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/subscribe_premium.xml" \
-X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <city>ZZ</city>
  <country nil="true"></country>
  <email>john@smith.com</email>
  <id>1053</id>
  <name>test119</name>
  <state nil="true"></state>
  <street nil="true"></street>
  <subscription_type>2</subscription_type>
  <telephone nil="true"></telephone>
  <user_name>John Smity</user_name>
  <zipcode>NA</zipcode>
  <utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
  <utc_updated_at>2013-07-30T00:11:17Z</utc_updated_at>
</account>

Note: Notice subscription_type should be changed to 2 (Premium Account).

Show Subscriptions (GET)

Returns a list of subscriptions, active or in-active. A subscription becomes in-active when its associated branch is deleted.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/show_subscriptions.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account-subscriptions type="array">
  <account_subscription>
    <amount>30.0</amount>
    <branch_id>1138</branch_id>
    <reference></reference>
    <status>A</status>
    <utc_created_at>2013-07-30T00:14:33Z</utc_created_at>
    <utc_updated_at>2013-07-30T00:14:33Z</utc_updated_at>
    <utc_subscribed_at>2013-07-30T00:14:33Z</utc_subscribed_at>
    <utc_canceled_at nil="true"></utc_canceled_at>
  </account_subscription>
</account-subscriptions>

Notice that the subscription status should now be "I" - indicating in-active.

Unsubscribe Premium (PUT)

Unsubscribe a premium account. The account will be converted to free account. Since free account only support single branch, all branches except owner's home branch will be deleted.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/unsubscribe_premium.xml" \
-X PUT

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <city>ZZ</city>
  <country nil="true"></country>
  <email>john@smith.com</email>
  <id>1053</id>
  <name>test119</name>
  <state nil="true"></state>
  <street nil="true"></street>
  <subscription_type>0</subscription_type>
  <telephone nil="true"></telephone>
  <user_name>John Smity</user_name>
  <zipcode>NA</zipcode>
  <utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
  <utc_updated_at>2013-07-30T00:12:38Z</utc_updated_at>
</account>

Note: Notice subscription_type should be changed back to 0 (FREE account).

Create Branch (PUT)

Create a new branch.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/create_branch.xml" \
-X PUT \
-d "<branch><name>San Francisco 1</name><zipcode>1234</zipcode></branch>"
  • Required fields: name - branch name
  • Optional Fields: street, city, zipcode, country, state, telephone, tin

Show Branches (GET)

Returns a list of branches, including deleted branches.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/show_branches.xml"

Return XML:

<?xml version="1.0" encoding="UTF-8"?>
<branches type="array">
  <branch>
    <city nil="true"></city>
    <country nil="true"></country>
    <id>1138</id>
    <name>Branch 1</name>
    <site_type nil="true"></site_type>
    <state nil="true"></state>
    <street nil="true"></street>
    <subscribed_at nil="true"></subscribed_at>
    <subscription_type>0</subscription_type>
    <tin nil="true"></tin>
    <zipcode nil="true"></zipcode>
    <utc_created_at>2013-07-28T23:29:12Z</utc_created_at>
    <utc_updated_at>2013-07-28T23:29:12Z</utc_updated_at>
  </branch>
</branches>

Delete Branch (PUT)

Delete a branch and cancel the associated subscription. Deleting branch is only possible if the account is in premium or trial membership mode.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/delete_branch.xml" \
-X PUT \
-d "<branch><id>1138</id></branch>"

Delete (DELETE)

Delete an account together with the associated branches and subscriptions. After deletion, the account status will be changed to 'D' and all the associated data will be deleted. Subscriptions will also be terminated (marked as 'I').

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053.xml" \
-X DELETE

WARNING!!!

This action will delete all the data associated with the account. This action is not REVERSIBLE.

Create User (PUT)

Create a new user. When an account is created, a default user is created automatically. Additional users can be created if the account is on trial or premium subscription.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/create_user.xml" \
-X PUT \
-d "<user><name>john01</name><password>12345</password><email>john01@imonggo2.com</email></user>"
  • Required fields: name, email, password
  • Optional Fields: role_id, home_branch_id, if not specified the default role is owner, default home branch is the same as owner's home branch.

Roles

  • 1 - Cashier
  • 2 - Supervisor
  • 3 - Manager
  • 4 - Owner

Show User API Token (GET)

Displays user API token. This token can be used to perform API login.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/show_user_api_token.xml?user_id=1282"

Update User (PUT)

Updates the user.

Example:

Change user email to john.smith@smith.com and role to cashier.

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/udpate_user.xml" \
-X PUT \
-d "<user><id>1282</id><email>john.smith@smith.com</email><role_id>1</role_id></user>"

Delete User (PUT)

Deletes an user given the user id.

Example:

Delete user with id of 1282.

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/delete_use.xml" \
-X PUT \
-d "<user><id>1282</id></user>"

Show Users (GET)

Display list of all users under the account.

Example:

curl -u partner_user_id:partner_key \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://api.myimonggo.com/api/partner/accounts/1053/show_users.xml"