This plugin implements FedEx’s Web Services API, allowing you to get shipping rates and print shipping labels.
This particular fork is a minor bugfix over philsmy’s fork that was updated to support version 9 of the API (the latest as of April 2011).
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 9, so if you’re upgrading check ship_constants.rb and rate_constants.rb to ensure your constant hasn’t been renamed.
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.
The return values haven’t changed.
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/dazl/fedex.git
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_v9.wsdl as of May 2010) and Ship (ShipService_v9.wsdl as of April 2011). Download these WSDLs and put them in the vendor/plugins/fedex/lib/wsdl/ directory.
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.
-
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)
-
Phil Smy (fork for v9 compatibility)
-
Davide Zilioli (additional fixes for v9 compatibility)
This plugin is made available under the MIT license.