Overview #

In addition to exporting orders on a pull (HTTP GET to our server) using a JSON format, orders can be pushed (HTTP POST from our server) to your server immediately as they are submitted.

Order submission and export #

If JSON order export is configured, the flow is:

• iPad submits order to server
• Server POSTs order to configured endpoint using HTTP Basic authentication (if user/password are provided) in our standard JSON export format
• If the endpoint responds with 200 OK, the order is marked exported

Error retries

• If the endpoint responds with something other than 200 OK the server will immediately retry the export.
• After 3 failed attempts, the server notifies of an error

POST details

The POST contains the following information:

• The request header Content-Type: application/json
• The request header Content-Length matches the length of the request body
• The request body contains the JSON version of the order

The contents of the JSON version of the order are listed here: JSON Order Fields

You can test the flow with sample data by doing the following:

• Download sample JSON orders (see 'Tips & Tricks' below)
• Run the following curl command: curl -u <user>:<password> --data-binary @order.json -H "Content-Type: application/json" <your URL>

Recommendations

• Provide your endpoint over HTTPS. (HTTP is too insecure.)

Error notifications

The order export system will send emails to the configured error email recipients. The email will contain the order number and a link to view the order.

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 'Push' API will send a separate submission for each resubmitted order. 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 with various options 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-3 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', the URL should be https://supercat.supercatsolutions.com/demo/ext/v2/117159.json.