iloxx_shipping 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format progress
+--backtrace

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in iloxx_shipping.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Maximilian Richt (robbi5)
+
+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,82 @@
+# Iloxx::Shipping
+
+This gem is a wrapper around the SOAP-based API provided by [iloxx](http://iloxx.de). It allows you to build and send a shipment request and return a shipping label and the parcel numbers.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'iloxx_shipping'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install iloxx_shipping
+
+## Usage
+
+1. Create a new receiver address:
+
+        receiver = Iloxx::Shipping::Address.new({
+          :name => "Lilly Lox",
+          :street => "Gutenstetter Str. 8b",
+          :zip => "90449",
+          :city => "Nürnberg",
+          :country_code => "DE"
+        })
+
+2. Create a new parcel
+
+        parcel = Iloxx::Shipping::Parcel.new(
+          weight: 1.25,
+          content: "Stones",
+          address: receiver,
+          service: Iloxx::Shipping::NormalpaketService.new,
+          # ^- or use ExpressService or RetoureService (with parameters) instead
+          reference: "Order #1234",
+        )
+
+3. Submit your parcel
+
+        config = {
+          user: "Your Iloxx User ID",
+          token: "Your Iloxx User Token",
+        }
+        api = Iloxx::Shipping::API.new(config, {
+          test: true # If test is set, all API calls go against the test system
+        })
+        shipment_date = Date.today
+        result = api.add_order(parcel, shipment_date)
+
+
+4. Receive the parcel number and label pdf
+
+        result[:shipments].each do |shipment|
+          p shipment[:parcel_number]
+        end
+
+        # base64 encoded label.pdf in result[:label_data] - lets save it to disk:
+
+        f = File.open('label.pdf', 'w')
+        begin
+          f.write Base64.decode64(result[:label_data])
+        ensure
+          f.close unless f.nil?
+        end
+
+
+## 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. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Thanks
+
+* iloxx AG for providing the documentation for their SOAP API
+* [savon](http://github.com/savonrb) for a nice soap abstraction library

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/iloxx_shipping/*_spec.rb'
+  spec.rspec_opts = ['--backtrace']
+end
+
+task :default => :spec
+task :test => :spec

data/iloxx_shipping.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'iloxx_shipping/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "iloxx_shipping"
+  gem.version       = Iloxx::Shipping::VERSION
+  gem.authors       = ["Maximilian Richt"]
+  gem.email         = ["maxi@richt.name"]
+  gem.description   = %q{A simple way to access the iloxx shipping API}
+  gem.summary       = %q{A wrapper around the SOAP-based iloxx shipping web service. Generate a shipping request and get a label back.}
+  gem.homepage      = "https://github.com/robbi5/iloxx_shipping"
+  gem.license       = 'MIT'
+
+  gem.add_dependency "savon", "~> 2.2.0"
+  gem.add_development_dependency "rspec", "~> 2.11.0"
+  gem.add_development_dependency "webmock", "~> 1.13.0"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/iloxx_shipping.rb

@@ -0,0 +1,17 @@
+require 'date'
+require 'savon'
+
+require 'iloxx_shipping/version'
+require 'iloxx_shipping/address'
+require 'iloxx_shipping/request'
+# requests
+require 'iloxx_shipping/order_request'
+require 'iloxx_shipping/daily_transaction_request'
+require 'iloxx_shipping/parcel'
+require 'iloxx_shipping/service'
+# services
+require 'iloxx_shipping/service/express'
+require 'iloxx_shipping/service/normalpaket'
+require 'iloxx_shipping/service/retoure'
+# and the last one:
+require 'iloxx_shipping/api'

data/lib/iloxx_shipping/address.rb

@@ -0,0 +1,48 @@
+module Iloxx
+  module Shipping
+    class Address
+      attr_accessor :company, :sex, :name, :street, :zip, :city, :state, :country_code, :email, :phone
+
+      VALID_SEX = [:NoSexCode, :Male, :Female]
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          setter = :"#{key.to_s}="
+          if self.respond_to?(setter)
+            self.send(setter, value)
+          end
+        end
+      end
+
+      def company?
+        !self.company.blank?
+      end
+
+      def sex=(sex)
+        raise "Sex must be one of the following: #{VALID_SEX.to_s}" unless VALID_SEX.include? sex
+        @sex = sex
+      end
+
+      def country_code=(country_code)
+        raise "Country code must be an ISO-3166 two digit code" unless country_code.length == 2
+        @country_code = country_code
+      end
+
+      def append_to_xml(xml)
+        xml.tns :ShipAddress do |xml|
+          xml.tns :Company, company if company?
+          xml.tns :SexCode, sex || :NoSexCode
+          xml.tns :Name, name
+          xml.tns :Street, street
+          xml.tns :ZipCode, zip
+          xml.tns :City, city
+          xml.tns :State, state || ""
+          xml.tns :Country, country_code
+          xml.tns :Phone, phone || ""
+          xml.tns :Mail, email || ""
+        end
+      end
+
+    end
+  end
+end

data/lib/iloxx_shipping/api.rb

@@ -0,0 +1,146 @@
+# encoding: UTF-8
+module Iloxx
+  module Shipping
+    class PartnerAuthenticationError < StandardError; end
+    class AuthenticationError < StandardError; end
+    class ShippingDateError < StandardError; end
+
+    class APIErrorCodes
+      PARTNER_AUTH_ERROR = 3 # Ungültige Zugangsdaten (PartnerCredentials).
+      AUTH_ERROR = 4 # Ungültige Zugangsdaten oder Nutzung des Services ist nicht freigegeben.
+    end
+
+    class API
+      DEFAULT_NAMESPACES = {
+        "xmlns:iloxx" => "http://iloxx.de/"
+      }
+
+      PPVAPI_WSDL = "https://www.iloxx.de/iloxxapi/ppvapi.asmx?WSDL"
+      PPVAPI_ENDPOINT = "https://www.iloxx.de/iloxxapi/ppvapi.asmx"
+
+      PPVAPI_TEST_WSDL = "http://qa.www.iloxx.de/iloxxapi/ppvapi.asmx?WSDL"
+      PPVAPI_TEST_ENDPOINT = "http://qa.www.iloxx.de/iloxxapi/ppvapi.asmx"
+
+      API_VERSION = 102
+
+      def initialize(config, options = {})
+        raise "User ID must be specified" if config[:user].nil?
+        raise "User Token must be specified" if config[:token].nil?
+
+        if options[:test]
+          wsdl_url = PPVAPI_TEST_WSDL
+          endpoint = PPVAPI_TEST_ENDPOINT
+        else
+          wsdl_url = PPVAPI_WSDL
+          endpoint = PPVAPI_ENDPOINT
+        end
+
+        @user = config[:user]
+        @token = config[:token]
+        @partner_name = config[:partner_name] || 'iloxx.24'
+        @partner_key = config[:partner_key] || '554F346F592B42757131367A64477A7A676362767A413D3D'
+
+        @options = options
+        @client = ::Savon::Client.new do |sc|
+          sc.wsdl wsdl_url
+          sc.endpoint endpoint
+          sc.namespace DEFAULT_NAMESPACES['xmlns:iloxx']
+          sc.soap_version 2
+          sc.filters [:LabelPDFStream, :UserToken]
+        end
+      end
+
+      def add_order(parcels, date = nil)
+        shipping_date = date || Date.today
+
+        if shipping_date > Date.today + 7
+          raise ShippingDateError.new('Invalid shipping date. Min: today, max: +7 days')
+        end
+
+        if !parcels.is_a? Array
+          parcels = [parcels]
+        end
+        parcels.each do |p|
+          p.internal_reference = parcels.index p
+        end
+
+        request = OrderRequest.new(
+          :version => API_VERSION,
+          :auth => auth_hash,
+          :shipping_date => shipping_date,
+          :parcels => parcels
+        )
+        response = @client.call(:ppv_add_order, message: request.build!)
+
+        result = response.body[:ppv_add_order_response][:ppv_add_order_result]
+        if result[:ack] == 'Success'
+          shipments = []
+          if !result[:response_data_array].is_a? Array
+            result[:response_data_array] = [result[:response_data_array][:response_data]]
+          end
+          result[:response_data_array].each { |rdata| shipments << rdata }
+          {
+            :label_data => result[:label_pdf_stream],
+            :shipments => shipments
+          }
+        else
+          handle_errors result
+        end
+      end
+
+      def get_daily_transaction_list(date = nil)
+        shipping_date = date || Date.today
+
+        request = DailyTransactionRequest.new(
+          :version => API_VERSION,
+          :auth => auth_hash,
+          :date => shipping_date,
+          :type => :DPD
+        )
+
+        response = @client.call(:ppv_get_daily_transaction_list, message: request.build!)
+        result = response.body[:ppv_get_daily_transaction_list_response][:ppv_add_order_result]
+        if result[:DailyTransactionResponse] == 'Success'
+          {
+            :transaction_list => result[:transaction_list_pdf_stream]
+          }
+        else
+          handle_errors result
+        end
+      end
+
+      protected
+
+      def auth_hash
+        {
+          :partner => {
+            :name => @partner_name,
+            :key => @partner_key
+          },
+          :user => {
+            :id => @user,
+            :token => @token
+          }
+        }
+      end
+
+      def handle_errors(result)
+        errors = result[:error_data_array][:error_data]
+        errors = [errors] unless errors.is_a? Array
+
+        errors.each do |err|
+          id = err[:error_id].to_i
+          msg = " " + (err[:error_msg] || "")
+          case id
+          when APIErrorCodes::PARTNER_AUTH_ERROR
+            raise PartnerAuthenticationError.new('Failed to authenticate partner.' + msg)
+          when APIErrorCodes::AUTH_ERROR
+            raise AuthenticationError.new('Failed to authenticate.' + msg)
+          else
+            raise "Iloxx API call failed: ##{id}: #{msg}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iloxx_shipping/daily_transaction_request.rb

@@ -0,0 +1,19 @@
+module Iloxx
+  module Shipping
+    class DailyTransactionRequest < Request
+
+      REQUEST_TYPE = :ppvDailyTransactionRequest
+
+      def initialize(attributes = {})
+        super(attributes)
+        @date = attributes[:date]
+        @type = attributes[:type]
+      end
+
+      def body(xml)
+        xml.tns :TransactionListDate, @date.strftime("%d.%m.%Y")
+        xml.tns :TransactionListType, @type
+      end
+    end
+  end
+end

data/lib/iloxx_shipping/order_request.rb

@@ -0,0 +1,33 @@
+module Iloxx
+  module Shipping
+    class OrderRequest < Request
+
+      REQUEST_TYPE = :ppvOrderRequest
+
+      def initialize(attributes = {})
+        super(attributes)
+        @shipping_date = attributes[:shipping_date]
+        @parcels = attributes[:parcels]
+      end
+
+      def body(xml)
+        xml.tns :OrderAction, "addOrder"
+        xml.tns :ServiceSettings do |xml|
+          xml.tns :ErrorLanguage, "German" # TODO: make configurable
+          xml.tns :CountrySettings, "ISO3166"
+          xml.tns :ZipCodeSetting, "ZipCodeAsSingleValue"
+        end
+        xml.tns :OrderLabel do |xml|
+          xml.tns :LabelSize, "MultiLabel_A4" # TODO: make configurable
+          xml.tns :LabelStartPosition, "UpperLeft"
+        end
+        xml.tns :ShipDate, @shipping_date.strftime("%d.%m.%Y")
+        xml.tns :ppvOrderDataArray do |xml|
+          @parcels.each do |parcel|
+            parcel.append_to_xml(xml)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/iloxx_shipping/parcel.rb

@@ -0,0 +1,31 @@
+module Iloxx
+  module Shipping
+    class Parcel
+      attr_accessor :internal_reference, :customer, :reference, :content, :weight, :service, :address, :track_url
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          setter = :"#{key.to_s}="
+          if self.respond_to?(setter)
+            self.send(setter, value)
+          end
+        end
+      end
+
+      def append_to_xml(xml)
+        xml.tns(:ppvOrderData) do |xml|
+          xml.tns(:PartnerOrderReference, internal_reference || " ")
+          xml.tns(:Customer, customer || " ")
+          xml.tns(:Reference, reference || " ")
+          xml.tns(:Content, content)
+          xml.tns(:Weight, weight)
+          xml.tns(:ShipService, service.service_type)
+          xml.tns(:CODAmount, service.cod_amount || 0)
+          address.append_to_xml(xml)
+          xml.tns(:TrackURL, track_url || "")
+        end
+      end
+
+    end
+  end
+end