dhl-ecommerce 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9fdcd2715365cddaefd2c83251042ead98c90bc4
+  data.tar.gz: cd2b1f3aa0c60ded06018d0061a62fe4cb6b0b74
+SHA512:
+  metadata.gz: 171ad8b6de6315759b2bda5af0addc55c32d031070ad5e2067013de9136d7cf7b0594826411d9e34fac36431240cc7eea41e77983554b8b1766166d4ceba0f11
+  data.tar.gz: 5eb55a54b412c6e6a34129b97dc979b53051c7c2000ece228e742fc3a934e415122352532fa4dce376078dbda397daf4fbbf33b353a015dd714bf9ae47886aaa

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 meowbox Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+# DHL eCommerce API Wrapper for Ruby
+
+[![Build Status](https://travis-ci.org/meowbox/dhl-ecommerce-ruby.svg)](https://travis-ci.org/meowbox/dhl-ecommerce-ruby)
+
+## Installation
+
+Installation is as simple at adding the following to your `Gemfile`.
+
+```ruby
+gem "dhl-ecommerce"
+```
+
+## Configuration
+
+The only configuration necessary is your `client_id` and either a `username`
+and `password` or an `access_token`.
+
+```ruby
+# DHL e-Commerce configuration.
+DHL::Ecommerce.configure do |config|
+  config.username = "meowbox"
+  config.password = "password"
+  config.client_id = 6369
+
+  # Label format can be either :png or :zpl.
+  config.label_format = :png
+end
+```
+
+## Usage
+
+### Accounts
+
+```ruby
+# Find all accounts.
+accounts = DHL::Ecommerce::Account.all
+
+# Find a particular account.
+account = DHL::Ecommerce::Account.find 6369
+```
+
+### Locations
+
+```ruby
+# Find all locations.
+locations = DHL::Ecommerce::Location.all
+
+# Find a particular location.
+location = DHL::Ecommerce::Location.find 6369
+```
+
+It's also possible to obtain a list of locations from an account by calling the
+`locations` method.
+
+### Labels
+
+```ruby
+# Create the consignee's address.
+consignee_address = DHL::Ecommerce::StandardAddress.new firm: "meowbox Inc.",
+                                                        address_1: "816 PEACE PORTAL DR",
+                                                        address_2: "STE 103",
+                                                        city: "BLAINE",
+                                                        postal_code: "98230",
+                                                        state: "WA",
+                                                        country: "US"
+
+# Create a single label.
+label = DHL::Ecommerce::Label.create consignee_address: consignee_address,
+                                     facility: :auburn,
+                                     location_id: 6369,
+                                     product_id: 83,
+                                     weight: 1
+```
+
+The `file` method of any valid label object will return a `StringIO` object
+containing either the PNG or ZPL representation of the label depending on your
+configuration.
+
+It's also possible to create multiple labels at once by passing an array of
+attributes to the `create` method.
+
+```ruby
+# Create multiple labels.
+labels = DHL::Ecommerce::Label.create [ label_attributes_1, label_attributes_2 ]
+```
+
+### Manifests
+
+Unlike other models, the `create` method will always return an array of
+`Manifest` objects – that's because the DHL e-Commerce API will return a
+manifest for each location and/or facility.
+
+```ruby
+# Create manifests
+manifests = DHL::Ecommerce::Manifest.create labels
+```
+
+### Tracking
+
+```ruby
+# Find events for a particular label.
+events = DHL::Ecommerce::Label.find("420000000000000001").events
+```
+
+### Other models
+
+A few supporting models are also available.
+
+- `Event`
+- `Imbp`
+- `Product`
+- `StandardAddress`

data/lib/dhl-ecommerce.rb

@@ -0,0 +1,89 @@
+require "builder"
+require "faraday"
+require "faraday_middleware"
+require "faraday_middleware/response/rashify"
+require "hashie"
+require "multi_xml"
+require "rash"
+
+# Errors
+require "dhl/ecommerce/errors/base_error"
+require "dhl/ecommerce/errors/authentication_error"
+require "dhl/ecommerce/errors/validation_error"
+
+# Operations
+require "dhl/ecommerce/operations/find"
+require "dhl/ecommerce/operations/list"
+
+# Resources
+require "dhl/ecommerce/base"
+require "dhl/ecommerce/account"
+require "dhl/ecommerce/event"
+require "dhl/ecommerce/impb"
+require "dhl/ecommerce/label"
+require "dhl/ecommerce/location"
+require "dhl/ecommerce/manifest"
+require "dhl/ecommerce/product"
+require "dhl/ecommerce/standard_address"
+require "dhl/ecommerce/tracked_event"
+
+# Version
+require "dhl/ecommerce/version"
+
+module DHL
+  module Ecommerce
+    @access_token = ENV["DHL_ECOMMERCE_ACCESS_TOKEN"]
+    @client_id = ENV["DHL_ECOMMERCE_CLIENT_ID"]
+    @password = ENV["DHL_ECOMMERCE_PASSWORD"]
+    @username = ENV["DHL_ECOMMERCE_USERNAME"]
+    @label_format = :png
+
+    class << self
+      attr_accessor :client_id, :label_format
+      attr_writer :access_token, :password, :username
+
+      def configure
+        yield self
+      end
+    end
+
+    def self.access_token
+      # TODO This needs better error handling.
+      @access_token ||= client.get("https://api.dhlglobalmail.com/v1/auth/access_token", username: @username, password: @password, state: Time.now.to_i).body.response.data[:access_token]
+    end
+
+    def self.request(method, url, &block)
+      client.params = {
+        access_token: self.access_token,
+        client_id: client_id
+      }
+
+      response = client.run_request method.downcase.to_sym, url, nil, nil, &block
+
+      puts response.to_yaml
+
+      case response.status
+      when 400
+        case response.body.response.meta.error.error_type
+        when "INVALID_CLIENT_ID", "INVALID_KEY", "INVALID_TOKEN", "INACTIVE_KEY"
+          throw Errors::AuthenticationError.new response.body.response.meta.error.error_message, response
+        when "VALIDATION_ERROR", "INVALID_FACILITY_CODE"
+          throw Errors::ValidationError.new response.body.response.meta.error.error_message, response
+        else
+          throw Errors::BaseError.new response.body.response.meta.error.error_message, response
+        end
+      end
+
+      response.body.response.data
+    end
+
+    private
+      def self.client
+        @client ||= Faraday.new url: "https://api.dhlglobalmail.com/v1/", headers: { accept: "application/xml", content_type: "application/xml;charset=UTF-8" } do |c|
+          c.response :rashify
+          c.response :xml, :content_type => /\bxml$/
+          c.adapter :net_http
+        end
+      end
+  end
+end

data/lib/dhl/ecommerce/account.rb

@@ -0,0 +1,30 @@
+module DHL
+  module Ecommerce
+    class Account < Base
+      include DHL::Ecommerce::Operations::Find
+      include DHL::Ecommerce::Operations::List
+
+      attr_reader :id, :address, :email
+
+      def initialize(attributes = {})
+        super attributes
+
+        unless attributes.empty?
+          @id = attributes[:account].to_i if attributes[:account]
+          @address = StandardAddress.new attributes
+        end
+      end
+
+      def locations
+        response = DHL::Ecommerce.request :get, "https://api.dhlglobalmail.com/v1/#{self.resource_name.downcase}s/#{id}/#{DHL::Ecommerce::Location.resource_name.downcase}s"
+        response[self.resource_name]["#{DHL::Ecommerce::Location.resource_name}s"][DHL::Ecommerce::Location.resource_name] = [response[self.resource_name]["#{DHL::Ecommerce::Location.resource_name}s"][DHL::Ecommerce::Location.resource_name]] unless response[self.resource_name]["#{DHL::Ecommerce::Location.resource_name}s"][DHL::Ecommerce::Location.resource_name].is_a? Array
+
+        response[self.resource_name]["#{DHL::Ecommerce::Location.resource_name}s"].map do |attributes|
+          location = DHL::Ecommerce::Location.new attributes
+          location.instance_variable_set :@account, self
+          location
+        end
+      end
+    end
+  end
+end

data/lib/dhl/ecommerce/base.rb

@@ -0,0 +1,22 @@
+module DHL
+  module Ecommerce
+    class Base
+      def initialize(attributes = {})
+        attributes.each do |attribute, value|
+          next if attribute.to_sym == :class
+
+          if respond_to? "#{attribute}="
+            send "#{attribute}=", value
+          elsif respond_to?("#{attribute}")
+            instance_variable_set "@#{attribute}", value
+          end
+        end unless attributes.empty?
+      end
+
+      private
+        def self.resource_name
+          self.name.split("::").last
+        end
+    end
+  end
+end

data/lib/dhl/ecommerce/errors/authentication_error.rb

@@ -0,0 +1,8 @@
+module DHL
+  module Ecommerce
+    module Errors
+      class AuthenticationError < BaseError
+      end
+    end
+  end
+end

data/lib/dhl/ecommerce/errors/base_error.rb

@@ -0,0 +1,15 @@
+module DHL
+  module Ecommerce
+    module Errors
+      class BaseError < StandardError
+        attr_reader :response
+
+        def initialize(message = nil, response = nil)
+          super message
+
+          @response = response
+        end
+      end
+    end
+  end
+end

data/lib/dhl/ecommerce/errors/validation_error.rb

@@ -0,0 +1,8 @@
+module DHL
+  module Ecommerce
+    module Errors
+      class ValidationError < BaseError
+      end
+    end
+  end
+end

data/lib/dhl/ecommerce/event.rb

@@ -0,0 +1,18 @@
+module DHL
+  module Ecommerce
+    class Event < Base
+      include DHL::Ecommerce::Operations::Find
+      include DHL::Ecommerce::Operations::List
+
+      attr_reader :id, :description
+
+      def initialize(attributes = {})
+        super attributes
+
+        unless attributes.empty?
+          @description.upcase! if @description
+        end
+      end
+    end
+  end
+end

data/lib/dhl/ecommerce/impb.rb

@@ -0,0 +1,7 @@
+module DHL
+  module Ecommerce
+    class Impb < Base
+      attr_accessor :construct, :value
+    end
+  end
+end

data/lib/dhl/ecommerce/label.rb

@@ -0,0 +1,250 @@
+module DHL
+  module Ecommerce
+    class Label < Base
+      attr_accessor :customer_confirmation_number, :service_endorsement, :reference, :batch, :mail_type, :facility, :expected_ship_date, :weight, :consignee_address, :return_address, :service
+      attr_reader :id, :location_id, :product_id, :events, :service_type, :file, :impb
+
+      FACILITIES = {
+        auburn: "USSEA1",
+        compton: "USLAX1",
+        denver: "USDEN1",
+        edgewood: "USISP1",
+        elkridge: "USBWI1",
+        forest_park: "USATL1",
+        franklin: "USBOS1",
+        grand_prairie: "USDFW1",
+        hebron: "USCVG1",
+        melrose_park: "USORD1",
+        memphis: "USMEM1",
+        orlando: "USMCO1",
+        phoenix: "USPHX1",
+        salt_lake_city: "USSLC1",
+        secaucus: "USEWR1",
+        st_louis: "USSTL1",
+        union_city: "USSFO1"
+      }
+
+      MAIL_TYPES = {
+        bound_printed_matter: 6,
+        irregular_parcel: 2,
+        machinable_parcel: 3,
+        marketing_parcel_gte_6oz: 30,
+        marketing_parcel_lt_6oz: 20,
+        media_mail: 9,
+        parcel_select_machinable: 7,
+        parcel_select_nonmachinable: 8
+      }
+
+      SERVICES = {
+        delivery_confirmation: "DELCON",
+        signature_confirmation: "SIGCON"
+      }
+
+      SERVICE_ENDORSEMENTS = {
+        address_service: 1,
+        change_service: 3,
+        forwarding_service: 2,
+        return_service: 4
+      }
+
+      def location_id=(location_id)
+        @location = nil
+        @location_id = location_id
+      end
+
+      def location
+        @location ||= DHL::Ecommerce::Location.find location_id
+      end
+
+      def location=(location)
+        @location = nil if @location_id != location.id
+        @location_id = location.id
+      end
+
+      def product_id=(product_id)
+        @product = nil
+        @product_id = product_id
+      end
+
+      def product
+        @product ||= DHL::Ecommerce::Product.find product_id
+      end
+
+      def product=(product)
+        @product = nil if @product_id != product.id
+        @product_id = product.id
+      end
+
+      def self.create(attributes)
+        array = attributes.is_a? Array
+        attributes = [attributes] unless array
+
+        labels = self.create_in_batches attributes
+
+        array ? labels : labels.first
+      end
+
+      def self.find(id)
+        attributes = DHL::Ecommerce.request :get, "https://api.dhlglobalmail.com/v1/mailitems/track" do |request|
+          request.params[:number] = id
+        end
+
+        attributes[:mail_items][:mail_item] = attributes[:mail_items][:mail_item].first if attributes[:mail_items][:mail_item].is_a? Array
+
+        new attributes[:mail_items][:mail_item]
+      end
+
+      def initialize(attributes = {})
+        super attributes
+
+        unless attributes.empty?
+          if attributes[:mail]
+            @id = attributes[:mail][:mailIdentifier] if attributes[:mail][:mailIdentifier]
+            @weight = attributes[:mail][:weight] if attributes[:mail][:weight]
+            @product_id = attributes[:mail][:product_id] if attributes[:mail][:product_id]
+            @reference = attributes[:mail][:customer_reference] if attributes[:mail][:customer_reference]
+            @batch = attributes[:mail][:batch_reference] if attributes[:mail][:batch_reference]
+            @impb = attributes[:mail][:intelligent_mail_barcode] if attributes[:mail][:intelligent_mail_barcode]
+            @customer_confirmation_number = attributes[:mail][:customer_confirmation_number] if attributes[:mail][:customer_confirmation_number]
+
+            @services = :delivery_confirmation if attributes[:mail][:delivery_confirmation_flag] == '1'
+            @services = :signature_confirmation if attributes[:mail][:signature_confirmation_flag] == '1'
+          end
+
+          if attributes[:pickup]
+            @location_id = attributes[:pickup][:pickup] if attributes[:pickup][:pickup]
+          end
+
+          if attributes[:recipient]
+            @consignee_address = StandardAddress.new attributes[:recipient]
+          end
+
+          if attributes[:events]
+            @events = []
+
+            attributes[:events][:event] = [attributes[:events][:event]] unless attributes[:events][:event].is_a? Array
+            attributes[:events][:event].each do |event_attributes|
+              event = TrackedEvent.new event_attributes
+              event.instance_variable_set :@event, Event.new(event_attributes)
+
+              @events << event
+            end
+          end
+        end
+      end
+
+      private
+
+      def xml
+        xml = Builder::XmlMarkup.new
+        xml.Mpu do
+          xml.PackageId customer_confirmation_number
+
+          xml.PackageRef do
+            xml.PrintFlag customer_confirmation_number.present?
+            # xml.LabelText ""
+          end
+
+          xml.ConsigneeAddress do
+            xml.StandardAddress do
+              xml.Name consignee_address.name
+              xml.Firm consignee_address.firm
+              xml.Address1 consignee_address.address_1
+              xml.Address2 consignee_address.address_2
+              xml.City consignee_address.city
+              xml.State consignee_address.state.to_s.upcase
+              xml.Zip consignee_address.postal_code
+              xml.CountryCode consignee_address.country.to_s.upcase
+            end
+          end
+
+          xml.ReturnAddress do
+            xml.StandardAddress do
+              xml.Name return_address.name
+              xml.Firm return_address.firm
+              xml.Address1 return_address.address_1
+              xml.Address2 return_address.address_2
+              xml.City return_address.city
+              xml.State return_address.state.to_s.upcase
+              xml.Zip return_address.postal_code
+              xml.CountryCode return_address.country.to_s.upcase
+            end
+          end if return_address
+
+          xml.OrderedProductCode product_id
+          xml.Service SERVICES.fetch service.downcase.to_sym if service
+          xml.ServiceEndorsement SERVICE_ENDORSEMENTS.fetch service_endorsement.downcase.to_sym if service_endorsement
+
+          # xml.DgCategory ""
+          # xml.ContactPhoneNumber ""
+
+          xml.Weight do
+            xml.Value weight
+
+            # TODO Add support for other units supported by DHL e-Commerce.
+            xml.Unit :lb.to_s.upcase
+          end
+
+          xml.BillingRef1 reference
+          xml.BillingRef2 batch
+          xml.FacilityCode FACILITIES.fetch facility.downcase.to_sym if facility
+          xml.ExpectedShipDate (expected_ship_date || DateTime.now).strftime("%Y%m%d")
+          xml.MailTypeCode MAIL_TYPES.fetch mail_type ? mail_type.downcase.to_sym : :parcel_select_machinable
+        end
+      end
+
+      def self.create_in_batches(attributes)
+        attributes.group_by do |value| value[:location_id] end.each.collect do |location_id, location_attributes|
+          case DHL::Ecommerce.label_format
+          when :png, :image
+            url = "https://api.dhlglobalmail.com/v1/#{self.resource_name.downcase}/US/#{location_id}/image"
+          when :zpl
+            url = "https://api.dhlglobalmail.com/v1/#{self.resource_name.downcase}/US/#{location_id}/zpl"
+          end
+
+          location_attributes.each_slice(500).collect do |slice|
+            labels = slice.map do |slice_attributes|
+              new slice_attributes
+            end
+
+            xml = Builder::XmlMarkup.new
+            xml.instruct! :xml, version: "1.1", encoding: "UTF-8"
+            xml.EncodeRequest do
+              xml.CustomerId location_id
+              xml.BatchRef DateTime.now.strftime("%Q")
+              xml.HalfOnError false
+              xml.RejectAllOnError true
+              xml.MpuList do
+                xml << labels.map do |label| label.send :xml end.join
+              end
+            end
+
+            response = DHL::Ecommerce.request :post, url do |request|
+              request.body = xml.target!
+            end
+
+            response[:mpu_list][:mpu] = [response[:mpu_list][:mpu]] unless response[:mpu_list][:mpu].is_a? Array
+
+            labels.zip(response[:mpu_list][:mpu]).map do |label, label_response|
+              label.instance_variable_set :@id, label_response[:mail_item_id].to_i if label_response[:mail_item_id]
+
+              case DHL::Ecommerce.label_format
+              when :png, :image
+                label.instance_variable_set :@file, StringIO.new(Base64.decode64(label_response[:label_image])) if label_response[:label_image]
+              when :zpl
+                label.instance_variable_set :@file, StringIO.new(Base64.decode64(label_response[:label_zpl])) if label_response[:label_zpl]
+              end
+
+              if label_response[:label_detail]
+                label.instance_variable_set :@impb, Impb.new(label_response[:label_detail][:impb]) if label_response[:label_detail][:impb]
+                label.instance_variable_set :@service_type, label_response[:label_detail][:service_type_code].to_i if label_response[:label_detail][:service_type_code]
+              end
+
+              label
+            end
+          end
+        end.flatten
+      end
+    end
+  end
+end