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

```ruby

Build shipper

shipperaddress = SimpleShipping::Address.new( :countrycode => 'US', :statecode => 'TX', :city => 'Texas', :streetline => 'SN2000 Test Meter 8', :postalcode => '73301' ) shippercontact = SimpleShipping::Contact.new( :personname => 'Mister Someone', :phonenumber => '1234567890' ) shipper = SimpleShipping::Party.new( :address => shipperaddress, :contact => shippercontact )

Build recipient

recipientaddress = SimpleShipping::Address.new( :countrycode => 'US', :statecode => 'MN', :city => 'Minneapolis', :streetline => 'Nightmare Avenue 13', :postalcode => '55411' ) recipientcontact = SimpleShipping::Contact.new( :personname => "John Recipient Smith", :phonenumber => "1234567890" ) recipient = SimpleShipping::Party.new( :address => recipientaddress, :contact => recipientcontact, # optional, but required if party is payor :accountnumber => ACCOUNTNUMBER )

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

Create clients

fedex = SimpleShipping::Fedex::Client.new( :credentials => { :key => KEY, :password => PASSWORD, :accountnumber => ACCOUNTNUMBER, :meternumber => METERNUMBER }) ups = SimpleShipping::Ups::ShipClient.new( :credentials => { :username => USERNAME, :password => PASSWORD, :accesslicensenumber => ACCESSLICENSENUMBER } )

Do request

Default payor is :shipper

upsresp = ups.shipmentrequest(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: ruby 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 ruby 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:

```yaml fedex: key: "KEY" password: "SECRET" accountnumber: "ACCOUNT NUM" meternumber: "METER NUM"

ups: username: "USER" accountnumber: "ACCOUNT NUM" password: "SECRET" :accesslicense_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.

Copyright

Copyright (c) 2011 TMX Credit. Author Potapov Sergey. See LICENSE.txt for further details.