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"

Example 3: Get Incoming Transfer

To view incoming transfers, set param incoming = 2 and branch_id of target branch

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/documents.xml?incoming=1&branch_id=40525

Example 4: Filter by Document Type

To filter list of documents by document type supply the document_type_id as document_type param.

DOCUMENT TYPE	ID
Receive From Supplier	1
Return to Supplier	2
Transfer In	3
Transfer Out	4
Adjustment In	5
Adjustment Out	6
Physical count	7

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

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>

Example 2: Receive Incoming Transfer

To receive incoming transfer, append receive_incoming

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \ 
-H "Accept: application/xml" -H "Content-Type: application/xml" \ "https://test_account.imonggo.com/api/documents/51/receive_incoming.xml?branch_id=67

Return Codes:

CODE/STATUS	CONDITION
200 OK	if successful
404 Not found	if no document matches the id

CREATE: (POST /documents.xml)

Example 1: Physical Count

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>

Example 2: Receive from Supplier

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>receive_supplier</document_type_code> 
 <remark>from api request</remark>
 <party_name>Supplier Inc.</party_name>
 <document_lines type="array"> 
  <document_line><product_id>48756</product_id>
  <quantity>10</quantity>
  <retail_price>100.0</retail_price>
  <discount_text>20.0%</discount_text>
  <price>80</price>
  </document_line> 
 </document_lines> 
</document>

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