Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Supports v8 of the Fedex API, including grouping multiple packages and shipping internationally.
Ruby
branch: master

This branch is 30 commits ahead of mcmire:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
tasks
.gitignore
MIT-LICENSE
README.rdoc
Rakefile
init.rb
install.rb
uninstall.rb

README.rdoc

FedEx

This plugin implements FedEx's Web Services API, allowing you to get shipping rates and print shipping labels.

Updates over other repos

This particular fork has been extended to allow multiple-package shipments and support international shipping. It's also been updated to support version 8 of the API (the latest as of May 2010).

API Changes

This update is nearly backwards-compatible with older versions; if you're only sending one item, you can still use the old-style inline API for package information:

price, label, tracking_number = @fedex.label({
  :shipper => shipper_address,
  :recipient => recipient_address,
  :weight => 4.3125,
  :service_type => 'FEDEX_GROUND'
})

If you want to ship one or more packages in a group, however, you can also use the :packages option:

price, labels, tracking_number = @fedex.label({
  :shipper => shipper_address,
  :recipient => recipient_address,
  :service_type => 'FEDEX_GROUND',
  :packages => [
    {:weight => 4.3125},
    {:weight => 1.23, :dry_ice => true, :dry_ice_weight => 0.5}
  ],
})

Some of the constants have also changed between version 5 and 8, so if you're upgrading check ship_constants.rb and rate_constants.rb to ensure your constant hasn't been renamed.

Return values

For Labels

The price returned is the sum of the prices of each package shipped. The second return value will be the label, if only one package is shipped, or an array of labels, if multiple are sent together. The tracking number returned when shipping a group of packages is the master tracking number, which you can use to track all grouped items.

For Rates

The return values haven't changed.

Installation

This plugin depends the SOAP4R library. Just add this line to config/environment.rb:

config.gem "soap4r", :lib => "soap/soap", :version => ">= 1.5.8"

and then run:

$ sudo rake gems:install

To install the plugin itself, simply navigate to your project directory and run:

script/plugin install git://github.com/kdonovan/fedex.git

IMPORTANT: Obtaining WSDLs

Due to copyright reasons we cannot distribute the associated WSDL files; you'll need to register for a developer account with Fedex to begin working on your integration. Once you've created your account head to the “Get Started” section, where you can find documentation and the individual WSDLs for all of the available services. For our purposes you need only two: Rate (RateService_v8.wsdl as of May 2010) and Ship (ShipService_v8.wsdl as of May 2010). Download these WSDLs and put them in the vendor/plugins/fedex/lib/wsdl/ directory.

Usage

Using the plugin is straightforward:

To use Fedex Web Services you will need four pieces of information: Account Number, Authorization Key, Security Code, and Meter Number. You will receive all four when you create your developer account. An ideal place to put these constants is in an initializer under config/initializers.

module FedExAuth
  DEVELOPMENT = {
    :auth_key       => YOUR_DEV_AUTH_KEY,
    :security_code  => YOUR_DEV_SECURITY_CODE,
    :account_number => YOUR_DEV_ACCOUNT_NUMBER,
    :meter_number   => YOUR_DEV_METER_NUMBER
  }

  PRODUCTION = {
    :auth_key       => YOUR_PROD_AUTH_KEY,
    :security_code  => YOUR_PROD_SECURITY_CODE,
    :account_number => YOUR_PROD_ACCOUNT_NUMBER,
    :meter_number   => YOUR_PROD_METER_NUMBER
  }
end

Before you can get a rate or create a label, you must first create a Fedex object. Here you pass in the constants you just created, along with any other options that apply (see lib/fedex.rb).

# Development
fedex = Fedex::Base.new( FedExAuth::DEVELOPMENT )

# Production
fedex = Fedex::Base.new( FedExAuth::PRODUCTION.merge(:environment => :production) )

Note that leaving out one or more required pieces of information for any method will result in an exception being thrown:

> fedex = Fedex::Base.new
Fedex::MissingInformationError: Missing :auth_key, :security_code, :account_number, :meter_number

For the purpose of demonstration we're using the PDF label type, which is the default. PDFs are nice because they'll print onto a regular 8.5“x11” sheet of paper exactly the way FedEx needs them. See ShippingDocumentImageTypes and LabelStockTypes (defined in lib/{rate|ship}_constants.rb) for more options to control label formatting.

Now let's get a Rate quote. Define your origin, destination, and the weight of all packages. If you supply a service_type you'll get back the price of that shipment; just leave this out to return a hash containing the price of all shipping options available between the specified origin and destination.

shipper = {
  :name => "Your Name",
  :phone_number => '5205551212'
}
recipient = {
  :name => "Fedex",
  :phone_number => '9013693600'
}
origin = {
  :street => '80 E. Rio Salado Pkwy. #711', # Off Madison Ave
  :city => 'Tempe',
  :state => 'AZ',
  :zip => '85281',
  :country => 'US'
}
destination = {
  :street => '942 South Shady Grove Road',  # Fedex
  :city => 'Memphis',
  :state => 'TN',
  :zip => '38120',
  :country => 'US',
  :residential => false
}
service_type = Fedex::ShipConstants::ServiceTypes::STANDARD_OVERNIGHT

Pass these to your Fedex object:

price = fedex.price(
  :shipper => { :contact => shipper, :address => origin },
  :recipient => { :contact => recipient, :address => destination },
  :service_type => service_type,
  :packages => [
    {:weight => 10}
  ]
)
price #=> 8644

Note that rate quotes are returned as whole integers in cents (so the charge in this case is $86.44).

Shipping is just as easy:

price, labels, tracking_number = fedex.label(
  :shipper => { :contact => shipper, :address => origin },
  :recipient => { :contact => recipient, :address => destination },
  :service_type => service_type,
  :packages => [
    {:weight => 10}
  ]
)

If everything goes well, price, label, and tracking_number will all be populated accordingly. label is the Base64-ecoded label as returned from Fedex (or, if multiple packages are provided, an array of Base64-encoded labels). By default the Fedex plugin requests the label to be returned as a PDF file suitable for laser printing. Store this in a :binary column in your database, or write it out to a file.

And that's it! There are quite a few additional configuration options which you can find by looking in the documentation or the source code itself, but this should be enough to get you started.

Author/Contributors

  • Joseph Jamarillo, josephj [at] offmadisonave [dot] com (original author)

  • Elliot Winkler, elliot.winkler [at] gmail [dot] com (fork for v5 compatibility)

  • Laurence A. Lee, lalee [at] pobox [dot] com (additional fixes for v5 compatibility)

  • Kali Donovan (v8 compatibility, multiple package support, international shipping)

Copyright/License

Copyright © 2010 Kali Donovan

This plugin is made available under the MIT license.

Something went wrong with that request. Please try again.