solidus_avatax 0.2.0

data/app/models/spree_avatax/sales_invoice.rb

@@ -0,0 +1,157 @@
+# A SalesInvoice is persisted by Avatax but it's not recognized as complete until it's "committed".
+class SpreeAvatax::SalesInvoice < ActiveRecord::Base
+  DOC_TYPE = 'SalesInvoice'
+  CANCEL_CODE = 'DocVoided'
+
+  class CommitInvoiceNotFound < StandardError; end
+  class AlreadyCommittedError < StandardError; end
+
+  belongs_to :order, class_name: "Spree::Order", inverse_of: :avatax_sales_invoice
+
+  validates :order, presence: true
+  validates :doc_id, presence: true
+  validates :doc_code, presence: true
+  validates :doc_date, presence: true
+
+  class << self
+    # Calls the Avatax API to generate a sales invoice and calculate taxes on the line items.
+    # On failure it will raise.
+    # On success it updates taxes on the order and its line items and create a SalesInvoice record.
+    #   At this point the record is saved but uncommitted on Avatax's end.
+    # After the order completes the ".commit" method will get called and we'll commit the
+    #   sales invoice, which marks it as complete on Avatax's end.
+    def generate(order)
+      bench_start = Time.now
+
+      return if order.completed? || !SpreeAvatax::Shared.taxable_order?(order)
+
+      taxable_records = order.line_items + order.shipments
+      taxable_records.each do |taxable_record|
+        taxable_record.update_column(:pre_tax_amount, taxable_record.discounted_amount.round(2))
+      end
+
+      result = SpreeAvatax::SalesShared.get_tax(order, DOC_TYPE)
+      # run this immediately to ensure that everything matches up before modifying the database
+      tax_line_data = SpreeAvatax::SalesShared.build_tax_line_data(order, result)
+
+      if sales_invoice = order.avatax_sales_invoice
+        if sales_invoice.committed_at.nil?
+          sales_invoice.destroy
+        else
+          raise AlreadyCommittedError.new("Sales invoice #{sales_invoice.id} is already committed.")
+        end
+      end
+
+      sales_invoice = order.create_avatax_sales_invoice!({
+        transaction_id:        result[:transaction_id],
+        doc_id:                result[:doc_id],
+        doc_code:              result[:doc_code],
+        doc_date:              result[:doc_date],
+        pre_tax_total:         result[:total_amount],
+        additional_tax_total:  result[:total_tax],
+      })
+
+      SpreeAvatax::SalesShared.update_taxes(order, tax_line_data)
+
+      sales_invoice
+    rescue Exception => e
+      if SpreeAvatax::Config.sales_invoice_generate_error_handler
+        SpreeAvatax::Config.sales_invoice_generate_error_handler.call(order, e)
+      else
+        raise
+      end
+    ensure
+      duration = (Time.now - bench_start).round
+      Rails.logger.info "avatax_sales_invoice_generate_duration=#{(duration*1000).round}"
+    end
+
+    def commit(order)
+      return if !SpreeAvatax::Shared.taxable_order?(order)
+
+      raise CommitInvoiceNotFound.new("No invoice for order #{order.number}") if order.avatax_sales_invoice.nil?
+
+      post_tax(order.avatax_sales_invoice)
+
+      order.avatax_sales_invoice.update!(committed_at: Time.now)
+
+      order.avatax_sales_invoice
+    rescue Exception => e
+      if SpreeAvatax::Config.sales_invoice_commit_error_handler
+        SpreeAvatax::Config.sales_invoice_commit_error_handler.call(order, e)
+      else
+        raise
+      end
+    end
+
+    def cancel(order)
+      return if order.avatax_sales_invoice.nil?
+
+      result = cancel_tax(order.avatax_sales_invoice)
+
+      order.avatax_sales_invoice.update!({
+        canceled_at:           Time.now,
+        cancel_transaction_id: result[:transaction_id],
+      })
+    rescue Exception => e
+      if SpreeAvatax::Config.sales_invoice_cancel_error_handler
+        SpreeAvatax::Config.sales_invoice_cancel_error_handler.call(order, e)
+      else
+        raise
+      end
+    end
+
+    private
+
+    def post_tax(sales_invoice)
+      params = posttax_params(sales_invoice)
+
+      logger.info "[avatax] posttax sales_invoice=#{sales_invoice.id} order=#{sales_invoice.order_id}"
+      logger.debug { "[avatax] params: #{params.to_json}" }
+
+      response = SpreeAvatax::Shared.tax_svc.posttax(params)
+      SpreeAvatax::Shared.require_success!(response)
+
+      response
+    end
+
+    def cancel_tax(sales_invoice)
+      params = canceltax_params(sales_invoice)
+
+      logger.info "[avatax] canceltax sales_invoice=#{sales_invoice.id}"
+      logger.debug { "[avatax] params: #{params.to_json}" }
+
+      response = SpreeAvatax::Shared.tax_svc.canceltax(params)
+
+      SpreeAvatax::Shared.require_success!(response)
+
+      response
+    end
+
+    # see https://github.com/avadev/AvaTax-Calc-SOAP-Ruby/blob/master/PostTaxTest.rb
+    def posttax_params(sales_invoice)
+      {
+        doccode:     sales_invoice.doc_code,
+        companycode: SpreeAvatax::Config.company_code,
+
+        doctype: DOC_TYPE,
+        docdate: sales_invoice.doc_date,
+
+        commit: true,
+
+        totalamount: sales_invoice.pre_tax_total,
+        totaltax:    sales_invoice.additional_tax_total,
+      }
+    end
+
+    # see https://github.com/avadev/AvaTax-Calc-SOAP-Ruby/blob/master/CancelTaxTest.rb
+    def canceltax_params(sales_invoice)
+      {
+        # Required Parameters
+        doccode:     sales_invoice.doc_code,
+        doctype:     DOC_TYPE,
+        cancelcode:  CANCEL_CODE,
+        companycode: SpreeAvatax::Config.company_code,
+      }
+    end
+  end
+end

data/app/models/spree_avatax/sales_shared.rb

@@ -0,0 +1,211 @@
+module SpreeAvatax::SalesShared
+
+  DESTINATION_CODE = "1"
+
+  SHIPPING_TAX_CODE = 'FR020100' # docs: http://goo.gl/KuIuxc
+
+  SHIPPING_DESCRIPTION = 'Shipping Charge'
+
+  class InvalidApiResponse < StandardError; end
+
+  class << self
+    # Queries Avatax for taxes on a specific order using the specified doc_type.
+    # SalesOrder doc types are not persisted on Avatax.
+    # SalesInvoice doc types do persist an uncommitted record on Avatax.
+    def get_tax(order, doc_type)
+      params = gettax_params(order, doc_type)
+
+      logger.info "[avatax] gettax order=#{order.id} doc_type=#{doc_type}"
+      logger.debug { "[avatax] params: #{params.to_json}" }
+
+      response = SpreeAvatax::Shared.tax_svc.gettax(params)
+      SpreeAvatax::Shared.require_success!(response)
+
+      response
+    end
+
+    def update_taxes(order, tax_line_data)
+      reset_tax_attributes(order)
+
+      tax_line_data.each do |data|
+        record, tax_line = data[:record], data[:tax_line]
+
+        record.update_column(:pre_tax_amount, record.discounted_amount)
+
+        tax = BigDecimal.new(tax_line[:tax]).abs
+
+        record.adjustments.tax.create!({
+          adjustable: record,
+          amount:     tax,
+          order:      order,
+          label:      Spree.t(:avatax_label),
+          included:   false, # would be true for VAT
+          source:     Spree::TaxRate.avatax_the_one_rate,
+          finalized:  true, # this tells spree not to automatically recalculate avatax tax adjustments
+        })
+
+        Spree::ItemAdjustments.new(record).update
+        record.save!
+      end
+
+      Spree::OrderUpdater.new(order).update
+      order.save!
+    end
+
+    # returns an array like:
+    # [
+    #   {tax_line: {...}, record: #<Spree::LineItem id=111>},
+    #   {tax_line: {...}, record: #<Spree::LineItem id=222>},
+    #   {tax_line: {...}, record: #<Spree::Shipment id=111>},
+    # ]
+    def build_tax_line_data(order, avatax_result)
+      # Array.wrap is required because the XML engine the Avatax gem uses turns child nodes into
+      #   {...} instead of [{...}] when there is only one child.
+      tax_lines = Array.wrap(avatax_result[:tax_lines][:tax_line])
+
+      # builds a hash like: {"L-111": {record: #<Spree::LineItem ...>}, ...}
+      data = (order.line_items + order.shipments).map { |r| [avatax_id(r), {record: r}] }.to_h
+
+      # adds :tax_line to each entry in the data
+      tax_lines.each do |tax_line|
+        avatax_id = tax_line[:no]
+        if data[avatax_id]
+          data[avatax_id][:tax_line] = tax_line
+        else
+          raise InvalidApiResponse.new("Couldn't find #{avatax_id.inspect}")
+        end
+      end
+
+      missing = data.select { |avatax_id, data| data[:tax_line].nil? }
+      if missing.any?
+        raise InvalidApiResponse.new("missing tax data for #{missing.keys}")
+      end
+
+      data.values
+    end
+
+    # sometimes we have to store different types of things in a single array (like line items and
+    # shipments). this allows us to provide a unique identifier to each record.
+    def avatax_id(record)
+      "#{record.class.name}-#{record.id}"
+    end
+
+
+    # Clears previously-set tax attributes from an order, if any, unless the
+    # order has already been completed.
+    #
+    # @param order [Spree::Order] the order
+    def reset_tax_attributes(order)
+      return if order.completed?
+
+      destroyed_adjustments = order.all_adjustments.tax.destroy_all
+      return if destroyed_adjustments.empty?
+
+      order.line_items.each do |line_item|
+        line_item.update_attributes!({
+          additional_tax_total: 0,
+          adjustment_total: 0,
+          pre_tax_amount: 0,
+          included_tax_total: 0,
+        })
+
+        Spree::ItemAdjustments.new(line_item).update
+        line_item.save!
+      end
+
+      order.update_attributes!({
+        additional_tax_total: 0,
+        adjustment_total: 0,
+        included_tax_total: 0,
+      })
+
+      order.update!
+      order.save!
+    end
+
+    private
+
+    def logger
+      SpreeAvatax::Shared.logger
+    end
+
+    # see https://github.com/avadev/AvaTax-Calc-SOAP-Ruby/blob/master/GetTaxTest.rb
+    def gettax_params(order, doc_type)
+      {
+        doccode:       order.number,
+        customercode:  REXML::Text.normalize(order.email),
+        companycode:   SpreeAvatax::Config.company_code,
+
+        doctype: doc_type,
+        docdate: Date.today,
+
+        commit: false, # we commit separately after the order completes
+
+        # NOTE: we only want order-level adjustments here. not line item or shipping adjustments.
+        #       avatax distributes order-level discounts across all "lineitem" entries that have
+        #       "discounted:true"
+        #       Also, the "discount" can be negative and Avatax handles that OK. A negative number
+        #       would mean that *charges* were added to the order via an order-level adjustment.
+        discount: order.avatax_order_adjustment_total.round(2).to_f,
+
+        addresses: [
+          {
+            addresscode: DESTINATION_CODE,
+            line1:       REXML::Text.normalize(order.ship_address.address1),
+            line2:       REXML::Text.normalize(order.ship_address.address2),
+            city:        REXML::Text.normalize(order.ship_address.city),
+            postalcode:  REXML::Text.normalize(order.ship_address.zipcode),
+          },
+        ],
+
+        lines: gettax_lines_params(order),
+      }
+    end
+
+    def gettax_lines_params(order)
+      line_items = order.line_items.includes(variant: :product)
+
+      line_item_lines = line_items.map do |line_item|
+        {
+          # Required Parameters
+          no:                  avatax_id(line_item),
+          qty:                 line_item.quantity,
+          amount:              line_item.discounted_amount.round(2).to_f,
+          origincodeline:      DESTINATION_CODE, # We don't really send the correct value here
+          destinationcodeline: DESTINATION_CODE,
+
+          # Best Practice Parameters
+          description: REXML::Text.normalize(line_item.variant.product.description.to_s.truncate(100)),
+
+          # Optional Parameters
+          itemcode:   line_item.variant.sku,
+          taxcode:    line_item.tax_category.tax_code,
+          # "discounted" tells avatax to include this item when it distributes order-level discounts
+          # across avatax "lines"
+          discounted: true,
+        }
+      end
+
+      shipment_lines = order.shipments.map do |shipment|
+        {
+          # Required Parameters
+          no:                  avatax_id(shipment),
+          qty:                 1,
+          amount:              shipment.discounted_amount.round(2).to_f,
+          origincodeline:      DESTINATION_CODE, # We don't really send the correct value here
+          destinationcodeline: DESTINATION_CODE,
+
+          # Best Practice Parameters
+          description: SHIPPING_DESCRIPTION,
+
+          # Optional Parameters
+          taxcode:    SHIPPING_TAX_CODE,
+          # order-level discounts do not apply to shipments
+          discounted: false,
+        }
+      end
+
+      line_item_lines + shipment_lines
+    end
+  end
+end

data/app/models/spree_avatax/shared.rb

@@ -0,0 +1,53 @@
+module SpreeAvatax::Shared
+  class FailedApiResponse < StandardError
+    attr_reader :response, :messages
+
+    def initialize(response)
+      @response = response
+      # avatax seems to have two different error message formats:
+      # https://gist.github.com/jordan-brough/a22163e4551c692365b8
+      # https://gist.github.com/jordan-brough/c778a3417850dfa2307c
+      # We should pester Avatax about this sometime.
+      if @response[:messages].is_a?(Array)
+        @messages = response[:messages]
+      else
+        @messages = Array.wrap(response[:messages][:message])
+      end
+
+      super(messages.map { |msg| msg[:summary] })
+    end
+  end
+
+  class << self
+
+    def logger
+      Rails.logger
+    end
+
+    def taxable_order?(order)
+      order.line_items.present? && order.ship_address.present?
+    end
+
+    def tax_svc
+      @tax_svc ||= AvaTax::TaxService.new({
+        username:               SpreeAvatax::Config.username,
+        password:               SpreeAvatax::Config.password,
+        service_url:            SpreeAvatax::Config.service_url,
+        clientname:             'Spree::Avatax',
+      })
+    end
+
+    def require_success!(response)
+      if response[:result_code] == 'Success'
+        logger.info "[avatax] response - result=success doc_id=#{response[:doc_id]} doc_code=#{response[:doc_code]} transaction_id=#{response[:transaction_id]}"
+        logger.debug { "[avatax] response: #{response.to_json}" }
+      else
+        logger.error "[avatax] response - result=error doc_id=#{response[:doc_id]} doc_code=#{response[:doc_code]} transaction_id=#{response[:transaction_id]}"
+        logger.error "[avatax] response: #{response.to_json}"
+        raise FailedApiResponse.new(response)
+      end
+    end
+
+  end
+
+end

data/app/models/spree_avatax/short_ship_return_invoice.rb

@@ -0,0 +1,133 @@
+class SpreeAvatax::ShortShipReturnInvoice < ActiveRecord::Base
+  DOC_TYPE = 'ReturnInvoice'
+
+  DESTINATION_CODE = "1"
+
+  TAX_OVERRIDE_TYPE = 'TaxAmount'
+  TAX_OVERRIDE_REASON = 'Short ship'
+
+  has_many :short_ship_return_invoice_inventory_units, class_name: 'SpreeAvatax::ShortShipReturnInvoiceInventoryUnit', inverse_of: :short_ship_return_invoice
+  has_many :inventory_units, through: :short_ship_return_invoice_inventory_units, class_name: 'Spree::InventoryUnit'
+
+  validates :doc_id, presence: true
+  validates :doc_code, presence: true
+  validates :doc_date, presence: true
+
+  class << self
+    # Calls the Avatax API to generate a return invoice for an item that has
+    # been short shipped.  It tells Avatax how much tax was refunded rather than
+    # asking it how much should be refunded.
+    # It is generated in the "committed" state since there is no need for a two-
+    # step commit here.
+    #
+    # On failure it will raise.
+    def generate(unit_cancels:)
+      inventory_units = unit_cancels.map(&:inventory_unit)
+
+      order_ids = inventory_units.map(&:order_id).uniq
+      if order_ids.size > 1
+        raise "unit cancels #{unit_cancels.map(&:id)} had more than one order: #{order_ids}"
+      end
+
+      success_result = get_tax(unit_cancels: unit_cancels)
+
+      create!(
+        inventory_units:       inventory_units,
+        committed:             true,
+        doc_id:                success_result[:doc_id],
+        doc_code:              success_result[:doc_code],
+        doc_date:              success_result[:doc_date],
+      )
+    end
+
+    private
+
+    def get_tax(unit_cancels:)
+      params = gettax_params(unit_cancels: unit_cancels)
+
+      logger.info("[avatax] gettax unit_cancel_ids=#{unit_cancels.map(&:id)} doc_type=#{DOC_TYPE}")
+      logger.debug("[avatax] params: " + params.to_json)
+
+      response = SpreeAvatax::Shared.tax_svc.gettax(params)
+      SpreeAvatax::Shared.require_success!(response)
+
+      response
+    end
+
+    # see https://github.com/avadev/AvaTax-Calc-SOAP-Ruby/blob/master/GetTaxTest.rb
+    def gettax_params(unit_cancels:)
+      # we verified previously that there is only one order
+      order = unit_cancels.first.inventory_unit.order
+
+      lines = gettax_line_params(
+        unit_cancels: unit_cancels,
+        taxed_at: order.avatax_sales_invoice.try!(:doc_date) || order.completed_at
+      )
+
+      {
+        doccode:       "#{order.number}-short-#{Time.now.to_f}",
+        referencecode: order.number,
+        customercode:  order.user_id,
+        companycode:   SpreeAvatax::Config.company_code,
+
+        doctype: DOC_TYPE,
+        docdate: Date.today,
+
+        commit: true,
+
+        addresses: [
+          {
+            addresscode: DESTINATION_CODE,
+            line1:       REXML::Text.normalize(order.ship_address.address1),
+            line2:       REXML::Text.normalize(order.ship_address.address2),
+            city:        REXML::Text.normalize(order.ship_address.city),
+            postalcode:  REXML::Text.normalize(order.ship_address.zipcode),
+          },
+        ],
+
+        lines: lines,
+      }
+    end
+
+    def gettax_line_params(unit_cancels:, taxed_at:)
+      unit_cancels.sort_by(&:id).map do |unit_cancel|
+        inventory_unit = unit_cancel.inventory_unit
+
+        adjustment = unit_cancel.adjustment
+
+        if adjustment
+          total = -adjustment.amount # adjustment is stored as a negative amount
+          tax = inventory_unit.additional_tax_total
+          before_tax = total - tax
+        else
+          # TODO: Consider removing this case. Are there expected scenarios
+          # where there will be no adjustment present?
+          total = 0
+          tax = 0
+          before_tax = 0
+        end
+
+        {
+          # Required Parameters
+          no:                  inventory_unit.id,
+          itemcode:            inventory_unit.line_item.variant.sku,
+          taxcode:             inventory_unit.line_item.tax_category.tax_code,
+          qty:                 1,
+          amount:              -before_tax,
+          origincodeline:      DESTINATION_CODE, # We don't really send the correct value here
+          destinationcodeline: DESTINATION_CODE,
+
+          # We tell Avatax what the amounts were rather than asking Avatax what
+          # the amounts should have been.
+          taxoverridetypeline: TAX_OVERRIDE_TYPE,
+          reasonline:          TAX_OVERRIDE_REASON,
+          taxamountline:       -tax,
+          taxdateline:         taxed_at.to_date,
+
+          # Best Practice Parameters
+          description: REXML::Text.normalize(inventory_unit.line_item.variant.product.description.to_s[0...100]),
+        }
+      end
+    end
+  end
+end