Document API
You can use document API to change the inventory quantity of the Stockroom. Each Stockroom transaction is represented as a document. Document API allows you to retrieve a list of documents or an individual document.
It is important to note that the document API always operates within the context of a specific branch. In case of single branch setup, there is no need to pass the branch id parameter; however, in multi-branch setting, you need to indicate which branch by passing the branch_id. Valid branches are active branches that are not head office.
Please refer Document Field Table for the meaning of individual field.
Here's a quick example how you can update inventory quantity of item with product id 48756.
Example:
A simple physical count document to change the quantity of an item.
curl -u 428d2622b1e717236418762c0c676def22d947dc:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml" \
-X POST \
-d @input.txt
Contents of input.txt
<document>
<document_type_code>physical_count</document_type_code>
<document_lines type="array">
<document_line><product_id>48756</product_id><quantity>10</quantity></document_line>
</document_lines>
</document>
LIST (GET /documents.xml)
Example 1: Listing of documents
Retrieve list of documents (only page 1 or first 50 items 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/documents.xml"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<documents type="array">
<document>
...
</document>
<document>
....
</document>
...
</documents>
Sample result (if contents is empty):
<documents/>
Example 2: Listing with page and per_page parameter
To retrieve page 1 of documents 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/documents.xml?page=1"
To retrieve page 2 of the document list:
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml?page=2"
To retrieve page 1 of the documents list with page size of 50
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml?page=1&per_page=50"
Return Codes:
Code/Status | Condition |
---|---|
200 OK | if successful |
GET (GET /documents/{id}.xml)
Retrieve information on single document. Replace {id} with the document id. Please refer to this page for return field information and meaning.
Note that document no is different from document id. document no is sequential number generated within each branch while document id is unique number assign to the document within your account. Document no is visible to regular user while document id is only visible to the API and programmers.
Example 1:
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents/179.xml"
Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<document>
<id>179995</id>
<reference/>
<remark/>
<status>S</status>
<user_id>48</user_id>
<document_type_code>receive_supplier</document_type_code>
<document_lines type="array">
<document_line>
<discount_text>0.0%</discount_text>
<line_no nil="true"/>
<price>100.0</price>
<product_id>854193</product_id>
<quantity>100.0</quantity>
<retail_price>100.0</retail_price>
<subtotal>10000.0</subtotal>
<product_name>Rock Game</product_name>
<product_stock_no>C2</product_stock_no>
</document_line>
</document_lines>
</document>
Return Codes:
Code/Status | Condition |
---|---|
200 OK | if successful |
404 Not found | if no document matches the id |
CREATE: (POST /documents.xml)
Currently, the document API only supports creation of Physical count document. Other types of documents are not yet supported.
Example:
A simple physical count document to change the quantity of an item.
curl -u 428d2622b1e717236418762c0c676def22d947dc:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml" \
-X POST \
-d @input.txt
Contents of input.txt
<document>
<document_type_code>physical_count</document_type_code>
<document_lines type="array">
<document_line><product_id>48756</product_id><quantity>10</quantity></document_line>
</document_lines>
</document>
Sample result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<id type="integer">912312</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 |
CANCEL OR VOID: (DELETE /documents/{id}.xml)
Cancel of voiding of document is not yet supported.
OTHER FEATURES (GET /documents.xml)
Example 1: Counting documents
To count on the total number of documents
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml?q=count"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<count type="integer">123</count>
</hash>
Example 2: Limiting Documents Listing with Last updated date
To inquire on the total number of documents updated from Sept 1, 2012 to present.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml?q=count&from=2012-9-1"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<hash>
<count type="integer">5</count>
</hash>
Retrieve list of documents updated after Dec 31, 2010.
curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/documents.xml?after=2010-12-31%2023:59"
Sample Result:
<?xml version="1.0" encoding="UTF-8"?>
<documents type="array">
<document>
...
</document>
<document>
....
</document>
...
</documents>
Note that we escaped space with %20 in "after=2010-12-31%2023:59".
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/documents.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>
Parameters for LIST (GET /documents.xml)
Page Filters
Page filters are used in LIST to limit the documents 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 100 (e.g. per_page=10)
Date Filters
Date filtered are used in LIST to limit the documents to be retrieved. Given date format is in "YYYY-MM-DD HH:MM:SS" specified in UTC time. Invalid date format will cause internal server error (status code: 500).
- before: updated date < given date
- after: updated date > given date
- from: updated date >= give date
- to: updated date <= give date
Inquiry
- q=count - returns a number of documents
- q=last_updated_at - returns the last updated date of your last posted or cancelled document
Additional Notes for Developers
- When a document is deleted, the status will be "D"
- Listing returns both active and deleted documents.
- In case the XML is not corrected formatted, the server will return 500 (Internal server error)
- Last updated at can be different from document date