A Ruby wrapper for the shipcloud API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.codeclimate.yml
.gitignore
.hound.yml
.rspec
.rubocop.yml
.ruby-version
.travis.yml
CHANGELOG.md
Gemfile
LICENSE.txt
README.md
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