Batch API/“Pull” based order export specifications #

Overview

You can export recently submitted orders to your own system by downloading them regularly. The flow is:

1. Download recently submitted orders using the API described below in "Downloading Orders"
2. Process the orders as you need to
3. Mark the orders processed so you don’t have to download them again using the API described below in “Marking Orders Received”

We call this a “Pull” based order export because your system “pulls” the orders from our server.

We have another way to export orders which we call “push” based, which is described here: JSON Order Export - Push

Downloading Orders

A standard API can be used to retrieve Cat orders in batches as follows.

Make an HTTP GET request (with admin level username/password) to the following URL (where <org> is the shortname of your organization, same as in all the admin portal URLs).

https://username:password@supercat.supercatsolutions.com/<org>/ext/v2/orders/new_orders

Please keep in mind that the above URL has the username and password built into it. However, some tools, such as Java's HttpURLConnection, do not support this kind of URL, and you will need to perform HTTP Basic authentication manually using your username and password.

No query parameters are necessary in the request since we simply send all orders that have not been flagged as ‘received’.

Note: This URL is the same URL you will use to POST the received order numbers later in the process.

The response will contain a success message and a single JSON array of orders.

A normal success response is:

{
 "status":"success",
 "error":null, //error will have an error message in the case of error
 "data" : [ { <order 1> }, { <order 2> }, ... ]
}

1. Every response will always contain 3 fields: status, error, data
2. If the status is "success", the data field will contain zero or more orders
3. If the status is not "success", the error field will contain a message4) status="error" does not need to be treated differently from status="failure" if you don't want to. You can simply examine the error field whenever status is not "success"

Each order in the array will be a JSON object corresponding to the JSON order format. As a simple example, the JSON returned will look as follows:

[ { "order_number" : "XYZ-123", ... }, { "order_number" : "XYZ-124", ... }, ... ]

A list of all fields that could potentially be included in an order is documented below.

Marking Orders Received

After the orders are received, make an HTTP POST request to send a JSON array of order numbers that were successfully received. Use the same URL you used above.

The orders will then be marked as having been successfully sent to avoid sending them again on a subsequent request. For example:

[ "XYZ-123", "XYZ-124", ... ]

Note that ALL orders that have not been flagged as retrieved will be sent. This includes any orders that have been submitted by a rep multiple times. These orders will have the usual dash number suffix appended to the order number to indicate they are a version of a previously sent order. Create a process to check for and handle duplicates on your end.

A normal success response is:

{
 "status": "success",
 "error": null, //error will have an error message in the case of error
 "data": {
 "<order number>": {
 "success": true
 }
 }
}

There will be an entry for each order number marked as received.

If any of the orders have an error associated with marking them received, the entry will look like:

 "<order number>": {
 "success": false,
 "error": "an error message"
 }

Order Fields

The fields in the JSON order rendering are listed here: JSON Order Fields

Inbound order processing - testing for duplicate orders #

When an order is submitted from eCat multiple times, a 'dash number' suffix is appended to the original order number. The first resubmitted order number receives a '-1' suffix. If the order were submitted again, a '-2' suffix would be appended.

The JSON order record contains other information that can be used to test for order uniqueness. Following is an example of an order submitted twice.

*Original order record:*
"order_number":"6385-031318-392" (Shown in admin portal order list.)
"uuid":"631F4C43-361B-4385-A1EC-7D214B5B4EBE"
"id":356509" (Shown in admin portal order list.)

*Revised order record:*
"order_number":"6385-031318-392-1" (Shown in admin portal order list.)
"uuid":"631F4C43-361B-4385-A1EC-7D214B5B4EBE"
"id":378430" (Shown in admin portal order list.)

The UUID values for the two versions of the order are the same, but the values for "order_number" and "id" are different. "id" values are assigned sequentially. So, if two or more orders have the same UUID, they are records for the same order that was submitted multiple times and the version with the highest numerical value for "id" is the most recent.

Just as a heads-up, we've seen cases where users delete the items from a submitted order then add items and re-submit it as a new order. (This is in spite of the fact that eCat displays an 'already submitted' warning when they submit the order.) The new order has the same number as the previous order other than the dash suffix, but should actually be processed as a new order. So it's good practice for order entry people to review any orders with a dash suffix and ask questions before processing. (And to train users how to start a new order!)

Tips & Tricks #

• Here’s a way to download single eCat orders in the correct JSON format for import testing purposes. This enables you to create test orders as needed to test the import process thoroughly.
  • Edit an order in the admin portal and note the order ID in the URL (this is a 6-7 digit number)
  • Add the order number to the URL:

    https://supercat.supercatsolutions.com/<org id>/ext/v2/orders/<order id>.json 

    where org ID is your 2-9 character eCat company abbreviation and order ID is the order number. You must sign in with your eCat admin credentials to view the order. For example, if the order ID is 117159, and the org ID is 'demo', then the URL should be

    https://supercat.supercatsolutions.com/demo/ext/v2/orders/117159.json