Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 127 lines (90 sloc) 6.764 kb
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
1 # Active Shipping
2
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
3 This library interfaces with the web services of various shipping carriers. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby API. Active Shipping is an extension of [Active Merchant][], and as such, it borrows heavily from conventions used in the latter.
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
4
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
5 Active Shipping is currently being used and improved in a production environment for [Shopify][]. Development is being done by the Shopify integrations team (<integrations-team@shopify.com>). Discussion is welcome in the [Active Merchant Google Group][discuss].
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
6
7 [Active Merchant]:http://www.activemerchant.org
8 [Shopify]:http://www.shopify.com
9 [discuss]:http://groups.google.com/group/activemerchant
10
11 ## Supported Shipping Carriers
12
13 * [UPS](http://www.ups.com)
14 * [USPS](http://www.usps.com)
d78664b @jamesmacaulay added FedEx to list of supported carriers
jamesmacaulay authored
15 * [FedEx](http://www.fedex.com)
5829d34 @jamesmacaulay Update changelog and readme
jamesmacaulay authored
16 * [Canada Post](http://www.canadapost.ca)
822eda4 @nigelramsay NZ Post reference
nigelramsay authored
17 * [New Zealand Post](http://www.nzpost.co.nz)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
18 * more soon!
19
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
20 ## Installation
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
21
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
22 gem install active_shipping
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
23
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
24 ...or add it to your [Gemfile](http://gembundler.com/).
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
25
26 ## Sample Usage
27
5829d34 @jamesmacaulay Update changelog and readme
jamesmacaulay authored
28 ### Compare rates from different carriers
29
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
30 require 'active_shipping'
31 include ActiveMerchant::Shipping
32
33 # Package up a poster and a Wii for your nephew.
34 packages = [
35 Package.new( 100, # 100 grams
36 [93,10], # 93 cm long, 10 cm diameter
37 :cylinder => true), # cylinders have different volume calculations
38
39 Package.new( (7.5 * 16), # 7.5 lbs, times 16 oz/lb.
40 [15, 10, 4.5], # 15x10x4.5 inches
41 :units => :imperial) # not grams, not centimetres
42 ]
43
44 # You live in Beverly Hills, he lives in Ottawa
45 origin = Location.new( :country => 'US',
46 :state => 'CA',
47 :city => 'Beverly Hills',
48 :zip => '90210')
49
50 destination = Location.new( :country => 'CA',
51 :province => 'ON',
52 :city => 'Ottawa',
53 :postal_code => 'K1P 1J1')
54
55 # Find out how much it'll be.
56 ups = UPS.new(:login => 'auntjudy', :password => 'secret', :key => 'xml-access-key')
57 response = ups.find_rates(origin, destination, packages)
58
59 ups_rates = response.rates.sort_by(&:price).collect {|rate| [rate.service_name, rate.price]}
60 # => [["UPS Standard", 3936],
61 # ["UPS Worldwide Expedited", 8682],
62 # ["UPS Saver", 9348],
63 # ["UPS Express", 9702],
64 # ["UPS Worldwide Express Plus", 14502]]
65
66 # Check out USPS for comparison...
67 usps = USPS.new(:login => 'developer-key')
68 response = usps.find_rates(origin, destination, packages)
69
70 usps_rates = response.rates.sort_by(&:price).collect {|rate| [rate.service_name, rate.price]}
71 # => [["USPS Priority Mail International", 4110],
72 # ["USPS Express Mail International (EMS)", 5750],
73 # ["USPS Global Express Guaranteed Non-Document Non-Rectangular", 9400],
74 # ["USPS GXG Envelopes", 9400],
75 # ["USPS Global Express Guaranteed Non-Document Rectangular", 9400],
76 # ["USPS Global Express Guaranteed", 9400]]
64a1348 FedEx carrier class now returns rates for both Ground and Express ser…
Jimmy Baker authored
77
5829d34 @jamesmacaulay Update changelog and readme
jamesmacaulay authored
78 ### Track a FedEx package
79
80 fedex = FedEx.new(:login => '999999999', :password => '7777777')
81 tracking_info = fedex.find_tracking_info('tracking-number', :carrier_code => 'fedex_ground') # Ground package
6cd0129 FedEx#find_tracking_info is working. Added Sample Usage to the README.
Jimmy Baker authored
82
83 tracking_info.shipment_events.each do |event|
84 puts "#{event.name} at #{event.location.city}, #{event.location.state} on #{event.time}. #{event.message}"
85 end
86 # => Package information transmitted to FedEx at NASHVILLE LOCAL, TN on Thu Oct 23 00:00:00 UTC 2008.
87 # Picked up by FedEx at NASHVILLE LOCAL, TN on Thu Oct 23 17:30:00 UTC 2008.
88 # Scanned at FedEx sort facility at NASHVILLE, TN on Thu Oct 23 18:50:00 UTC 2008.
89 # Departed FedEx sort facility at NASHVILLE, TN on Thu Oct 23 22:33:00 UTC 2008.
90 # Arrived at FedEx sort facility at KNOXVILLE, TN on Fri Oct 24 02:45:00 UTC 2008.
91 # Scanned at FedEx sort facility at KNOXVILLE, TN on Fri Oct 24 05:56:00 UTC 2008.
92 # Delivered at Knoxville, TN on Fri Oct 24 16:45:00 UTC 2008. Signed for by: T.BAKER
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
93
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
94 ## Running the tests
95
96 After installing dependencies with `bundle install`, you can run the unit tests with `rake test:units` and the remote tests with `rake test:remote`. The unit tests mock out requests and responses so that everything runs locally, while the remote tests actually hit the carrier servers. For the remote tests, you'll need valid test credentials for any carriers' tests you want to run. The credentials should go in ~/.active_merchant/fixtures.yml, and the format of that file can be seen in the included [fixtures.yml](https://github.com/Shopify/active_shipping/blob/master/test/fixtures.yml).
97
ea75dd1 @jamesmacaulay update README again
jamesmacaulay authored
98 ## Contributing
99
100 Yes, please! Take a look at the tests and the implementation of the Carrier class to see how the basics work. At some point soon there will be a carrier template generator along the lines of the gateway generator included in Active Merchant, but carrier.rb outlines most of what's necessary. The other main classes that would be good to familiarize yourself with are Location, Package, and Response.
101
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
102 For the features you add, you should have both unit tests and remote tests. It's probably best to start with the remote tests, and then log those requests and responses and use them as the mocks for the unit tests. You can see how this works with the USPS tests right now:
103
104 https://github.com/Shopify/active_shipping/blob/master/test/remote/usps_test.rb
105 https://github.com/Shopify/active_shipping/blob/master/test/unit/carriers/usps_test.rb
106 https://github.com/Shopify/active_shipping/tree/master/test/fixtures/xml/usps
107
108 To log requests and responses, just set the `logger` on your carrier class to some kind of `Logger` object:
109
110 USPS.logger = Logger.new($stdout)
111
112 (This logging functionality is provided by the [`PostsData` module](https://github.com/Shopify/active_utils/blob/master/lib/active_utils/common/posts_data.rb) in the `active_utils` dependency.)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
113
ea75dd1 @jamesmacaulay update README again
jamesmacaulay authored
114 After you've pushed your well-tested changes to your github fork, make a pull request and we'll take it from there!
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
115
116 ## Contributors
117
428e933 @jamesmacaulay added attribution info
jamesmacaulay authored
118 * James MacAulay (<http://jmacaulay.net>)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
119 * Tobias Luetke (<http://blog.leetsoft.com>)
120 * Cody Fauser (<http://codyfauser.com>)
428e933 @jamesmacaulay added attribution info
jamesmacaulay authored
121 * Jimmy Baker (<http://jimmyville.com/>)
5829d34 @jamesmacaulay Update changelog and readme
jamesmacaulay authored
122 * William Lang (<http://williamlang.net/>)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
123
124 ## Legal Mumbo Jumbo
125
f3b56fd @jamesmacaulay update README
jamesmacaulay authored
126 Unless otherwise noted in specific files, all code in the Active Shipping project is under the copyright and license described in the included MIT-LICENSE file.
Something went wrong with that request. Please try again.