<commit_before>== Fedex On Rails

=== Description

This Rails[http://www.rubyonrails.org] 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}[http://mightyinteractive.com/ruby-on-rails/fedex/] that has been updated to be compatible with version 3 of the WSDLs that Fedex provides for integration purposes.

=== Installation

This plugin depends upon NaHi's[http://dev.ctor.org/soap4r/wiki/NaHi] excellent SOAP4R[http://dev.ctor.org/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}[http://www.fedex.com/developer] 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

=== Usage

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 => "<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.

=== Author

<NAME>, josephj [at] offmadisonave [dot] com
<NAME>, elliot.winkler [at] gmail [dot] com (fork for v3 compatibility)

=== Copyright/License

Copyright (c) 2007 <NAME>amillo

This plugin is made available under the MIT license.<commit_msg>Documentation corrections for v5<commit_after>== Fedex On Rails

=== Description

This Rails[http://www.rubyonrails.org] 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}[http://mightyinteractive.com/ruby-on-rails/fedex/] that has been updated to be compatible with version 3 of the WSDLs that Fedex provides for integration purposes.

=== Installation

This plugin depends upon NaHi's[http://dev.ctor.org/soap4r/wiki/NaHi] excellent SOAP4R[http://dev.ctor.org/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}[http://www.fedex.com/developer] 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

=== Usage

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.

 shipper       = {:name => "<NAME>",
                  :phone_number => '5205551212'}

 recipient     = {:name => "Fedex",
                  :phone_number => '9013693600'}

 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}

 pkg_count     = 1
 weight        = 10
 service_type  = Fedex::ServiceTypes::STANDARD_OVERNIGHT

Pass these to your Fedex object:

 price = fedex.price(:shipper      => {:contact=>shipper,   :address=>origin},
                     :recipient    => {:contact=>recipient, :address=>destination},
                     :count        => pkg_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:
 
 price, label, tracking_number = fedex.label(:shipper      => {:contact=>shipper,   :address=>origin},
                                             :recipient    => {:contact=>recipient, :address=>destination},
                                             :count        => pkg_count,
                                             :weight       => 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.  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.

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.

=== Author

<NAME>, josephj [at] offmadisonave [dot] com
<NAME>, elliot.winkler [at] gmail [dot] com (fork for v3 compatibility)
<NAME>, lalee [at] pobox [dot] com (additional fixes for v5 compatibility)

=== Copyright/License

Copyright (c) 2007 <NAME>

This plugin is made available under the MIT license.

{'fraction_non_alphanumeric': 0.07559292456571746, 'fraction_numerical': 0.012532719917506147, 'mean_word_length': 2.7368109069353883, 'pattern_counts': {'":': 0, '<': 12, '<?xml version=': 0, '>': 85, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 22, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5273843', 'n_tokens_mistral': 3472, 'n_tokens_neox': 3179, 'n_words': 1439}