Blackbird::Retoure
Blackbird::Retoure is a Ruby implementation of the DHL Retoure REST API. The documentation of the API itself is located at: https://entwickler.dhl.de/group/ep/wsapis/retouren
Currently Blackbird::Retoure does support version 1.0 of the API.
Installation
Add this line to your application's Gemfile:
gem 'blackbird-retoure'
And then execute:
$ bundle
Or install it yourself as:
$ gem install blackbird-retoure
Usage
Configuration
Before you can call the DHL Retoure API you need to set up your account according to https://entwickler.dhl.de/group/ep/wsapis/retouren/authentifizierung
Add an initializer to your application and configure the gem as follows:
Blackbird::Retoure.configure do |config|
config.username = 'Username of the system user'
config.password = 'Password of the system user'
config.app_token = 'Application token for production environment (CIG)'
config.app_id = 'Application ID for production environment (CIG)'
config.environment = :production
end
Sandbox
For username
use your developer id of your developer account and for password
the matching password of your developer account.
The settings for app_token
and app_id
doesn't need to be set in a sandbox environment.
Production
For username
use your AppId and for the password
use the one time token.
The settings for app_token
and app_id
have to be provided in a production environment.
Label creation
Data validation
The objects Blackbird::Retoure::Country
, Blackbird::Retoure::ReturnOrder
and Blackbird::Retoure::ReturnOrder
as
well Blackbord::Retoure::SimpleAddress
uses ActiveModel::Validations
to ensure data validations.
Error messages can then be accessed by the #error
method.
Minimum amount of data needed
args = {
receiver_id: 'DE',
sender_address: {
name1: 'Name #1',
street_name: 'Street Name',
house_number: 'House Number #',
post_code: '12345',
city: 'City',
country: { country_iso_code: 'DEU' }
}
}
Retrieve a single shipping label with the least amount of data.
shipping_label = Blackbird::Retoure.shipping_label(args)
Just retrieve a QR code
qr_code = Blackbird::Retoure.qr_code(args)
Receive both documents (shipping label and qr code)
both_documents = Blackbird::Retoure.both(args)
Return object
The DHL API returns a JSON object consisting of the following data:
{
"shipmentNumber": "Shipping number",
"labelData": "Label data - base64 encoded",
"qrLabelData": "QR label data - base64 encoded",
"routingCode": "Routing code"
}
If an error happens you will receive a different structure:
{
"statusCode": "Error status code (e.g. 500)",
"statusText": "Error message"
}
To process this data you have to manually parse it.
Development
After checking out the repo, run bin/setup
to install dependencies.
As the DHL API need a personal username and password for the Sandbox environment, duplicate the YAML file spec/support/dev_environments/default.yml
and name it like your login user and change the default values in it. All files added to this directory will be ignored by commits.
Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Caveats
- Customs documents are currently not supported.
- A response class instead of passing of the Net::HTTP objects (tbd)
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/flip4dev/blackbird-retoure. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Blackbird::Retoure project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.