Spree + EasyPost

This is an extension to integrate Easy Post into Spree. This extension is based off of a combination of solidus_easypost and solidus_shipping_labeler

You will need to sign up for an account to use this extension.

Installation

1. Add this extension to your Gemfile with this line:

gem 'spree_easypost', github: 'ShopFelixGray/spree_easypost'

2. Install the gem using Bundler:

bundle install

3. Copy & run migrations

bundle exec rails g spree_easypost:install
rake db:migrate

4. This goes into a new file called config/initializers/easy_post.rb:

EasyPost.api_key = 'YOUR_API_KEY_HERE'

5. Restart your server

If your server was running, restart it so that it can find the assets properly.

6. Add Carrier Accounts

Make sure to add accounts (seperated by commas but NO spaces) to the easypost settings in the admin section configuration. The account ids can be found in your easypost dashboard under carrier section.

Usage

1. Validating An Address

To validate an address with this gem, call .easypost_address_validate on an instance of the Spree::Address model.

Example:

Spree::Address.find(1).easypost_address_validate

This method will not run the model validations that already exist in your application, nor will it save or update an address for you. This method is only designed to run the address through the Easypost API and return a hash with suggestions to update the address if successful, or return Easypost error message is unsuccessful.

2. Response from the .easypost_address_validate method

This method will respond with a hash containing a key which will be either :suggestions (if the address is determined deliverable) or :errors (if the address is invalid or not deliverable).

Given the following address hash:

{
  firstname: "Bob",
  lastname: "Seger",
  address1: "624 W 139th St",
  address2: "Apt 2C",
  city: "New York",
  state_id: "3561",
  zipcode: "10031",
  country_id: "232",
  phone: "1234567890"
}

The suggestion hash will return the following - changing some of the formatting and moving address 2 to the address 1 line:

{
  suggestions: {
    address1: "624 W 139TH ST APT 2C",
    address2: "",
    city: "NEW YORK",
    zipcode: "10031-7329"
  }
}

3. Error responses from the .easypost_address_validate method

If the Easypost API does not validate the address, you will receive an array of errors in the response hash.

Example error messages:

{
  errors: {
    address1: ["can't be blank"],
    address2: ["Missing secondary information(Apt/Suite#)"],
    address: [
      "Invalid city/state/ZIP",
      "Address not found"
    ]
  }
}

Errors will be returned under the address key if they are not particular to a specific part of the address such as when the address does not exist or if the error is related to multiple parts of the address (such as city/state/zip mismatch).

Testing

First bundle your dependencies, then run rake. rake will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using rake test_app.

bundle
bundle exec rake

When testing your applications integration with this extension you may use it's factories. Simply add this require statement to your spec_helper:

require 'spree_easypost/factories'

Contributing

If you'd like to contribute, please take a look at the instructions for installing dependencies and crafting a good pull request.

Copyright (c) 2017 Houtan Fanisalek, released under the New BSD License