A Ruby wrapper for the shipcloud API
Ruby
Latest commit 92656d4 Apr 25, 2016 @torasakura torasakura committed with sfroehler add pickup_address to PickupRequest resource (#20)
* **add pickup_address to PickupRequest resource**
* send an optional pickup address with a pickup request
* add comment in CHANGELOG.md

[Trello #10](https://trello.com/c/e6c6OXhH)
Permalink
Failed to load latest commit information.
lib add pickup_address to PickupRequest resource (#20) Apr 25, 2016
spec add pickup_address to PickupRequest resource (#20) Apr 25, 2016
.codeclimate.yml
.gitignore adds vendor/bundle to .gitignore Jun 26, 2014
.hound.yml Adds rubocop and hound configuration files Jan 7, 2016
.rspec
.rubocop.yml
.ruby-style.yml Updates ruby style guide file Jan 21, 2016
.travis.yml drop jruby-9 support Jan 21, 2016
CHANGELOG.md add pickup_address to PickupRequest resource (#20) Apr 25, 2016
Gemfile updates gemfile and shipcloud.gemspec Jun 26, 2014
LICENSE.txt Initial commit Aug 29, 2013
README.md add basic pickup request support Apr 1, 2016
Rakefile
shipcloud.gemspec

README.md

Code Climate Build Status Dependency Status

shipcloud

A Ruby wrapper for the shipcloud API

We have dropped the support of jruby-9, because there is an issue with mixing hash and keyword arguments (https://github.com/jruby/jruby/issues/3138). When this issue is fixed, we will support jruby-9 again.

Installation

Add this line to your application's Gemfile:

gem 'shipcloud'

And then execute:

$ bundle

Or install it yourself as:

$ gem install shipcloud

Usage

Before using the shipcloud API, you may want to set the API access key.

Shipcloud.api_key = 'your-api-key-goes-here'

Since Version 0.4.0, you can also do this via a configuration block, e.g. in an initializer:

Shipcloud.configure do |config|
  config.api_key = 'your-api-key-goes-here'
end

You can also pass the API key with each request:

 Shipcloud::Shipment.create(
   {
     carrier: 'ups',
     from: from-address-params,
     to: to-address-params,
     package: package-params,
     create_shipping_label: true
   },
  api_key: "your-api-key"
 )

If you pass in the api_key option, the value will be used as API key for the current request, even if you have set the Shipcloud.api_key before.

You can sign up for a developer account at shipcloud.io

Create a new shipment

To create a new Shipment on the shipcloud platform, you need to provide the name of the carrier, to- and from-address, and the package dimensions. For details, see shipcloud API documentation on Shipments

Shipcloud::Shipment.create(
    carrier: 'ups',
    from: from-address-params,
    to: to-address-params,
    package: package-params,
    create_shipping_label: true
)

Shipment#create will return shipping label and tracking information, encapsulated in a Shipcloud::Shipment object:

shipment = Shipcloud::Shipment.create(...) # parameters ommitted
shipment.tracking_url # -> http://track.shipcloud.io/uzdgu22z3ed12

Get a list of shipments

You can get a list of all shipments from the shipcloud platform. Shipments can be filtered by providing optional parameters. For more information and a list of valid parameters see shipcloud API documentation on Shipments Index

Shipcloud::Shipment.all(
  carrier: 'ups',
  per_page: 25,
  page: 2
)

Shipment#all will return an array of Shipcloud::Shipment objects, matching the given parameters.

Get a shipment quote

To get a shipment qoute from the shipcloud platform, you need to provide the name of the carrier, the service, to- and from-address, and the package dimensions. For details, see shipcloud API documentation on shipment quotes

shipment_quote = Shipcloud::ShipmentQuote.create(
  carrier: 'ups',
  service: 'standard',
  to: {
    street: "Receiver street",
    street_no: "123",
    zip_code: "12345",
    city: "Receiver town",
    country: "DE"
  },
  from: {
    street: "Sender street",
    street_no: "321",
    zip_code: "54321",
    city: "Sender town",
    country: "DE"
  },
  package: {
    weight: 8,
    width: 15,
    length: 32,
    height: 46,
  },
)

shipment_quote.price # => 6.2

Create a pickup request

To request parcels being picked up, you need to provide the carrier name and the time (earliest and latest) your shipments shall be fetched.

pickup_request = Shipcloud::PickupRequest.create(
  carrier: 'dpd',
  pickup_time: {
    earliest: "2016-04-04T09:00:00+02:00",
    latest: "2016-04-04T18:00:00+02:00"
  }
)

pickup_request.id # => "dje892dj20d2odj20"
pickup_request.carrier_pickup_number # => "12345"

You may also provide a list of shipment ids to specify only certain shipments to be included in the pickup request.

pickup_request = Shipcloud::PickupRequest.create(
  carrier: 'dpd',
  pickup_time: {
    earliest: "2016-04-04T09:00:00+02:00",
    latest: "2016-04-04T18:00:00+02:00"
  },
  shipments: [
    { id: "abc_123"}
  ]
)

pickup_request.id # => "dje892dj20d2odj20"
pickup_request.carrier_pickup_number # => "12345"

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Update the "Unreleased" section of the CHANGELOG.md (Keep a CHANGELOG)
  5. Push to the branch (git push origin my-new-feature)
  6. Create new Pull Request