Order API

This Document is a Draft. The feature here is implemented in Imonggo Enterprise Edition

Order API allows you to retrieve the list of invoices or individual invoice. You can create or void an exiting invoice. Orders cannot be updated; it can only be voided or canceled. Once canceled, it cannot be undone.

It is important to note the Order 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 Order Field Table Order Field Table for the meaning of individual field.

LIST (GET /orders.xml)

Example 1: Listing of orders

Retrieve list of invoices (only page 1 (first 50) of the orders 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/orders.xml"

Sample Result:

<?xml version="1.0" encoding="UTF-8"?>
<orders type="array">
  <order>
    ...
  </order>
  <order>
    ....
  </order>
  ...
</orders>

Sample result (if contents is empty):

<orders/>

Return Codes:

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

Retrieve information on single order. Replace {id} with the order id. Please refer this page for return field information and meaning. Note that order no is different from order id. Order no is sequential number generated within each branch while invoice id is unique number assign to the invoice within your account. Order no is visible to regular user while order 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/orders/123456.xml"

Return Codes:

CREATE: (POST /orders.xml)

Create a new order. The minimum required format. Please refer to this Order Field Table Order Field Table for the supported fields.

Example 1:

Create an a simple order with one item with retail of price 100 and no discount. Note the invoice date is specified in UTC format.

curl -u 428d2622b1e717236418762c0c676def22d947dc:X \
-H "Accept: application/xml" \
-H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/orders.xml" \
-X POST \
-d @input.txt

<order>
  <remark>Sample order with units</remark>
  <target_delivery_date>2014-05-01</target_delivery_date>
  <order_lines type="array">
    <order_line>
      <product_id>54018</product_id>
      <quantity>20</quantity>
    </order_line>
  </order_lines>
</order>

Example 2:

Create an simple order, the 2nd order line contains unit information including unit-id, unit-name, unit-quantity, and unit-retail-price.

<order>
  <remark>Hello mark</remark>
  <order_lines type="array">
    <order_line>
      <product_id>11716</product_id>
      <quantity>9</quantity>
    </order_line>
    <order_line>
      <product_id>12806</product_id>
      <quantity>120</quantity>
      <unit_id>10</unit_id>
      <unit_name>CASE</unit_name>   
      <unit_quantity>10</unit_quantity> 
      <unit_content_quantity>12</unit_content_quantity>
      <unit_retail_price>1200</unit_retail_price>       
    </order_line>
  </order_lines>
</order>

CANCEL OR VOID: (DELETE /orders/{id}.xml)

Use this command to cancel or void. When a order is already deleted, server will return 422 error. and return 404 (Not found) if there is no matching order id.

You are require to specify a reason for cancelation.

Example 1:

Delete order identified with id 12345.

curl -u 4acc660ce98b9d38d7fea10705aa1ebd7d836fe0:X \
-H "Accept: application/xml" -H "Content-Type: application/xml" \
"https://test_account.imonggo.com/api/orders/12345.xml?reason=wrong%order" \
-X DELETE

Return Codes: