Supplier API

Suppliers API allows you to retrieve the list of suppliers or individual supplier. You can create, update or delete an existing supplier. Please refer to Supplier Fields table for meaning and usage of individual field.

LIST (GET /suppliers.xml)

Retrieve list of active suppliers, both active and deleted are included. To exclude deleted suppliers, use active_only parameter. Each call returns only 1 page worth of records. The default and maximum page size is 50.

Example 1: Listing of Suppliers

Retrieve list of suppliers. Only page 1 or first 50 records will be returned. You can use page parameter to return more pages.

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

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<suppliers type="array">
  <supplier>
    ...
  </supplier>
  <supplier>
    ....
  </supplier>
  ...
</suppliers>

Sample result (when empty): 
<suppliers/>

Example 2: Listing with page and per_page parameter

To retrieve page 1 of suppliers with default page size of 50.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?page=1"

To retrieve page 2 of the suppliers list:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?page=2"

Example 3: Listing of Active Suppliers Only

This parameter is useful when you are retrieving a complete set of active suppliers only. If you are retrieving the updated supplier list, it is important to include the delete suppliers so that you know when to delete local version of the suppliers.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?active_only=1"

Return Codes:

  • 200 OK - if successful

GET (GET /suppliers/{id}.xml)

Retrieve information on single supplier. Replace {id} with the supplier id.

Example 1:

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers/53.xml"

Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<supplier>
    <city nil="true"></city>
    <code>2434HI</code>
    <contact_person>Jarret Pires</contact_person>
    <contact_position nil="true"></contact_position>
    <contact_title>Mr</contact_title>
    <country nil="true"></country>
    <discount_text nil="true"></discount_text>
    <email>jpiresc@home.pl</email>
    <fax nil="true"></fax>
    <id>22259</id>
    <mobile nil="true"></mobile>
    <name>Zoombeat</name>
    <remark>deploy clicks-and-mortar e-commerce</remark>
    <state nil="true"></state>
    <street>7 Thompson Road</street>
    <tax_exempt nil="true"></tax_exempt>
    <telephone nil="true"></telephone>
    <zipcode nil="true"></zipcode>
</supplier>

Return Codes:

  • 200 OK - if successful
  • 404 Not found - if no supplier matches the id

CREATE (POST /suppliers.xml)

Create a new supplier. The minimum required fields are name, stock_no and retail_price.

Example 1:

Create an item name of "Nokia" with stock_no of "E71" and retail_price of $200.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml" \
-X POST \
-d "<supplier><name>Merit Inc.</name><contact_person>James Hower</contact_person></supplier>" 

Sample result (when succcessful):
<?xml version="1.0" encoding="UTF-8"?>
<hash>
    <id type="integer">23248</id>
</hash>

Return Codes:

  • 200 OK - if successful
  • 422 Un-processable Entity - if validation error occurred
  • 500 Internal Server Error - if unexpected error occurred

UPDATE (PUT /supplier/{id}.xml)

Example 1:

Change the supplier cost to 199 and retail price to 299.95. The supplier is identified with id of 53.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers/53.xml" \
-X PUT \
-d "<supplier><name>Median Enterprise</name></supplier>"

Return Codes:

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

DELETE (DELETE /supplier/{id}.xml)

Use this command to mark a supplier as deleted.

Example 1:

Delete supplier identified with id 59.

curl -I -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers/599.xml" \
-X DELETE

Return Codes:

  • 200 OK - if successful
  • 404 Not found - if no supplier matches the id

Parameters for LIST (GET /suppliers.xml)

Page Filters

Page filters are used in LIST to limit the suppliers to be retrieved. You can combined page filter with date Filters (before, after, from and to).

  • page: default of 1 (eg. page=1)
  • per_page: any number between 1 to 50 (e.g. per_page=10)

Date Filters

Date filtered are used in LIST to limit the suppliers to be retrieved. Date format must be given in UTC date/time format ("YYYY-MM-DDTHH:MM:SSZ").

  • before: updated date < given date
  • after: updated date > given date
  • from: updated date >= give date
  • to: updated date <= give date

Status Filter

  • active_only: when setup to 1 to true, the list will exclude deleted suppliers

Inquiry

  • q=count - returns a number of suppliers
  • q=last_updated_at - returns the last updated date for your supplier database

More Examples

Example 1: Counting Suppliers

To count on the total number of active suppliers

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?q=count"

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">7</count>
</hash>

To count on the total number of active suppliers updated after Jan 1, 2011.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?q=count&after=2011-01-01T00:00:00Z"

Example 2: Limiting Suppliers Listing with Last updated date

To inquire on the total number of suppliers updated after April 1, 2011

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?q=count&after=2011-04-1T00:00:00Z"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <count type="integer">1</count>
</hash>

Retrieve list of suppliers updated after Dec 31, 2010.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?after=2010-12-31T23:59:00Z"

Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<suppliers type="array">
  <supplier>
    ...
  </supplier>
  <supplier>
    ....
  </supplier>
  ...
</suppliers>

Example 3: Last Updated At

To inquire on the last updated date, use q=last_updated_at

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/suppliers.xml?q=last_updated_at"

Sample Result: 
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <last-updated-at>2011-04-13 04:37:45</last-updated-at>
</hash>

Additional Notes for Developers

  1. When a supplier is deleted, the status will be "D"
  2. Listing returns both active and deleted suppliers.
  3. In case the XML is malformed, the server will return 500 (Internal server error)

Proposed Algorithm for synchronizing supplier incrementally

  1. Keep a local persistent variable: previous_last_updated_date (which is initially nil)
  2. GET last_updated_date from server
  3. GET suppliers after previous_last_updated_date to last_updated_date
  4. Start with page 1 until suppliers return contains an empty array
  5. Override local variable pervious_last_updated_date with last_updated_date

Note: When suppliers downloaded contains status D, you should delete the local copy of the supplier if present.