The custom Web store integration points hook shiprush Web to your site, store or app.
Terms
Developer: That is you, the developer who is consuming the ShipRush Web Non-Visual API in a Web or desktop application.
"Your Application": This is the app you (the developer reading this) are responsible for. This API supports both desktop and browser applications.
Client Application or Client App: The same as above.
Customer or User: This is your customer or user. AKA "end user".
HTTP REST: This is a standard way of presenting an API on the Internet. RFC's, details, etc are discussed in many places on the Internet, including wikipedia http://en.wikipedia.org/wiki/Representational_State_Transfer
-
Fiddler: This is a free tool that is very useful for working with and understanding a REST API. It is available at http://www.fiddler2.com/fiddler2/ (Windows)
Alternate tool: HTTP Analyzer (Windows)
Alternative tool: curl (cross platform)
Date Time format: My.ShipRush uses the ISO 8601 Date/Time Format http://en.wikipedia.org/wiki/ISO_8601
Custom Web stores
Developers and users who have custom (or heavily customized) systems can interact with ShipRush two ways:
"Push" based "Custom Post In" method
"Polling" based Custom Web Store method
Both methods expect you to format data in XML. The format of the shipment XML follows the standard ShipRush "core" format. This is the same format used in ShipRush zpk files and the ShipRush SDK. Details can be found in:
Using the ShipRush UI to save zpk templates
The ShipRush Browser Plugin documentation (aka "Clicky," in ShipRush_Developer_Clicky.chm)
-
Shipment XSD (ShipRushShipment_Redist.xsd)
The XSD also has constants and enums for the various shipping carriers, packaging types, service options, etc.
ShipRush.SDK.DesktopDemo demo application that can post sample order to PostIn URL
My.ShipRush PHP Web store integration (including sample Custom Integration) http://my.shiprush.com/assets/ShipRush_ShoppingCart_Integration_Kit__See_README_file.zip
Reference to the documentation is needed when passing order line items and detailed shipping information (such as shipping service). For super-high level automation, the minimum elements can be sent. See below for detail.
Push / Custom-Post-In Diagram
Custom Web Store - Polling Architecture Chart
Custom-Post-In: Setup & API
Web store type: postin
In ShipRush, when adding a Web store, choose Custom Post In as shown below.
With Post-In API you/your developer pushes orders into My.ShipRush via HTTP POST. During Custom Post-In Web store set up (the screens that come later in the wizard shown above) you are given a unique URL to this effect:
https://api.my.shiprush.com/IntegrationService.svc/XXqoomtXOU28wJyUAPgFig/UtCQqjsGeU6l##########/order/addThis URL is your username, password and a place to post new sales to My.ShipRush. For each new sale on your site your code would HTTP POST a ShipRush-compatible XML to this URL.
This URL is a password. Store it in encrypted storage. It should not be displayed in clear in your application. In your logging system, it should be masked so as not to expose these elements.
So What Do You Post There?
See below for example order XML.
Once an Order Is in Descartes ShipRush, How to Update It?
If the order is cancelled / deleted / changed on your system, and you wish to update ShipRush, simply post it into ShipRush again, with a different status.
Order Status Explanation (Shipped, Unshipped, Paid, Cancelled)
Shipped/Unshipped/Cancelled
In the case of a My.ShipRush consuming developer, focus on the Order and ignore the information below RE shipment.
Order Based
For "payload" which has BOTH Shipment and Order the information about shipping status will be duplicated in 2 places
To put an order in the Ready to Ship folder: Set: Shipment.ShipmentType == Pending AND Order.IsShipped == FALSETo put an order in the Shipped folder: Set: Shipment.ShipmentType == History AND Order.IsShipped == TRUE
Shipment Based
A Shipment can be Shipped or Unshipped.
We suggest to always send: Shipment.ShipmentType == Pending
As this will put orders in the Ready to Ship folder.
Shipped (the Shipped folder): Shipment.ShipmentType == History
Unshipped (Ready to Ship folder): Shipment.ShipmentType == Pending
Paid Status
Payment status only applies to the Order. Shipment has no concept of "payment". Information about payment status always comes via Order.IsPaid
When sending orders to ShipRush, there are two ways to handle data that is not paid:
Ignore it: Do not send to ShipRush orders that are not paid.
Flag it: Send unpaid orders to ShipRush, which will now appear in the Unpaid area.
Recommended: Only send orders to ShipRush that are paid and "ship able"
Deleted/Cancelled Statuses
These are different for Shipment and Order. We suggest to focus on the Order and ignore the information below RE shipment.
Since "Deleted" and "Cancelled" represent different concepts - it is possible to have combination of Order/Shipment where Cancelled and Deleted do not match.
Cancelled Flag
The Cancelled flag always comes from you by updating the order (there is no way to modify it in My.ShipRush) and is controlled via the Order.IsCancelled field.
To update an order in ShipRush, post in with: Order.IsCancelled == True
When the shipper refreshes the list of shipments, the shipment will move to the Cancelled folder.
Deleted Flag
The "Deleted" flag applies to the Shipment. It indicates that the user of ShipRush deleted a shipping label that he already printed. The Deleted flag is available via Shipment.ShipmentStatus == Deleted.
Tagging Shipments
Shipments coming into ShipRush can be tagged by using the "Tags" element of the TShipment payload
Tags should be comma or space-separated.
The total length of all tags should not exceed 100 characters. If it does they are truncated at 100.
Tags in Action
The shipment grid can be filtered by tag. This shows the tags visually:
Geting Tracking Numbers from My.Shiprush to Your System
There are two way you can get tracking number from My.ShipRush to your system.
-
Subscribe to shipping notifications by providing a notification URL (on your server) via Shipment.PostbackUrl
This is simple and automatic. When you push the order into ShipRush, include an URL (in the Shipment.PostbackUrl element) and ShipRush will push ShipRush xml to that URL when there is a tracking number to report.
-
Advanced, harder way: My.ShipRush Ecommerce Gateway (aka the My.ShipRush API): This lets you poll for tracking numbers. (Push notifications can also be configured.) However this is a different code path and requires significant additional development by you.
NOTE: This requires full use of the My.ShipRush API, which is significant additional effort. (However it does give more global control.)
Sending in a PostBackURL
My.ShipRush will do an HTTP post to the provided URL with the full Shipment/Order data (with <Request> as root XML element - same format you used for posting data to My.ShipRush). We recommend using online HTTP-post catching service like http://requestb.in/ for testing PostbackUrl functionality.
My.ShipRush API users: ShipRush.Test.GUI SDK demo shows how to add a shipment with a PostbackUrl (under "Shipments and orders" tab)
Note: For shipments processed with Web Shipping there will be at least 2 notifications coming to PostbackUrl. One is instant and another one in a few seconds. If your server is down My.ShipRush will keep retrying for 2 days every few hours. For shipments processed in ShipRush desktop there will be at least 1 notification a few seconds after operation completed. (For shipments marked via UpdateShipment REST API in the My.ShipRush API, the post out is within a few seconds of the shipment.)
The max length for a postbackurl is 55 characters.
Make sure to pad PostbackUrl with some kind of authentication token to prevent someone else posting invalid data to your system. We strongly suggest that this be a dynamic, changing token. NOT a global token.
Good Example: hash order # + dynamic password (for example, each 10 day window of time generates a new pw)
Weak Example: hash the Order # + salt: (problem: The salt is constant across all orders, hack once, hack all)
order 234234234: https://my.systemsite.com/updateorder/ABDD003BDDD1F3DD
order 234234235: https://my.systemsite.com/updateorder/37237DEFFACC8238
Bad Example (please do not emulate!)
order 234234234: https://my.systemsite.com/updateorder/234234234
order 234234235: https://my.systemsite.com/updateorder/234234235
Best Practice: The PostbackUrl, on your system, should expire (e.g., after some number of days (say 7)); it should not allow any input.
<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ShipTransaction>
<Shipment>
<PostbackUrl>http://requestb.in/1aa5uuj1</PostbackUrl>
...
<Package>
<PackageActualWeight>7</PackageActualWeight>
<PackagingType>02</PackagingType>
<PackageReference1>Order # 61-0</PackageReference1>
...
</Package>
<DeliveryAddress>
<Address>
<FirstName>Joe</FirstName>
<LastName>Buyer</LastName>
<Address1>123 Buy It Street</Address1>
<City>Seattle</City>
<State>WA</State>
...
</Address>
</DeliveryAddress>
<ShipperAddress>
<UPSAccountNumber>123555</UPSAccountNumber>
<Address>
<FirstName>Alex</FirstName>
<LastName>Test</LastName>
<Company>ACME</Company>
<Address1>120 Lakeside ave</Address1>
...
</Address>
</ShipperAddress>
</Shipment>
<Order>
<BillingAddress>
<FirstName>Joe Bogus</FirstName>
<Company>Z-Firm LLC</Company>
<Address1>120 lakeside ave</Address1>
...
</BillingAddress>
<ShippingAddress>
<FirstName>Joe Bogus</FirstName>
<Company>Z-Firm LLC</Company>
<Address1>120 lakeside ave</Address1>
...Quick Steps to See PostbackUrl in Action
Using systems like requestb.in exposes you to risk in that any data sent to such an endpoint is public. For example, if you send a live order there, you may be exposing to the public the real name and PII (Personally Identifiable Information) of a customer. If the payload were to include a postback URL or the Custom Post In Url, those URLs contain passwords / security elements that should not be exposed.
Please think it through and use caution.
Create a post in store on the My.ShipRush site.
Go to "http://requestb.in/" and create new capture URL.
Use Fiddler to send in an order with a PostbackUrl set to the capture URL created above.
Ship the order (use a plain "USPS" account in ShipRush to get quick setup for shipping without a credit card of carrier account).
At this point instant HTTP POST notification will go through.
Go to to "http://requestb.in/1aa5uuj1?inspect" (token in your URL will be different) and look at payload.
My.Shiprush API Users: See PostbackURL Notification Working with Interactive and Online Tools Only
Note: No modifications to your server code are required.
Start ShipRush.Tests.GUI.exe (from My.ShipRush SDK package).
Create new user (or grab token for existing user).
Go to "webstores" tab. Create new Web store of type "postin". After browser pops - complete registration (click "next" few times).
Go to "http://requestb.in/" and create new capture URL.
Go back to ShipRush.Tests.GUI to "Shipments and orders" tab, paste capture URL to "Postback Url" field.
Click "Add pending shipments" <- this simulates your Web store posting shipments to My.ShipRush.
Go to My.ShipRush Web Shipping (http://my.shiprush.com).
Go to "Ready To Ship" \ "Custom PostIn Webstore" folder.
Ship one of the pending shipments. At this point instant HTTP POST notification will go through.
Go to to "http://requestb.in/1aa5uuj1?inspect" (token in your URL will be different) and look at payload.
Wait few seconds. At this point second background HTTP POST notification will fire.
Setup Workflow
The user starts in Order Manager (or My.ShipRush), creates a My.ShipRush ID, and creates the Web store. During the Web store creation, the user is given the URL which gets entered on the host system configuration.
For developers with many users, the Web Store Type listed in My.ShipRush can be customized, to name the host system clearly, and offer specific help content to assist with setup. For example, if you publish a system called SuperDuperCart, you can request that this be listed as the store type in the list of store types.
Sample HTTP Post (HTTP Post Headers and Body)
Note that the Content-Type header is required.
Headers
HTTP/1.0
Content-Type: application/xml
Host: api.my.shiprush.com
Content-Length: 1817Order Sample: with Order Details
<?xml version = "1.0"?>
<Request>
<ShipTransaction>
<Order>
<OrderNumber>ZF-0034</OrderNumber>
<Total>199.95</Total>
<PaymentStatus>2</PaymentStatus>
<ShipmentOrderItem>
<Name>iPhone Nano 8GB</Name>
<Price>199.98</Price>
<Quantity>1</Quantity>
</ShipmentOrderItem>
<BillingAddress>
<FirstName>John Stewart</FirstName>
<LastName></LastName>
<Address1>101 Lakeside AVE APT 4703</Address1>
<City>KILLEEN</City>
<State>TX</State>
<PostalCode>76541</PostalCode>
<Country>US</Country>
<Phone>5054144980</Phone>
</BillingAddress>
</Order>
<Shipment>
<UPSServiceType>U02</UPSServiceType>
<ShipmentChgType>PRE</ShipmentChgType>
<PartnerId>Amazon</PartnerId>
<PostbackUrl>http://requestb.in/1aa5uuj1</PostbackUrl>
<Package>
<PackageActualWeight>4</PackageActualWeight>
<PackagingType>02</PackagingType>
<PackageReference1></PackageReference1>
<InsuranceAmount>55</InsuranceAmount>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Stewart</FirstName>
<LastName></LastName>
<Address1>101 Lakeside AVE APT 4703</Address1>
<City>KILLEEN</City>
<State>TX</State>
<PostalCode>76541</PostalCode>
<Country>US</Country>
<Phone>5054144980</Phone>
</Address>
</DeliveryAddress>
</Shipment>
</ShipTransaction>
</Request>Order Sample: The Bare Minimum Order
Just an address. No order information other than an order number.
Suggested minimum elements for <Order>
OrderNumber // to map to your system
PaymentStatus // send 2 (means paid, ready to ship)
ShipmentType // Set to Pending (means not shipped)
OrderDate // Set to appro date, remember to use appro ISO encoding as mentioned above in this document
<?xml version = "1.0"?>
<Request>
<ShipTransaction>
<Order>
<OrderNumber>ZF-0040</OrderNumber>
</Order>
<Shipment>
<Package>
<PackageReference1>Widgets</PackageReference1>
</Package>
<DeliveryAddress>
<Address>
<FirstName>John Stewart</FirstName>
<Address1>101 Lakeside AVE APT 4703</Address1>
<City>KILLEEN</City>
<State>TX</State>
<PostalCode>76541</PostalCode>
<Country>US</Country>
<Phone>5054144980</Phone>
</Address>
</DeliveryAddress>
</Shipment>
</ShipTransaction>
</Request>Error Response
<?xml version="1.0" encoding="utf-8"?>
<Error xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Message>Invalid security token 'a2a87a5d-576b-4d39-bcc0-###########'. Token not found. [0013].</Message>
<Details/>
<CallContextId>caf7d793-7ef0-46b2-a278-###########</CallContextId>
</Error>Polling API
Web store type: custom
With Polling API My.ShipRush will call your Website periodically to see if there are new sales available. Your Website needs to have an entry point for My.ShipRush calls and return ShipRush-friendly XML. My.ShipRush will pass query parameters in the URL parameters and will expect response in the HTTP body.
Z-Firm build several PHP implementations based on this API. ZenCart, Magento, OsCommerce integrations use this API to get orders from these shopping carts. You can use our code as a reference point for implementing your integration. Download latest package from http://my.shiprush.com/assets/ShipRush_ShoppingCart_Integration_Kit__See_README_file.zip
You need to implement following commands. My.ShipRushs expects HTTP 200 for all successful requests and HTTP 500 for all failed requests. Failed requests will be retried in 2-4 hours.
Url Parameters |
Description |
cmd |
Command |
shipping_access_token |
Security token that identifies caller as My.ShipRush. |
datefrom |
Get orders From date in UTC |
dateto |
Get orders To date in UTC |
Getordersbydate
Return all sales that fit date range http://mywebstore.com/MyShipRushEntry.php?cmd=getordersbydate&shipping_access_token=ABCD1234SUPER&datefrom=2000-01-01T01:01:01Z&dateTo=2020-01-01T01:01:01Z
Ping
Check setup and return basic server info as XMLhttp://mywebstore.com/MyShipRushEntry.php?cmd=ping&shipping_access_token=ABCD1234SUPER
<Response>
<Message>Success. Access token database access verified.</Message>
<Version>1.0.0.36236</Version>
</Response>Getserverinfo
Return expanded server info as text blobhttp://mywebstore.com/MyShipRushEntry.php?cmd=getserverinfo&shipping_access_token=ABCD1234SUPER
Updateshippinginfo
Update order in your system with tracking number and name of the shipping service. http://mywebstore.com/MyShipRushEntry.php?cmd=updateshippinginfo&shipping_access_token=ABCD1234SUPER&OrderNumber=ZF999&TrackingNumber=1Z00000000000&Carrier=UPS&Service=UPS+Ground
FAQ
Can You Send Me a Javascript Example for Post out and Post Back?
It is true that you could implement the code to do post out/post in in node.js, and this would be javascript code. However, you cannot interact with ShipRush Web via js in a browser. Why? Because it is a cross-domain-scripting approach, which browsers forbid due to security concerns.
The solution: Go from .js in browser to your site, and from your site (server side code) out to SR.
Then, (obviously) SR is going to post back to a site (not to a browser).
More about cross site scripting (aka XSS):
- https://danielmiessler.com/study/xss/
- http://security.stackexchange.com/q/1368/43858
The needed flow is: