This Rails plugin will enable you to integrate with Fedex’s Web Services platform for the purpose of obtaining shipping rate quotes, generating shipping labels, and cancelling shipments. Web Services is Fedex’s new web service platform that replaces Web Integration. It is quite robust. The plugin we’re providing here attempts to make using this new system as simple as you’ve come to expect from Rails itself. It does not implement Web Services in its entirety, but it provides the two core services (Rate and Ship) most applicable to e-commerce.
This is a fork of Mighty Interactive’s Fedex plugin that has been updated to be compatible with version 3 of the WSDLs that Fedex provides for integration purposes.
This plugin depends upon NaHi’s excellent SOAP4R library. You can install the latest gem as follows:
$ gem install soap4r --source http://dev.ctor.org/download/
Replace install with update if you’ve already installed SOAP4R. Additional installation options are available on the SOAP4R site. Any version after 1.5.8-RC2 will do.
To install the plugin itself, simply run:
./script/plugin install git://github.com/mcmire/fedex.git
Due to copyright reasons we cannot distribute the associated WSDL files; you will need to apply 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_v3.wsdl at the time of this writing) and Ship (ShipService_v3.wsdl at the time of this writing). Download these WSDLs and put them in vendor/plugins/fedex/lib/wsdl/ directory
Using the plugin is straightforward:
Start out by defining constants to hold the authentication parameters. 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 environment.rb.
AUTH_KEY = 'YOUR_AUTHORIZATION_KEY' SECURITY_CODE = 'YOUR_SECURITY_CODE' ACCOUNT = 'YOUR_ACCOUNT_NUMBER' METER_NUMBER = 'YOUR_METER_NUMBER'
Next, create your Fedex object. In true Rails fashion, parameters are supplied as a hash:
fedex = Fedex::Base.new( :auth_key => AUTH_KEY, :security_code => SECURITY_CODE, :account_number => ACCOUNT, :meter_number => METER_NUMBER )
The plugin has some basic minimum requirement-checking built in. 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
from ./lib/fedex.rb:204:in `check_required_options'
from ./lib/fedex.rb:37:in `initialize'
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. Additional options for printing are available. See Fedex::LabelSpecificationImageTypes for a list, which includes PNG and special formats designed for thermal printers.
Now let’s get a Rate quote. Define your origin, destination, number of packages, total weight, and shipping method.
origin = {:country => 'US', :street => '80 E. Rio Salado Pkwy. #711', # Off Madison Ave :city => 'Tempe', :state => 'AZ', :zip => '85281'} destination = {:country => 'US', :street => '942 South Shady Grove Road', # Fedex :city => 'Memphis', :state => 'TN', :zip => '38120', :residential => false} count = 1 weight = 10 service_type = Fedex::ServiceTypes::STANDARD_OVERNIGHT
Pass these to your Fedex object:
price = fedex.price(:origin => origin,
:destination => destination,
:count => count,
:weight => weight,
:service_type => service_type)
> puts price
8644
Rate quotes are returned as whole integers in cents (so the charge in this case is $86.44). Shipping is just as easy. Specify who’s doing the sending and receiving:
shipper = {:name => "Your Name", :phone_number => '5205551212'} recipient = {:name => "Fedex", :phone_number => '9013693600'}
And off we go:
price, label, tracking_number = fedex.label(:shipper => {:contact => shipper, :address => origin}, :recipient => {:contact => recipient, :address => destination}, :weight => total_weight, :service_type => service_type)
If everything goes well price, label, and tracking_number will all be populated accordingly. label is the Base64-decoded label as returned from Fedex. Store this in a :binary column in your database, or write it out to a file.
That’s it! There are quite a few additional configuration options which you can find by looking in the documentation in the source code itself, but this should be enough to get you started. If you encounter any bugs, please email me at josephj [at] offmadisonave [dot] com.
Joseph Jamarillo, josephj [at] offmadisonave [dot] com Elliot Winkler, elliot.winkler [at] gmail [dot] com (fork for v3 compatibility)
Copyright © 2007 Joseph Jaramillo
This plugin is made available under the MIT license.