Simple Shipping

Provides a common simple API to build labels for the following shipping services:

FedEx
UPS

Installation

Add to Gemfile:

gem 'simple_shipping'

Run bundle install.

Usage

# Build shipper
shipper_address = SimpleShipping::Address.new(
  :country_code => 'US',
  :state_code   => 'TX',
  :city         => 'Texas',
  :street_line  => 'SN2000 Test Meter 8',
  :postal_code  => '73301'
)
shipper_contact = SimpleShipping::Contact.new(
  :person_name  => 'Mister Someone',
  :phone_number => '1234567890'
)
shipper = SimpleShipping::Party.new(
  :address => shipper_address,
  :contact => shipper_contact
)

# Build recipient
recipient_address = SimpleShipping::Address.new(
  :country_code => 'US',
  :state_code   => 'MN',
  :city         => 'Minneapolis',
  :street_line  => 'Nightmare Avenue 13',
  :postal_code  => '55411'
)
recipient_contact = SimpleShipping::Contact.new(
  :person_name  => "John Recipient Smith",
  :phone_number => "1234567890"
)
recipient = SimpleShipping::Party.new(
  :address        => recipient_address,
  :contact        => recipient_contact,
  # optional, but required if party is payor
  :account_number => ACCOUNT_NUMBER
)

package = SimpleShipping::Package.new(
  :weight          => 1,
  :length          => 2,
  :height          => 3,
  :dimension_units => :in,  # you can use :kg as well
  :weight_units    => :lb,  # you can use :cm as well
  :width           => 4,
  :packaging_type  => :your
)

# Create clients
fedex = SimpleShipping::Fedex::Client.new(
  :credentials => {
    :key            => KEY,
    :password       => PASSWORD,
    :account_number => ACCOUNT_NUMBER,
    :meter_number   => METER_NUMBER
})
ups = SimpleShipping::Ups::ShipClient.new(
  :credentials => {
    :username              => USERNAME,
    :password              => PASSWORD,
    :access_license_number => ACCESS_LICENSE_NUMBER
  }
)

# Do request
# Default payor is :shipper
ups_resp   = ups.shipment_request(shipper, recipient, package)
fedex_resp = fedex.request(shipper, recipient, package, :payor => :recipient)

Specific extra options

You can customize the request using specific options for the service by passing an options hash:

FedEx extra options

:dropoff_type (see SimpleShipping::Fedex::ShipmentBuilder::DROPOFF_TYPES for available values)
:service_type (see SimpleShipping::Fedex::ShipmentBuilder::SERVICE_TYPES for available values)

Example:

fedex_client.request(shipper, recipient, package, :dropoff_type => :drop_box)

UPS extra options

service_type (see SimpleShipping::Ups::ShipmentBuilder::SERVICE_TYPES for available values)

Example

ups_client.shipment_request(shipper, recipient, package, :service_type => :express)

Requirements

You must have ImageMagick installed to run the demos.

Linux

Gentoo

emerge -pv imagemagick emerge imagemagick

Ubuntu

sudo apt-get install imagemagick libmagic-dev libmagicwand-dev

OS X

Homebrew

brew install imagemagick

MacPorts

sudo port install imagemagick

Fink

fink install imagemagick

Developers information

SimpleShipping provides the following models which inherit SimpleShipping::Abstract::Model:

Shipment
Package
Party
Address
Contact

Every service adapter has its own builders which know how to represent every separated model to build SOAP request for a specific service. For example to represent Package model, the FedEx adapter has Fedex::PackageBuilder and the UPS adapter has Ups::PackageBuilder. All these model builders inherit SimpleShipping::Abstract::Builder.

Request builders are used to build whole request for the service. They inherit Abstract::RequestBuilder.

Client is a facade which provides a public API to the user. Every service has its own client but they all inherit Abstract::Client. All clients provide the same interface:

.new(credentials_hash)
#request(shipper, recipient, package, opts)

Demo rake tasks

You can test the library against real remote requests. For this you need to have a yaml file with your private credentials, for example credentials.yml wich looks this way:

fedex:
  key: "KEY"
  password: "SECRET"
  account_number: "ACCOUNT NUM"
  meter_number: "METER NUM"

ups:
  username: "USER"
  account_number: "ACCOUNT NUM"
  password: "SECRET"
  :access_license_number: "LICENSE NUM"

To run demo tasks:

rake demo:fedex:shipment_request[credentials.yml]
rake demo:ups:shipment_request[credentials.yml]
rake demo:ups:void_request[credentials.yml]

UPS certification

To run UPS certification:

./script/ups_certification.rb ./credentials.yml

Where credentials.yml is file with format described above.

TODO

Validation for country codes and states?
Refactor
Ability to get more information from response object than just a label(tracking number, etc)

Contributing to simple_shipping

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.