shipcloud / shipcloud-ruby

A Ruby wrapper for the shipcloud API

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 (jruby/jruby#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