README.md in shipping_easy-0.3.0 vs README.md in shipping_easy-0.3.1
- old
+ new
@@ -1,16 +1,20 @@
[](https://codeclimate.com/repos/5315eeefe30ba01aa501c119/feed)
# ShippingEasy
-This is the official wrapper for the ShippingEasy API. Currently the API only exposes several functions so this wrapper only handles the following calls:
+This is the official wrapper for the ShippingEasy API.
-* Adding an order to a ShippingEasy store
-* Cancelling an order before it has been shipped
+The ShippingEasy API supports the following features:
-We will keep this library up to date as we expand our API offerings.
+* Secure, authenticated intake of orders for shipment
+* Cancellation of orders that no longer need to be shipped
+* A callback facility that provides shipment information (carrier, cost, tracking number, etc.) for an order
+* Query capabilities to read order data from ShippingEasy
+We will keep this library up to date as we expand the ShippingEasy API.
+
## Setup
### Installation
Add this line to your application's Gemfile:
@@ -60,11 +64,11 @@
## API Calls
### Finding an order
-To retrieve a specific order, call the find method on the Order resource class with a ShippingEasy order ID specified.
+To retrieve a specific order, call the find method on the Order resource class.
ShippingEasy::Resources::Order.find(id: 876)
If successful the call will return a JSON hash with the ShippingEasy order.
@@ -127,11 +131,11 @@
##### ShippingEasy::AccessDeniedError
Your credentials could not be authenticated or the store api_key could not be found.
##### ShippingEasy::InvalidRequestError
-The order could not be created on the server for one or more of the following reasons:
+The orders could not retrieved for one or more of the following reasons:
* The API timestamp could not be parsed.
The exception will contain a message that indicates which of these conditions failed.
@@ -401,9 +405,39 @@
* The order could not be found.
* The order has already been marked as shipped in the ShippingEasy system and cannot be cancelled.
The exception will contain a message that indicates which of these conditions failed.
+
+## Making requests via curl
+First you will need to create an API signature. Concatenate these into a plaintext string using the following order:
+
+1. Capitilized method of the request. E.g. "POST"
+2. The URI path
+3. The query parameters sorted alphabetically and concatenated together into a URL friendly format: param1=ABC¶m2=XYZ
+4. The request body as a string if one exists
+
+All parts are then concatenated together with an ampersand. The result resembles something like this:
+
+ "POST&/api/orders&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{\"orders\":{\"name\":\"Flip flops\",\"cost\":\"10.00\",\"shipping_cost\":\"2.00\"}}"
+
+Finally, using your API secret encrypt the string using HMAC sha256. In ruby, it looks like this:
+
+ OpenSSL::HMAC::hexdigest("sha256", api_secret, "POST&/api/orders&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{\"orders\":{\"name\":\"Flip flops\",\"cost\":\"10.00\",\"shipping_cost\":\"2.00\"}}")
+
+### API timestamp
+You must include an API timestamp in your requests. The timestamp should be an integer representation of the current time.
+
+### Example curl request
+
+````shell
+curl -H "Content-Type: application/json" --data @body.json "https://app.shippingeasy.com/api/stores/27aa472e16faa83dd13b7758d31974ed/orders?api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&api_signature=c65f43beed46e581939898a78acd10064cfa146845e97885ec02124d7ad648e4"
+````
+
+An example body.json can be found here:
+
+https://gist.github.com/twmills/3f4636b835c611ab3f7f
+
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)