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
CODE/STATUS | CONDITION |
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:
CODE/STATUS | CONDITION |
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:
CODE/STATUS | CONDITION |
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:
CODE/STATUS | CONDITION |
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:
CODE/STATUS | CONDITION |
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
When a supplier is deleted, the status will be "D"
Listing returns both active and deleted suppliers.
In case the XML is malformed, the server will return 500 (Internal server error)
Proposed Algorithm for synchronizing supplier incrementally
Keep a local persistent variable: previous_last_updated_date (which is initially nil)
GET last_updated_date from server
GET suppliers after previous_last_updated_date to last_updated_date
Start with page 1 until suppliers return contains an empty array
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.