dhl_ecommerce_api 0.1.0

data/lib/dhl_ecommerce_api/resources/pickup.rb

@@ -0,0 +1,90 @@
+module DHLEcommerceAPI
+  class Pickup < Base
+    # This is a one-off pickup request. 
+    # It simply tells DHL to pickup items from the shipper_details address.
+    # Used in conjunction with the Shipment::Dropoff class. 
+
+    self.prefix = "/rest/v2/Order/Shipment/Pickup"
+    self.element_name = ""
+    
+    def create
+      run_callbacks :create do
+        connection.post(collection_path, formatted_request_data(pickup_request), self.class.headers).tap do |response|
+          load_attributes_from_response(response)
+        end
+      end
+    end
+
+    def load_attributes_from_response(response)
+      if response_code_allows_body?(response.code.to_i) &&
+          (response["Content-Length"].nil? || response["Content-Length"] != "0") &&
+          !response.body.nil? && response.body.strip.size > 0
+        
+        bd = self.class.format.decode(response.body)["bd"]
+        response_status = bd["responseStatus"]
+        code = response_status["code"]
+
+        if code == "200"
+          @persisted = true
+        elsif code == "204"
+          # handle partial success
+          @persisted = false
+        else
+          error_messages = response_status["messageDetails"].map{|err| err["messageDetail"]}
+          handle_errors(code, error_messages)
+          @persisted = false
+        end
+
+        new_attributes = attributes.merge(bd)
+        load(new_attributes, true, @persisted)
+      end
+    end
+
+    def pickup_request
+      {
+        pickup_request: {
+          hdr: headers,
+          bd: attributes_with_account_ids.deep_transform_keys {|key| key.to_s.underscore.to_sym }
+        }
+      }
+    end
+    
+    def headers
+      {
+        message_type: "PICKUP",
+        message_date_time: DateTime.now.to_s,
+        access_token: DHLEcommerceAPI::Authentication.get_token,
+        message_version: "1.2"
+      }
+    end
+  end
+end
+
+# example_pickup_params = {
+#   "handover_items": [
+#     {
+#       "pickup_date": "2022-03-09",
+#       "pickup_start_time": "09:00",
+#       "pickup_end_time": "18:00",
+#       "shipment_type": "1",
+#       "notification_email": nil,
+#       "shipper_details": {
+#         "company": "PostCo",
+#         "name": "PostCo",
+#         "email_id": nil,
+#         "phone_number": "0169822645",
+#         "address_line_1": "no 26 jalan 31/123, petaling jaya",
+#         "address_line_2": nil,
+#         "address_line_3": nil,
+#         "city": "Kuala Lumpur",
+#         "state": "Kuala Lumpur",
+#         "postal_code": "57000",
+#         "country": "MY",
+#       },
+#       "shipments": {
+#         "quantity": 1,
+#         "totalWeight": 100
+#       }
+#     }
+#   ]
+# }

data/lib/dhl_ecommerce_api/resources/shipment/dropoff.rb

@@ -0,0 +1,50 @@
+module DHLEcommerceAPI
+  class Shipment::Dropoff < Shipment
+    # This creates a Shipment ONLY. 
+    # DHL will expect the item to be dropped off at one of their locations.
+    # Used in conjunction with the Pickup class.
+
+    self.element_name = ""
+
+    DEFAULT_ATTRIBUTES = {
+      handover_method: 1,
+      shipment_items: []
+    }
+  end
+end
+
+# shipment_with_dropoff_params = {
+#   "shipment_items" => [
+#     { 
+#       "consignee_address" => { 
+#         "company_name" => "Test",
+#         "name" => "Test1",
+#         "address1" => "NO 3 JALAN PPU 1",
+#         "address2" => "TAMAN PERINDUSTRIAN PUCHONG UTAMA",
+#         "address3" => nil,
+#         "city" => "PUCHONG",
+#         "state" => "SELANGOR",
+#         "district" => nil,
+#         "country" => "MY",
+#         "post_code" => "57000",
+#         "phone" => "0123456798",
+#         "email" => nil 
+#       },
+#       "shipment_id" => "MYPTC000103",
+#       "package_desc" => "Bread Materials",
+#       "total_weight" => 2000,
+#       "total_weight_uom" => "G",
+#       "dimension_uom" => "CM",
+#       "height" => nil,
+#       "length" => nil,
+#       "width" => nil,
+#       "product_code" => "PDO",
+#       "cod_value" => nil,
+#       "insurance_value" => nil,
+#       "total_value" => 300,
+#       "currency" => "MYR",
+#       "remarks" => nil,
+#       "is_routing_info_required" => "Y" 
+#     }
+#   ],
+# }

data/lib/dhl_ecommerce_api/resources/shipment/pickup.rb

@@ -0,0 +1,79 @@
+module DHLEcommerceAPI
+  class Shipment::Pickup < Shipment
+    # This is a coupled shipment + pickup request.
+
+    self.element_name = ""
+
+    DEFAULT_ATTRIBUTES = {
+      handover_method: 2,
+      pickup_date_time: nil,
+      pickup_address: {
+        company_name: "",
+        name: "",
+        address1: "",
+        address2: nil,
+        address3: nil,
+        city: "",
+        state: "",
+        post_code: "",
+        country: "MY",
+        phone: "",
+        email: nil
+      },
+      shipment_items: []
+    }
+
+    validates_presence_of :pickup_date_time
+  end
+end
+
+# shipment_with_pickup_params = {
+#   "handoverMethod": 2,
+#   "pickupDateTime": DateTime.now.to_s,
+#   "pickupAddress": {
+#     "companyName": "Pickup From Company",
+#     "name": "Pickup From Name",
+#     "address1": "Holistic Pharmacy PostCo, 55, Jalan Landak",
+#     "address2": "",
+#     "address3": "",
+#     "city": " Kuala Lumpur",
+#     "state": " Kuala Lumpur",
+#     "postCode": "55100",
+#     "country": "MY",
+#     "phone": "0169822645",
+#     "email": "erwhey@postco.co"
+#   },
+#   "shipmentItems": [
+#     {
+#       "shipmentID": "MYPTC0087",
+#       "packageDesc": "Laptop Sleeve",
+#       "totalWeight": 500,
+#       "totalWeightUOM": "G",
+#       "dimensionUOM": "CM",
+#       "height": nil,
+#       "length": nil,
+#       "width": nil,
+#       "productCode": "PDO",
+#       "codValue": nil,
+#       "insuranceValue": nil,
+#       "totalValue": 300,
+#       "currency": "MYR",
+#       "remarks": nil,
+#       "isRoutingInfoRequired": "Y",
+#       "consigneeAddress": {
+#         "companyName": "Sleeve Company",
+#         "name": "Sleeve Sdn Bhd",
+#         "address1": "No. 3, Jalan Bangsar, Kampung Haji Abdullah Hukum",
+#         "address2": nil,
+#         "address3": nil,
+#         "city": "Kuala Lumpur",
+#         "state": "Kuala Lumpur",
+#         "district": nil,
+#         "country": "MY",
+#         "postCode": "59200",
+#         "phone": "0169822645",
+#         "email": nil
+#       }
+#     },
+#   ]
+# }

data/lib/dhl_ecommerce_api/resources/shipment/shipment_item.rb

@@ -0,0 +1,46 @@
+module DHLEcommerceAPI
+  # Component item
+  class Shipment::ShipmentItem < Base
+    # add some validations?
+    DEFAULT_ATTRIBUTES = { 
+      shipment_id: nil,
+      package_desc: "",
+      total_weight: nil,
+      total_weight_uom: "G",
+      dimension_uom: "CM",
+      height: nil,
+      length: nil,
+      width: nil,
+      product_code: "PDO",
+      cod_value: nil,
+      insurance_value: nil,
+      total_value: 300,
+      currency: "MYR",
+      remarks: nil,
+      is_routing_info_required: "Y",
+      consignee_address: { 
+        company_name: "",
+        name: "",
+        address1: "",
+        address2: nil,
+        address3: nil,
+        city: "",
+        state: "",
+        district: nil,
+        country: "MY",
+        post_code: "",
+        phone: "",
+        email: nil 
+      }
+    }
+
+    def initialize(attributes = {}, persisted = false)
+      status = attributes["response_status"]
+      if status.present? && status["code"] != "200"
+        error_messages = status["message_details"].map{|err| err["message_detail"]}
+        handle_errors(status["code"], error_messages) 
+      end
+      super
+    end
+  end
+end

data/lib/dhl_ecommerce_api/resources/shipment.rb

@@ -0,0 +1,154 @@
+module DHLEcommerceAPI
+  class Shipment < Base
+    # Base Shipment class
+    # info returned - delivery_confirmation_no, delivery_depot_code, primary_sort_code, secondary_sort_code
+
+    self.prefix = "/rest/v3/Shipment"
+    self.element_name = ""
+    
+    has_many :shipment_items, class_name: "DHLEcommerceAPI::Shipment::ShipmentItem"
+    
+    validates_presence_of :handover_method
+
+    def create
+      run_callbacks :create do
+        data = formatted_request_data(manifest_request)
+        connection.post(collection_path, data, self.class.headers).tap do |response|
+          load_attributes_from_response(response)
+        end
+      end
+    end
+
+    def load_attributes_from_response(response)
+      if response_code_allows_body?(response.code.to_i) &&
+          (response["Content-Length"].nil? || response["Content-Length"] != "0") &&
+          !response.body.nil? && response.body.strip.size > 0
+        
+        bd = self.class.format.decode(response.body)["bd"]
+        response_status = bd["responseStatus"]
+        code = response_status["code"]
+
+        if code == "200"
+          @persisted = true
+        elsif code == "204"
+          # handle partial success
+          @persisted = false
+        else
+          error_messages = response_status["messageDetails"].map{|err| err["messageDetail"]}
+          handle_errors(code, error_messages)
+          @persisted = false
+        end
+
+        new_attributes = attributes.merge(bd)
+        load(new_attributes, true, @persisted)
+      end
+    end
+
+    def manifest_request
+      {
+        manifest_request: {
+          hdr: headers,
+          bd: attributes_with_account_ids.deep_transform_keys {|key| key.to_s.underscore.to_sym }
+        }
+      }
+    end
+    
+    def headers
+      {
+        message_type: "SHIPMENT",
+        message_date_time: DateTime.now.to_s,
+        access_token: DHLEcommerceAPI::Authentication.get_token,
+        message_version: "1.0"
+      }
+    end
+  end
+end
+
+# Examples:
+# shipment_with_pickup_params = {
+#   "handoverMethod": 2,
+#   "pickupDateTime": DateTime.now.to_s,
+#   "pickupAddress": {
+#     "companyName": "Pickup From Company",
+#     "name": "Pickup From Name",
+#     "address1": "Holistic Pharmacy PostCo, 55, Jalan Landak",
+#     "address2": "",
+#     "address3": "",
+#     "city": " Kuala Lumpur",
+#     "state": " Kuala Lumpur",
+#     "postCode": "55100",
+#     "country": "MY",
+#     "phone": "0169822645",
+#     "email": "erwhey@postco.co"
+#   },
+#   "shipmentItems": [
+#     {
+#       "shipmentID": "MYPTC0083",
+#       "packageDesc": "Laptop Sleeve",
+#       "totalWeight": 500,
+#       "totalWeightUOM": "G",
+#       "dimensionUOM": "CM",
+#       "height": nil,
+#       "length": nil,
+#       "width": nil,
+#       "productCode": "PDO",
+#       "codValue": nil,
+#       "insuranceValue": nil,
+#       "totalValue": 300,
+#       "currency": "MYR",
+#       "remarks": nil,
+#       "isRoutingInfoRequired": "Y",
+#       "consigneeAddress": {
+#         "companyName": "Sleeve Company",
+#         "name": "Sleeve Sdn Bhd",
+#         "address1": "No. 3, Jalan Bangsar, Kampung Haji Abdullah Hukum",
+#         "address2": nil,
+#         "address3": nil,
+#         "city": "Kuala Lumpur",
+#         "state": "Kuala Lumpur",
+#         "district": nil,
+#         "country": "MY",
+#         "postCode": "59200",
+#         "phone": "0169822645",
+#         "email": nil
+#       }
+#     },
+#   ]
+# }
+
+# shipment_with_dropoff_params = {
+#   "handover_method" => 1,
+#   "shipment_items" => [
+#     { 
+#       "consignee_address" => { 
+#         "company_name" => "Test",
+#         "name" => "Test1",
+#         "address1" => "NO 3 JALAN PPU 1",
+#         "address2" => "TAMAN PERINDUSTRIAN PUCHONG UTAMA",
+#         "address3" => nil,
+#         "city" => "PUCHONG",
+#         "state" => "SELANGOR",
+#         "district" => nil,
+#         "country" => "MY",
+#         "post_code" => "57000",
+#         "phone" => "0123456798",
+#         "email" => nil 
+#       },
+#       "shipment_id" => "MYPTC000102",
+#       "package_desc" => "Bread Materials",
+#       "total_weight" => 2000,
+#       "total_weight_uom" => "G",
+#       "dimension_uom" => "CM",
+#       "height" => nil,
+#       "length" => nil,
+#       "width" => nil,
+#       "product_code" => "PDO",
+#       "cod_value" => nil,
+#       "insurance_value" => nil,
+#       "total_value" => 300,
+#       "currency" => "MYR",
+#       "remarks" => nil,
+#       "is_routing_info_required" => "Y" 
+#     }
+#   ],
+# }

data/lib/dhl_ecommerce_api/resources/tracking.rb

@@ -0,0 +1,88 @@
+module DHLEcommerceAPI
+  class Tracking < Base
+    # example_tracking_params = {
+    #   "e_pod_required": "Y", 
+    #   "trackingReferenceNumber": [
+    #       "MYPTC00012", "MYPTC00013"
+    #   ]
+    # }
+
+    self.prefix = "/rest/v3/Tracking"
+    self.element_name = ""
+    
+    def initialize(attributes = {}, persisted = false)
+      attributes = account_ids.merge(attributes)
+      super
+    end
+
+    def self.find(arguments)
+      tracking = self.new({
+        e_pod_required: "Y",
+        tracking_reference_number: arguments.is_a?(Array) ? arguments : [arguments]
+      })
+      tracking.save
+      return tracking.shipment_items.presence || []
+    end
+
+    def create
+      run_callbacks :create do
+        connection.post(collection_path, formatted_request_data(request_data), self.class.headers).tap do |response|
+          load_attributes_from_response(response)
+        end
+      end
+    end
+
+    def load_attributes_from_response(response)
+      if response_code_allows_body?(response.code.to_i) &&
+          (response["Content-Length"].nil? || response["Content-Length"] != "0") &&
+          !response.body.nil? && response.body.strip.size > 0
+        
+        bd = self.class.format.decode(response.body)["bd"]
+        response_status = bd["responseStatus"]
+        code = response_status["code"]
+
+        if code == "200"
+          @persisted = true
+        elsif code == "204"
+          # handle partial success
+          @persisted = false
+        else
+          error_messages = response_status["messageDetails"].map{|err| err["messageDetail"]}
+          handle_errors(code, error_messages)
+          @persisted = false
+        end
+        
+        new_attributes = attributes.merge(bd)
+        load(new_attributes, true, @persisted)
+      end
+    end
+    
+    def request_data
+      {
+        track_item_request: {
+          hdr: headers,
+          bd: attributes.except("response_status") # dont send responseStatus
+        }
+      }
+    end
+    
+    def headers
+      {
+        message_type: "TRACKITEM",
+        message_date_time: DateTime.now.to_s,
+        access_token: DHLEcommerceAPI::Authentication.get_token,
+        message_version: "1.0"
+      }
+    end
+
+
+    # Since request_data isnt the same as object attributes. 
+    # We have to write our own method to format the request data
+    def formatted_request_data(request_data)
+      request_data.as_json
+        .deep_transform_keys do |key| 
+          custom_key_format(key) # method from Base
+        end.to_json
+    end
+  end
+end

data/lib/dhl_ecommerce_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DHLEcommerceAPI
+  VERSION = "0.1.0"
+end

data/lib/dhl_ecommerce_api.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "dhl_ecommerce_api/version"
+require "active_resource"
+
+module DHLEcommerceAPI
+  require "dhl_ecommerce_api/cache"
+  require "dhl_ecommerce_api/configuration"
+  require "dhl_ecommerce_api/connection"
+  
+  require "dhl_ecommerce_api/resources/base"
+  require "dhl_ecommerce_api/resources/authentication"
+
+  require "dhl_ecommerce_api/resources/shipment"
+  require "dhl_ecommerce_api/resources/pickup"
+
+  require "dhl_ecommerce_api/resources/tracking"
+end

data/sig/dhl_ecommerce_api.rbs

@@ -0,0 +1,4 @@
+module DHLEcommerceAPI
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end