README.md in shipping_easy-0.3.2 vs README.md in shipping_easy-0.5.0
- old
+ new
@@ -1,7 +1,7 @@
-[](https://codeclimate.com/repos/5315eeefe30ba01aa501c119/feed)
-
+[](https://codeclimate.com/github/ShippingEasy/shipping_easy-ruby)
+[](https://travis-ci.org/ShippingEasy/shipping_easy-ruby)
# ShippingEasy
This is the official wrapper for the ShippingEasy API.
The ShippingEasy API supports the following features:
@@ -393,10 +393,99 @@
If successful the call will return a JSON hash with the ShippingEasy order ID, as well as the external order identifier originally supplied in your call.
{ "order" => { "id" => "27654", "external_order_identifier" => "ABC123" } }
+### Rate Quote API
+
+ShippingEasy provides an API for our partners to fetch rate quotes from USPS, UPS or FedEx.
+
+Once you've setup your Partner credentials with a ShippingEasy account manager and have been issued an API key/secret, configure the client with your API credentials in the following block, which should be setup in an initializer:
+
+ ShippingEasy.configure do |config|
+ config.partner_api_key = REPLACE_WITH_API_KEY # Use your provided Partner API Key
+ config.partner_api_secret = REPLACE_WITH_API_SECRET # Use your provided Partner API Secret
+ config.base_url = "https://app.shippingeasy.com"
+ end
+
+#### Rate Quote API Attributes
+
+The following is a list of attributes that should be provided to the `ShippingEasy::Resources::RateQuote` object as an associative array, using the `fetch` method.
+
+Some example hashes of rate quote request data for each carrier can be found at https://gist.github.com/nkrupa/3a76e592377f12bd96be
+
+**carrier**
+: *Required.* Must be one of the following (case-sensitive): `['usps', 'ups', 'fedex']`.
+
+**carrier_service**
+: *Required.* Must match the carrier-specific service API key (and is case-sensitive). For example, for USPS First Class International, use `FirstClassMailInternational`. See the carrier's documentation for possible service keys.
+
+**packaging**
+: *Required.* Use `custom` for customer-provided, otherwise specify the carrier-specific packaging key. For example, for USPS Small Flat Rate Box, use `SmallFlatRateBox`.
+
+**packaging_dimensions**
+: Valid only for customer-provided packaging. Must be a hash with all three keys of `:length, :width, :height`.
+
+**from_address_1**
+: *Required for UPS and FedEx*
+
+**from_address_2**
+
+**from_city**
+: *Required for UPS and FedEx*
+
+**from_state**
+: *Required for UPS and FedEx*
+
+**from_postal_code**
+: *Required for all carriers*
+
+**from_phone_number**
+: *Required for FedEx*
+
+**to_residential**
+: boolean (defaults to false) represented if destination address is residential. Used by UPS and FedEx.
+
+**to_postal_code**
+: *Required for USPS domestic rates, and for UPS and FedEx*
+
+**to_address_1**
+: *Required for UPS and FedEx*
+
+**to_address_2**
+
+**to_city**
+: *Required for UPS and FedEx*
+
+**to_state**
+: *Required for UPS and FedEx*
+
+**to_country_code**
+: *Required for all international quotes* Defaults to 'US', must be a two-digit ISO-3166 country code.
+
+**to_phone_number**
+: *Required for FedEx*
+
+**weight**
+: *Required for most carrier services* - represented in ounces.
+
+**confirmation_option**
+: Available options (not all available for all carriers/services): `["delivery_confirmation", "signature_required", "adult_signature_required", "verbal_confirmation", "DIRECT", "INDIRECT", "ADULT", "included_signature_confirmation", "restricted_delivery", "signature_confirmation", "adult_signature", "delivery_confirmation", "am_delivery"]`
+
+**requires_additional_handling**
+: Available for UPS only
+
+**saturday_pickup**
+: Available for UPS/FedEx only. Cannot be combined with saturday_delivery
+
+**saturday_delivery**
+: Available for UPS/FedEx only. Cannot be combined with saturday_pickup
+
+**ship_date**
+: *Required for FedEx*
+
+
#### Possible Exceptions
##### ShippingEasy::AccessDeniedError
Your credentials could not be authenticated or the store api_key could not be found.
@@ -412,11 +501,11 @@
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
+4. The request body as a string if one exists. Escape all double quotes with backslashes.
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\"}}"
@@ -425,18 +514,32 @@
OpenSSL::HMAC::hexdigest("sha256", api_secret, "POST&/api/stores/27aa472e16faa83dd13b7758d31974ed/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 a Unix epoch timestamp (integer) of the current time.
-### Example curl request
+### Example curl requests
+#### Creating an order
+
````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
+
+#### Cancelling an order
+
+````shell
+curl -X POST "https://app.shippingeasy.com/api/stores/86eac265e87ea9a74a86fe248f2e79d2/orders/ABC123/cancellations?api_key=XXX&api_signature=c24c5118a2b2af27557af721145991594d00a0d914f0d9bc2b9a2fa26efb30cc&api_timestamp=1409173624"
+````
+
+#### Searching orders
+
+````shell
+curl "https://app.shippingeasy.com/api/orders?api_key=XXX&api_signature=a6ab10918d435ad2abfbbe6004dc2fc7faac62a291f4d66e4a36e5a654d15a54&api_timestamp=1409174329&page=3&per_page=10&status%5B%5D=ready_for_shipment&status%5B%5D=shipped"
+````
## Contributing
1. Fork it