{"id":24926648,"url":"https://github.com/webit-de/dhl-bcs","last_synced_at":"2025-04-09T20:41:44.084Z","repository":{"id":10279827,"uuid":"65194959","full_name":"webit-de/dhl-bcs","owner":"webit-de","description":"client for DHL Business Customer Shipping API version 2","archived":false,"fork":false,"pushed_at":"2023-04-12T05:55:25.000Z","size":54,"stargazers_count":12,"open_issues_count":3,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T22:37:27.901Z","etag":null,"topics":["dhl","dhl-api","gem","ruby","soap"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webit-de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-08T10:21:11.000Z","updated_at":"2024-05-13T12:15:52.000Z","dependencies_parsed_at":"2023-02-14T07:45:35.869Z","dependency_job_id":null,"html_url":"https://github.com/webit-de/dhl-bcs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webit-de%2Fdhl-bcs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webit-de%2Fdhl-bcs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webit-de%2Fdhl-bcs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webit-de%2Fdhl-bcs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webit-de","download_url":"https://codeload.github.com/webit-de/dhl-bcs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248109873,"owners_count":21049388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dhl","dhl-api","gem","ruby","soap"],"created_at":"2025-02-02T12:52:57.941Z","updated_at":"2025-04-09T20:41:44.055Z","avatar_url":"https://github.com/webit-de.png","language":"Ruby","readme":"# Dhl::Bcs\n\nThis is a client for the DHL Business Customer Shipping (BCS) API version 2.0.\nIt is inspired by the [DHL intraship gem](https://github.com/waldher/dhl-intraship) which implements API version 1.0 which is expired.\nThe Dhl::Bcs gem uses [Savon 2](https://github.com/savonrb/savon) to communicate via SOAP with the DHL API.\nThe DHL BCS API is just for standard parcels. If you are looking for shipping of express parcels this gem is not for you.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'dhl-bcs'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install dhl-bcs\n\n## Usage\n\nInitialize a new API client using\n\n```ruby\nclient = Dhl::Bcs.client(config, options)\n```\n\nConfig is the following hash:\n\n```ruby\nconfig = {\n  api_user: 'The user for API BasicAuth', #mandatory\n  api_pwd: 'The password for API BasicAuth', #mandatory\n  user: 'your BCS user name', #mandatory\n  signature: 'Your BCS user password', #mandatory\n  ekp: 'Your DHL EKP (first part of your DHL Account number)', #mandatory\n  participation_number: 'Your DHL participation_number (last two characters of your DHL Account number)' #mandatory\n}\n```\n\nOptions is an optional parameter and can contain the following parameters:\n\n```ruby\noptions = {\n test: true, # If test is set, all API calls go against the DHL test system (defaults to false)\n log: false # If log is set, you get all logging (with request and response XML) to your standard logger. (defaults to true)\n}\n```\n\n### Where do I get all these numbers?\nIf you are confused about all the number and credential stuff here is a short explanation.\n\nDHL uses a customer integration gateway (cig) for its services.\nYou have to register your app first at the developer portal of dhl, define an app_id and get a token for that.\n`api_user` is your app_id and `api_pwd` is the token you get.\nThis is basically needed to communicate with the DHL services.\n\nTo identify as a BCS user you have to give your credentials of the BCS website as `user` and `signature`.\n\nThe billing works with a number (Abrechnungsnummer) with 14 chars that consists of three parts.\nThe first 10 digits are your EKP (Einheitliche Kunden- und Produktnummer) that you get from your DHL contract.\n\nThe next 2 digits are product dependent (Verfahren), so you don't have to specify it, because they are known if you specify a product at the shipment.\n\nThe last 2 chars, the participation_number (Teilnahme-Nummer) can be digits or uppercase characters.\nThis is contract dependent and used to specify billing conditions.\n\n\n### Create shipments\n\nTo create a shipment at DHL you need a sender_address, a receiver_address, and informations about the parcel.\n\n```ruby\nshipment = Dhl::Bcs.build_shipment(\n  shipper: {\n    name: 'Christoph Wagner',\n    company: 'webit! Gesellschaft für neue Medien mbH',\n    street_name: 'Schandauer Straße',\n    street_number: '34',\n    zip: '01309',\n    city: 'Dresden',\n    country_code: 'DE',\n    email: 'wagner@webit.de'\n  },\n  receiver: {\n    name: 'Jane Doe',\n    street_name: 'Willy-Brandt-Straße',\n    street_number: '1',\n    zip: '10557',\n    city: 'Berlin',\n    country_code: 'DE',\n    email: 'jane.doe@example.com'\n  },\n  weight: 3.5,\n  length: 10,\n  width: 20,\n  height: 30,\n  shipment_date: Date.new(2016, 7, 13)\n)\n\nclient.create_shipment_order(shipment)\n```\n\nYou will get a result that looks like this:\n\n```ruby\n[\n  {\n    status: { status_code: '0', status_text: 'ok', status_message: 'Der Webservice wurde ohne Fehler ausgeführt.' },\n    shipment_number: '22222222201019582121',\n    label_url: 'https://cig.dhl.de/gkvlabel/SANDBOX/dhl-vls/gw/shpmntws/printShipment?token=JD7HKktuvugIFEkhSvCfbEz4J8Ah0dkcVuw4PzBGRyRnW%2FwEPAwfytLtb31e7gMDsSX32%2BEB5exp8nNPs%2FhJSQ%3D%3D',\n  }\n]\n```\n\nThis is an Array of Hashes, cause it is possible to send up to 30 parcels at the same time, with the API.\nSay you want to send 3 parcels to the same address you can also do something like that:\n\n```ruby\nshipper = Dhl::Bcs.build_shipper(\n  name: 'Christoph Wagner',\n  company: 'webit! Gesellschaft für neue Medien mbH',\n  street_name: 'Schandauer Straße',\n  street_number: '34',\n  zip: '01309',\n  city: 'Dresden',\n  country_code: 'DE',\n  email: 'wagner@webit.de'\n)\n\nreceiver = Dhl::Bcs.build_receiver(\n  name: 'Jane Doe',\n  street_name: 'Willy-Brandt-Straße',\n  street_number: '1',\n  zip: '10557',\n  city: 'Berlin',\n  country_code: 'DE',\n  email: 'jane.doe@example.com'\n)\n\nshipment1 = Dhl::Bcs.build_shipment(shipper: shipper, receiver: receiver, weight: 3)\nshipment2 = Dhl::Bcs.build_shipment(shipper: shipper, receiver: receiver, weight: 3.5)\nshipment3 = Dhl::Bcs.build_shipment(shipper: shipper, receiver: receiver, weight: 4)\n\nclient.create_shipment_order(shipment1, shipment2, shipment3)\n```\n### International Shipments\n\nIn order to send parcels outside of the EU, one should provide information about the content of the shipment.   \nDhl offers cn23 document, which is data for the Customs as this kind of shipment is considered Export of goods.\nAs an output one gets, in addition to the label, a url for the document in an A4-format ready to be printed.\n\nThe way to implement that is identical of shipper's and receiver's ones.\n\n```ruby\nexport_document = {\n  invoice_number = 'ABCDEF...',\n  export_type = 'Document',  #  could be one of these ['RETURN_OF_GOODS','PRESENT','COMMERCIAL_SAMPLE','DOCUMENT','OTHER']\n  export_type_description = 'some desc', # should be set if `export_type` was set to 'OTHER'\n  terms_of_trade = 'DDP', # could be one of these ['DDP','DXV','DDU','DDX']\n  place_of_commital= 'Bern',\n  permit_number = 1232135,\n  attestation_number = 1234345,\n  with_electronic_export_notification = true, # true|false\n  export_doc_positions: [\n    {\n      description: 'content1',\n      country_code_origing: 'CN',\n      customs_tariff_number: '1234567',\n      ammount: 1,\n      net_weight_in_kg: 0.2,\n      customs_value: 25.00\n    },\n    {\n      description: 'content2',\n      country_code_origing: 'DE',\n      customs_tariff_number: '00222011',\n      ammount: 1,\n      net_weight_in_kg: 1.2,\n      customs_value: 112.00\n    }\n  ]\n}\n\nshipment = Dhl::Bcs.build_shipment(export_document: export_document, shipper: shipper, receiver: receiver)\n```\n\nand then one gets a result like this:\n\n```ruby\n[\n  {\n    status: { status_code: '0', status_text: 'ok', status_message: 'Der Webservice wurde ohne Fehler ausgeführt.' },\n    shipment_number: '22222222201019582121',\n    label_url: 'https://cig.dhl.de/gkvlabel/SANDBOX/dhl-vls/gw/shpmntws/printShipment?token=JD7HKktuvugIFEkhSvCfbEz4J8Ah0dkcVuw4PzBGRyRnW%2FwEPAwfytLtb31e7gMDsSX32%2BEB5exp8nNPs%2FhJSQ%3D%3D',\n    export_label_url: 'https://cig.dhl.de/gkvlabel/SANDBOX/dhl-vls/gw/shpmntws/printShipment?token=Vfov%2BMinVhMH6nQVfvSCmNUSRNnaQNHKPaiLiWtXsqm%2BENCM6wnStB2C44rl6BEmSxbrPeaTQwBhoHBr802FnuftGVJ9uVM0C0ztLpxNfyc%3D',\n  }\n]\n```\n\n### Validate shipments\n\n```ruby\nclient.validate_shipment(shipment1, shipment2, shipment3)\n```\n\n### Update shipment\n\nYou can update a shipment at DHL. It is the same like deleting it and creating a new one just with one request.\nSo you will get a new shipping number for it and so on.\nTo update a shipment you need the shipment number of the old one and give a complete new shipment that is created instead.\nThis works for one shipment at a time.\n```ruby\nclient.update_shipment_order('22222222901010000944', shipment)\n```\n\n### Other methods\n\nThe methods `delete_shipment_order`, `get_label`, `get_export_doc` and `do_manifest` works technically the same.\nThey took one or many (up to 30) shipment numbers and do something with these shipments at DHL.\n\nTo delete a shipment you can use:\n```ruby\nclient.delete_shipment_order('22222222901010000944')\n```\n\nAs result you will get one Hash like:\n```ruby\n{\n  '22222222901010000944' =\u003e {\n    status: { status_code: '0', status_text: 'ok', status_message: nil }\n  }\n}\n```    \n\n### Services\n\nThere is a basic support to add Services to a shipment in this gem.\n\n```ruby\nshipment.services \u003c\u003c Dhl::Bcs.build_service(name: 'IndividualSenderRequirement', attributes: { active: '1', details: 'Test' })\n```\n\nA service has a name and attributes.\nSometimes a service has children, for example the 'IdentCheck'-Service.\n\n```ruby\nshipment.services \u003c\u003c Dhl::Bcs.build_service(name: 'IdentCheck', attributes: { active: '1' }, children: { 'Ident' =\u003e { surname: 'Doe', given_name: 'Jon Doe', date_of_birth: '1980-12-24', minimum_age: '18' } })\n```\n\nCheck out the DHL developer documentation to configure the services you need.\n\n### Get API version\n\n```ruby\nclient.get_version\n```\nYou don't need a shipment for that.\n\n### Logging\n\nIf you need the last made request and its response from the client you can use:\n```ruby\nclient.last_log\n```\nThis works even if you used the option `log: false` at the client. This option controlls just the output in the log file or console.\n\n### Everything else\nHave a deeper look at the code of this gem and find out how things work.\nYou can help to implement missing things or extend this documentation.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo 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](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/webit-de/dhl-bcs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebit-de%2Fdhl-bcs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebit-de%2Fdhl-bcs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebit-de%2Fdhl-bcs/lists"}