Project

fedex_ship

0.0
No commit activity in last 3 years
No release in over 3 years
Provides an interface to Upgraded Fedex Web Services
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

>= 0
>= 0
~> 3.1
~> 2.0
~> 1.8.0

Runtime

>= 0.13.7
>= 1.5.6
 Project Readme

IMPORTANT!!

This is an updated version of fedex gem. I just updated fedex gem for my personal use but later on, I realized that I should give this gem to others to leverage it.

I plan a major refactor to this gem. Sorry but at this moment I am not merging PR's. I appreciate your effort but need some time to catch up. Thanks!!

Fedex Rate Web Service

Fedex API Shipment Version: 21

For more information visit Fedex Web Services for Shipping.

This version uses the Non-SOAP Web Services so there is no need to download the Fedex WSDL files, note however that you will need to apply for development/production credentials.

Note: Please make sure to test your results.

Installation:

gem install fedex_ship

Usage example:

Define the shipper:

shipper = { :name => "Sender",
            :company => "Company",
            :phone_number => "555-555-5555",
            :address => "Main Street",
            :city => "Harrison",
            :state => "AR",
            :postal_code => "72601",
            :country_code => "US",
            :tin_type => "BUSINESS_NATIONAL",
            :tin_number => 'Shipper Tin Number' 
    }

Define the recipient:

recipient = { :name => "Recipient",
              :company => "Company",
              :phone_number => "555-555-5555",
              :address => "Main Street",
              :city => "Franklin Park",
              :state => "IL",
              :postal_code => "60131",
              :country_code => "US",
              :residential => "false",
              :tin_type => "BUSINESS_NATIONAL",
              :tin_number => 'Shipper Tin Number' 
}

Define the packages; multiple packages in a single shipment are allowed: Note that all the dimensions must be integers.

packages = []
packages << {
  :weight => {:units => "LB", :value => 2},
  :dimensions => {:length => 10, :width => 5, :height => 4, :units => "IN" }
}
packages << {
  :weight => {:units => "LB", :value => 6},
  :dimensions => {:length => 5, :width => 5, :height => 4, :units => "IN" }
}

By default packaging type is "YOUR PACKAGING" and the drop off type is "REGULAR PICKUP". If you need something different you can pass an extra hash for shipping options.

shipping_options = {
  :packaging_type => "YOUR_PACKAGING",
  :drop_off_type => "REGULAR_PICKUP",
  :special_services => []
}

If you pass a non-nil :return_reason as part of the shipping options, you will create a return shipment. The request to fedex will include the following additional XML.

<SpecialServicesRequested>
  <SpecialServiceTypes>RETURN_SHIPMENT</SpecialServiceTypes>
  <ReturnShipmentDetail>
    <ReturnType>PRINT_RETURN_LABEL</ReturnType>
    <Rma>
      <Reason>YOUR RETURN REASON HERE</Reason>
    </Rma>
  </ReturnShipmentDetail>
</SpecialServicesRequested>

By default the shipping charges will be assigned to the sender. If you may change this by passing an extra hash of payment options.

payment_options = {
  :type => "THIRD_PARTY",
  :account_number => "123456789",
  :name => "Third Party Payor",
  :company => "Company",
  :phone_number => "555-555-5555",
  :country_code => "US"
}

Create a FedexShip::Shipment object using your FedEx credentials; mode should be either production or development depending on what Fedex environment you want to use.

require 'fedex_ship'
fedex = FedexShip::Shipment.new(:key => 'xxx',
                            :password => 'xxxx',
                            :account_number => 'xxxx',
                            :meter => 'xxx',
                            :mode => 'production')

** Getting Shipping Rates **

To find a shipping rate:

rate = fedex.rate(:shipper=>shipper,
                  :recipient => recipient,
                  :packages => packages,
                  :service_type => "FEDEX_GROUND",
                  :customs_clearance_detail => {:customs_value => {:currency => "INR", :amount => invoice_amount}, :commercial_invoice => {:purpose => purpose}},
                  :shipping_options => shipping_options,
                  :carrier_code => 'FDXE',
                  :preferred_currency => "INR")

Fedex provides multiple total values; total_net_charge is the final amount you are looking for.

    $ rate.total_net_charge => "34.03"
    # Complete response
    $ <FedexShip::Rate:0x1019ba5f8
          @total_net_charge="34.03",
          @total_surcharges="1.93",
          @total_billing_weight="8.0 LB",
          @total_taxes="0.0",
          @rate_type="PAYOR_ACCOUNT_PACKAGE",
          @total_base_charge="32.1",
          @total_freight_discounts=nil,
          @total_net_freight="32.1",
          @rate_zone="51">

** Create a shipment and Get a Transit time(please note this will generate a shipment in your Fedex account if you are using production mode) **

ship = fedex.ship(:shipper=>shipper,
                  :recipient => recipient,
                  :packages => packages,
                  :service_type => "FEDEX_GROUND",
                  :customs_clearance_detail => @customs_clearance_detail,
                  :mps => {:package_count => packages.length.to_s, :total_weight => total_weight.to_s, :sequence_number => '1'},
                  :total_insured_value => {:amount => "0", :currency => "INR"},
                  :commercial_invoice_options => {
                                                       :shipping_document_types => "COMMERCIAL_INVOICE",
                                                       :commercial_invoice_detail => {
                                                           :format => {
                                                               :image_type => "PDF",
                                                               :stock_type => "PAPER_LETTER",
                                                               :provide_instructions => "1"
                                                           }
                                                       }
                                                   },
                 :shipping_options => shipping_options,
                 :carrier_code => 'FDXE',
                 :preferred_currency => "INR")
puts ship[:completed_shipment_detail][:operational_detail][:transit_time]

Above code will give you the transit time.

** Generate a shipping label (PDF) **

To create a label for a shipment:

label = fedex.label(:filename => "my_dir/example.pdf",
                    :shipper=>shipper,
                    :recipient => recipient,
                    :packages => packages,
                    :service_type => "FEDEX_GROUND",
                    :shipping_options => shipping_options)

** Generate a shipping label in any available format **

Change the filename extension and pass a label_specification hash. For example:

example_spec = {
  :image_type => "EPL2",
  :label_stock_type => "STOCK_4X6"
}

label = fedex.label(:filename => "my_dir/example_epl2.pcx",
                    :shipper=>shipper,
                    :recipient => recipient,
                    :packages => packages,
                    :service_type => "FEDEX_GROUND",
                    :shipping_options => shipping_options,
                    :label_specification => example_spec)

** Storing a label on Amazon S3 with Paperclip **

This is useful when you need to store the labels for later use, and are hosting your application on Heroku as they do not allow writing to the filesystem, save the tmp directory. With Paperclip setup up on a shipment model:

label = fedex.label(:filename => "tmp/example_label.pdf",
                    :shipper=>shipper,
                    :recipient => recipient,
                    :packages => packages,
                    :service_type => "FEDEX_GROUND",
                    :shipping_options => shipping_options,
                    :label_specification => example_spec)

Then attach the label to your Paperclip model:

shipment.fedex_label = label.file_name
shipment.save!

Documentation for setting up Paperclip with Amazon S3 can be found in the Paperclip README.

** Generate shipping labels for multi-package shipments (MPS) **

Multiple packages for a single pick-up, destination and payer can be combined into a single MPS shipment. The first label will provide a master tracking number which must be used in the subsequent calls for the remaining packages in the shipment.

Parameters for the first label:

label = fedex.label(
  :filename => file_name,
  :shipper => shipper,
  :recipient => recipient,
  :packages => packages,
  :service_type => service_type,
  :shipping_details => shipping_details,
  :shipping_charges_payment => shipping_charges_payment,
  :customs_clearance_detail => customs_clearance_detail,
  :mps => {:package_count => package_count, :total_weight => total_weight, :sequence_number => '1'}
  )

Parameters for labels 2 through 'n':

fedex.label(
  :filename => file_name,
  :shipper => shipper,
  :recipient => recipient,
  :packages => packages,
  :service_type => service_type,
  :shipping_details => shipping_details,
  :shipping_charges_payment => shipping_charges_payment,
  :customs_clearance_detail => customs_clearance_detail,
  :mps => {
      :master_tracking_id => {:tracking_id_type => 'FEDEX', :tracking_number =>tracking_number},
      :package_count => package_count,
      :total_weight => {
          :value => total_weight,
          :units => 'KG'
      }
      :sequence_number => 'n'
      }
   )

** Create COD Shipment **

To create a Cash On Delivery label for a shipment:

change "commerical_invoice = {:purpose => 'SOLD'}" in customs_clearance_detail

add shipping_options with {:cod => {:currency => "currency", :amount => "amount", :collection_type => 'PAYMENT COLLECTION TYPE'}, :special_services => ["COD"] }

PAYMENT COLLECTION TYPE - CASH, CHEQUE, DEMAND DRAFT

** To add multiple commodities in customs_clearance_detail

use this format commodities_1 .... commodities_N

example

customer_references_package = [
            {
                :customer_reference_type => "CUSTOMER_REFERENCE",
                :value => 'recipient_email'
            }, {
                :customer_reference_type => "INVOICE_NUMBER",
                :value => "INV123456"
            }, {
                :customer_reference_type => "P_O_NUMBER",
                :value => "OrderNumber123456"
            }
        ]

@customs_clearance_detail = {
            :duties_payment => {
                :payment_type => "SENDER",
                :payor => {
                    :responsible_party => {
                        :account_number => @account_no,
                        :address => {
                            :country_code => "IN"
                        }
                    }
                }
            },
            :document_content => "NON_DOCUMENTS",
            :customs_value => {:currency => "INR", :amount => invoice_amount},
            :commercial_invoice => {:purpose => purpose, :customer_references => customer_references_package
            },
            :commodites_1 => {
                :number_of_pieces => "1",
                :description => "desc....",
                :country_of_manufacture => "IN",
                :weight => {
                    :units => "KG",
                    :value => 1.5
                },
                :quantity => 2,
                :quantity_units => "pieces",
                :unit_price => {
                    :currency => "INR",
                    :amount => 100
                }
             }
             :commodites_2 => {
                ......
                ......
                ......
             }
        }

** Masking shipper details in label **

this allows you hide shipper details on the label

Add customer_specified_detail = {:masked_data_1 => 'SOMETHING', :masked_data_2 => 'SOMETHING'} in :label_specification key

Example

  customer_specified_detail = {
      :masked_data_1 => "SHIPPER_ACCOUNT_NUMBER",
      :masked_data_2 => "TRANSPORTATION_CHARGES_PAYOR_ACCOUNT_NUMBER",
      :masked_data_3 => "DUTIES_AND_TAXES_PAYOR_ACCOUNT_NUMBER"
  }

** Delete a shipment **

If you do not intend to use a label you should delete it. This will notify FedEx that you will not be using the label and they won't charge you.

To delete a shipment:

fedex.delete(:tracking_number => "1234567890123")

** Tracking a shipment **

To track a shipment:

results = fedex.track(:tracking_number => "1234567890123")
# => [#<FedexShip::TrackingInformation>]

# Pull the first result from the returned array
#
tracking_info = results.first

tracking_info.tracking_number
# => "1234567890123"

tracking_info.status
# => "Delivered"

tracking_info.events.first.description
# => "On FedEx vehicle for delivery"

** Verifying an address **

To verify an address is valid and deliverable:

address = {
  :street     => "5 Elm Street",
  :city        => "Norwalk",
  :state       => "CT",
  :postal_code => "06850",
  :country     => "USA"
}

address_result = fedex.validate_address(:address => address)

address_result.residential
# => true

address_result.score
# => 100

address_result.postal_code
# => "06850-3901"

** Requesting a Pickup **

To request a pickup:

pickup = fedex.pickup(:carrier_code => 'FDXE',
                      :packages => {:weight => {:units => "LB", :value => 10}, :count => 2},
                      :ready_timestamp => Date.today.to_datetime + 1.375,
                      :close_time => Date.today.to_time + 60 * 60 * 17,
                      :country_relationship => "DOMESTIC",
                      :pickup_location => shipper)
puts pickup[:pickup_confirmation_number]

** Getting pickup availability details **

To check for pickup availability:

dispatch = Date.tomorrow.strftime('%Y-%m-%d')

pickup_availability = fedex.pickup_availability(:country_code => 'IN',
                                   :postal_code => '400061',
                                   :request_type => 'FUTURE_DAY',
                                   :dispatch_date => dispatch_date,
                                   :carrier_code => 'FDXE')

puts pickup_availability[:options]

** Getting service availability **

To check service availability:

origin = {:postal_code => '400012', :country_code => 'IN'}
destination = { :postal_code => '400020', :country_code => 'IN'}
fedex_service_hash = {:origin => origin, :destination => destination, :ship_date => '2014-06-28', :carrier_code => 'FDXE'}

service = fedex.service_availability(fedex_service_hash)

puts service[:options]

Services/Options Available

FedexShip::Request::Base::SERVICE_TYPES
FedexShip::Request::Base::PACKAGING_TYPES
FedexShip::Request::Base::DROP_OFF_TYPES
FedexShip::Request::Base::CARRIER_CODES

Contributors: