zugpferd 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a9f2f51374e01f8940bd39a69c088477348c26d77d69adca3f1737445f99c9d
-  data.tar.gz: 8a541edb6c9b0aa78d87d715e8a04271ef0a8ea03d9d49463b4d0f45f72ce499
+  metadata.gz: eb023a7256c9cf26f6688283b6204bbccc0f46f2a6c8f0bb8082c2b1db277151
+  data.tar.gz: 00d5dc92b2d38a3744af4388017629d83b74b28241014448c75b684fb8de7c5c
 SHA512:
-  metadata.gz: 5f3051364d36fc4b5fddb4ff6e8369f37aca520f88aaa20784443176706bbfa688da434f4f3ba28fea8953460a092914b7fa0ca4380a9d07e16df5205258b7de
-  data.tar.gz: 4c40141f885ee40dd9da1e67432ba2a7a80cf5d59b2847cf4b487df4682baffc224f7b61d58b5a0b5f51aeeb684b6bf8ae501b9616e124dcaa77828761e8034a
+  metadata.gz: 0b6313dfce9be63204e9c7317be9abfbd38c0a53c97e5a7960c4b4fab98421f7f5ec892af59457c4babcdc0ec811de4159f926ae8f443df5f1d417055eb3847f
+  data.tar.gz: 449b38ee768cea1a0a5167f498c5b80a6bc3604bfe92967cabed4e51d230fe56b307dd88c5313886cb2b67d6b053932bf5f8e575b18385b781fd323f74d10fdf

data/lib/zugpferd/cii/mapping.rb

@@ -38,9 +38,17 @@ module Zugpferd
         end_date:   "ram:EndDateTime/udt:DateTimeString",
       }.freeze
 
+      # Preceding invoice reference (BG-3), relative to the settlement node
+      PRECEDING_INVOICE = "ram:InvoiceReferencedDocument"
+      PRECEDING_INVOICE_FIELDS = {
+        number:     "ram:IssuerAssignedID",
+        issue_date: "ram:FormattedIssueDateTime/qdt:DateTimeString",
+      }.freeze
+
       INVOICE_SETTLEMENT = {
         currency_code:  "#{SETTLEMENT}/ram:InvoiceCurrencyCode",
         buyer_reference: "#{AGREEMENT}/ram:BuyerReference",
+        purchase_order_reference: "#{AGREEMENT}/ram:BuyerOrderReferencedDocument/ram:IssuerAssignedID",
       }.freeze
 
       # Seller (BG-4)
@@ -93,6 +101,7 @@ module Zugpferd
 
       # TaxTotal (BG-23)
       TAX_SUBTOTAL = "ram:ApplicableTradeTax"
+      TAX_FALLBACK_CURRENCY = "ram:InvoiceCurrencyCode"
       TAX = {
         taxable_amount:        "ram:BasisAmount",
         tax_amount:            "ram:CalculatedAmount",
@@ -164,7 +173,9 @@ module Zugpferd
       # Price (BG-29)
       PRICE = "ram:SpecifiedLineTradeAgreement/ram:NetPriceProductTradePrice"
       PRICE_FIELDS = {
-        amount: "ram:ChargeAmount",
+        amount:                 "ram:ChargeAmount",
+        base_quantity:          "ram:BasisQuantity",
+        base_quantity_unit_code: "ram:BasisQuantity/@unitCode",
       }.freeze
     end
   end

data/lib/zugpferd/cii/reader.rb

@@ -12,6 +12,9 @@ module Zugpferd
     class Reader
       include Mapping
 
+      # Raised when BT-110 is missing and the VAT breakdown (BG-23) does not sum to 0.
+      class MissingTaxTotalError < Zugpferd::Error; end
+
       TYPE_CODE_MAP = {
         "381" => Model::CreditNote,
         "384" => Model::CorrectedInvoice,
@@ -25,6 +28,7 @@ module Zugpferd
       # @param xml_string [String] valid CII D16B XML
       # @return [Model::BillingDocument]
       # @raise [Nokogiri::XML::SyntaxError] if the XML is malformed
+      # @raise [MissingTaxTotalError] if BT-110 is missing and the VAT breakdown does not sum to 0
       def read(xml_string)
         doc = Nokogiri::XML(xml_string) { |config| config.strict }
         root = doc.root
@@ -50,6 +54,7 @@ module Zugpferd
           type_code: text(root, INVOICE[:type_code]),
           currency_code: text(root, INVOICE_SETTLEMENT[:currency_code]),
           buyer_reference: text(root, INVOICE_SETTLEMENT[:buyer_reference]),
+          purchase_order_reference: text(root, INVOICE_SETTLEMENT[:purchase_order_reference]),
           customization_id: text(root, INVOICE[:customization_id]),
           profile_id: text(root, INVOICE[:profile_id]),
           note: text(root, INVOICE[:note]),
@@ -57,6 +62,7 @@ module Zugpferd
           buyer: build_party(root.at_xpath(BUYER, NS)),
           line_items: root.xpath(INVOICE_LINE, NS).map { |n| build_line_item(n) },
           allowance_charges: settlement ? build_allowance_charges(settlement) : [],
+          preceding_invoices: settlement ? build_preceding_invoices(settlement) : [],
           tax_breakdown: build_tax_breakdown(settlement),
           monetary_totals: build_monetary_totals(settlement&.at_xpath(MONETARY_TOTAL, NS)),
           payment_instructions: build_payment_instructions(settlement),
@@ -129,14 +135,9 @@ module Zugpferd
 
         totals_node = settlement_node.at_xpath(MONETARY_TOTAL, NS)
         tax_total_node = totals_node&.at_xpath(TOTALS[:tax_total_amount], NS)
-        currency = tax_total_node&.[]("currencyID")
-
-        breakdown = Model::TaxBreakdown.new(
-          tax_amount: tax_total_node&.text,
-          currency_code: currency,
-        )
+        currency = tax_total_node ? tax_total_node["currencyID"] : text(settlement_node, TAX_FALLBACK_CURRENCY)
 
-        breakdown.subtotals = settlement_node.xpath(TAX_SUBTOTAL, NS).map do |sub|
+        subtotals = settlement_node.xpath(TAX_SUBTOTAL, NS).map do |sub|
           Model::TaxSubtotal.new(
             taxable_amount: text(sub, TAX[:taxable_amount]),
             tax_amount: text(sub, TAX[:tax_amount]),
@@ -148,9 +149,25 @@ module Zugpferd
           )
         end
 
+        breakdown = Model::TaxBreakdown.new(
+          tax_amount: tax_total_node ? tax_total_node.text : zero_tax_total(subtotals),
+          currency_code: currency,
+        )
+        breakdown.subtotals = subtotals
         breakdown
       end
 
+      # BR-CO-15 lets CII omit BT-110 on invoices without VAT. A breakdown
+      # that shows VAT contradicts that, even where the Schematron passes it.
+      def zero_tax_total(subtotals)
+        sum = subtotals.sum(BigDecimal("0"), &:tax_amount)
+        return sum if subtotals.any? && sum.zero?
+
+        raise MissingTaxTotalError,
+              "Invoice total VAT amount (BT-110) is missing and the VAT breakdown (BG-23) " \
+              "#{subtotals.empty? ? "is empty" : "sums to #{sum.to_s("F")}"}"
+      end
+
       def build_monetary_totals(node)
         return nil unless node
 
@@ -202,9 +219,20 @@ module Zugpferd
 
         Model::Price.new(
           amount: text(node, PRICE_FIELDS[:amount]),
+          base_quantity: parse_decimal(text(node, PRICE_FIELDS[:base_quantity])),
+          base_quantity_unit_code: node.at_xpath(PRICE_FIELDS[:base_quantity_unit_code], NS)&.text,
         )
       end
 
+      def build_preceding_invoices(settlement_node)
+        settlement_node.xpath(PRECEDING_INVOICE, NS).map do |node|
+          Model::PrecedingInvoice.new(
+            number: text(node, PRECEDING_INVOICE_FIELDS[:number]),
+            issue_date: parse_cii_date(text(node, PRECEDING_INVOICE_FIELDS[:issue_date])),
+          )
+        end
+      end
+
       def build_allowance_charges(settlement_node)
         settlement_node.xpath(ALLOWANCE_CHARGE, NS).map do |node|
           Model::AllowanceCharge.new(

data/lib/zugpferd/cii/writer.rb

@@ -76,6 +76,13 @@ module Zugpferd
           xml["ram"].BuyerReference doc.buyer_reference if doc.buyer_reference
           build_party(xml, "SellerTradeParty", doc.seller) if doc.seller
           build_party(xml, "BuyerTradeParty", doc.buyer) if doc.buyer
+          build_buyer_order_reference(xml, doc) if doc.purchase_order_reference
+        end
+      end
+
+      def build_buyer_order_reference(xml, doc)
+        xml["ram"].BuyerOrderReferencedDocument do
+          xml["ram"].IssuerAssignedID doc.purchase_order_reference
         end
       end
 
@@ -190,6 +197,20 @@ module Zugpferd
           end
 
           build_monetary_total(xml, doc.monetary_totals, doc.tax_breakdown) if doc.monetary_totals
+
+          # CII allows a single InvoiceReferencedDocument, so only the first BG-3 is written
+          build_preceding_invoice(xml, doc.preceding_invoices.first) if doc.preceding_invoices.any?
+        end
+      end
+
+      def build_preceding_invoice(xml, preceding)
+        xml["ram"].InvoiceReferencedDocument do
+          xml["ram"].IssuerAssignedID preceding.number
+          if preceding.issue_date
+            xml["ram"].FormattedIssueDateTime do
+              xml["qdt"].DateTimeString(format_cii_date(preceding.issue_date), format: "102")
+            end
+          end
         end
       end
 
@@ -296,6 +317,11 @@ module Zugpferd
             if line.price
               xml["ram"].NetPriceProductTradePrice do
                 xml["ram"].ChargeAmount format_decimal(line.price.amount)
+                if line.price.base_quantity
+                  attrs = {}
+                  attrs[:unitCode] = line.price.base_quantity_unit_code if line.price.base_quantity_unit_code
+                  xml["ram"].BasisQuantity(format_decimal(line.price.base_quantity), attrs)
+                end
               end
             end
           end

data/lib/zugpferd/model/billing_document.rb

@@ -19,9 +19,11 @@ module Zugpferd
       # @return [String] BT-3 Invoice type code
       # @return [String] BT-5 Document currency code (default: "EUR")
       # @return [Date, nil] BT-72 Actual delivery date
+      # @return [Array<PrecedingInvoice>] BG-3 Preceding invoice references
       # @return [Date, nil] BT-73 Invoicing period start date
       # @return [Date, nil] BT-74 Invoicing period end date
       # @return [String, nil] BT-10 Buyer reference
+      # @return [String, nil] BT-13 Purchase order reference
       # @return [String, nil] BT-24 Specification identifier
       # @return [String, nil] BT-23 Business process type
       # @return [String, nil] BT-22 Invoice note
@@ -35,9 +37,10 @@ module Zugpferd
       attr_accessor :number, :issue_date, :due_date, :type_code,
                     :currency_code, :delivery_date,
                     :invoicing_period_start_date, :invoicing_period_end_date,
-                    :buyer_reference, :customization_id, :profile_id, :note, :seller, :buyer,
+                    :buyer_reference, :purchase_order_reference,
+                    :customization_id, :profile_id, :note, :seller, :buyer,
                     :line_items, :tax_breakdown, :monetary_totals,
-                    :payment_instructions, :allowance_charges
+                    :payment_instructions, :allowance_charges, :preceding_invoices
 
       # @param number [String] BT-1 Invoice number
       # @param issue_date [Date] BT-2 Issue date
@@ -52,6 +55,7 @@ module Zugpferd
         @currency_code = currency_code
         @line_items = []
         @allowance_charges = []
+        @preceding_invoices = []
         @tax_breakdown = nil
         rest.each { |k, v| public_send(:"#{k}=", v) }
       end

data/lib/zugpferd/model/payment_instructions.rb

@@ -6,7 +6,7 @@ module Zugpferd
       # @return [String] BT-81 Payment means type code
       # @return [String, nil] BT-83 Remittance information
       # @return [String, nil] BT-84 Payment account identifier (IBAN)
-      # @return [String, nil] BT-82 Payment terms note
+      # @return [String, nil] BT-20 Payment terms
       # @return [String, nil] BT-87 Payment card primary account number
       # @return [String, nil] BT-88 Payment card holder name
       # @return [String, nil] Card network ID (UBL-only, required in CardAccount)

data/lib/zugpferd/model/preceding_invoice.rb

@@ -0,0 +1,17 @@
+module Zugpferd
+  module Model
+    # Reference to a preceding invoice (BG-3).
+    class PrecedingInvoice
+      # @return [String] BT-25 Preceding invoice number
+      # @return [Date, nil] BT-26 Preceding invoice issue date
+      attr_accessor :number, :issue_date
+
+      # @param number [String] BT-25 Preceding invoice number
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(number:, **rest)
+        @number = number
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/price.rb

@@ -6,7 +6,8 @@ module Zugpferd
     class Price
       # @return [BigDecimal] BT-146 Item net price
       # @return [BigDecimal, nil] BT-149 Item price base quantity
-      attr_accessor :amount, :base_quantity
+      # @return [String, nil] BT-150 Item price base quantity unit of measure code
+      attr_accessor :amount, :base_quantity, :base_quantity_unit_code
 
       # @param amount [String, BigDecimal] BT-146 Item net price
       # @param rest [Hash] additional attributes set via accessors

data/lib/zugpferd/ubl/mapping.rb

@@ -26,6 +26,9 @@ module Zugpferd
         note:               "cbc:Note",
       }.freeze
 
+      # BT-9 in a credit note (it has no cbc:DueDate)
+      CREDIT_NOTE_DUE_DATE = "cac:PaymentMeans/cbc:PaymentDueDate"
+
       # Delivery (BG-13)
       DELIVERY = "cac:Delivery"
       DELIVERY_DATE = "cbc:ActualDeliveryDate"
@@ -37,6 +40,16 @@ module Zugpferd
         end_date:   "cbc:EndDate",
       }.freeze
 
+      # Purchase order reference (BT-13)
+      ORDER_REFERENCE = "cac:OrderReference/cbc:ID"
+
+      # Preceding invoice reference (BG-3)
+      PRECEDING_INVOICE = "cac:BillingReference/cac:InvoiceDocumentReference"
+      PRECEDING_INVOICE_FIELDS = {
+        number:     "cbc:ID",
+        issue_date: "cbc:IssueDate",
+      }.freeze
+
       # Seller (BG-4)
       SELLER = "cac:AccountingSupplierParty/cac:Party"
       # Buyer (BG-7)
@@ -152,7 +165,9 @@ module Zugpferd
       # Price (BG-29)
       PRICE = "cac:Price"
       PRICE_FIELDS = {
-        amount: "cbc:PriceAmount",
+        amount:                 "cbc:PriceAmount",
+        base_quantity:          "cbc:BaseQuantity",
+        base_quantity_unit_code: "cbc:BaseQuantity/@unitCode",
       }.freeze
     end
   end

data/lib/zugpferd/ubl/reader.rb

@@ -30,6 +30,7 @@ module Zugpferd
       def build_invoice(root)
         type_code_element = @credit_note ? "cbc:CreditNoteTypeCode" : INVOICE[:type_code]
         line_element = @credit_note ? "cac:CreditNoteLine" : INVOICE_LINE
+        due_date_element = @credit_note ? CREDIT_NOTE_DUE_DATE : INVOICE[:due_date]
 
         model_class = @credit_note ? Model::CreditNote : Model::Invoice
 
@@ -39,13 +40,14 @@ module Zugpferd
         model_class.new(
           number: text(root, INVOICE[:number]),
           issue_date: parse_date(text(root, INVOICE[:issue_date])),
-          due_date: parse_date(text(root, INVOICE[:due_date])),
+          due_date: parse_date(text(root, due_date_element)),
           delivery_date: delivery_node ? parse_date(text(delivery_node, DELIVERY_DATE)) : nil,
           invoicing_period_start_date: period_node ? parse_date(text(period_node, INVOICE_PERIOD_FIELDS[:start_date])) : nil,
           invoicing_period_end_date: period_node ? parse_date(text(period_node, INVOICE_PERIOD_FIELDS[:end_date])) : nil,
           type_code: text(root, type_code_element),
           currency_code: text(root, INVOICE[:currency_code]),
           buyer_reference: text(root, INVOICE[:buyer_reference]),
+          purchase_order_reference: text(root, ORDER_REFERENCE),
           customization_id: text(root, INVOICE[:customization_id]),
           profile_id: text(root, INVOICE[:profile_id]),
           note: text(root, INVOICE[:note]),
@@ -53,6 +55,7 @@ module Zugpferd
           buyer: build_party(root.at_xpath(BUYER, @ns)),
           line_items: root.xpath(line_element, @ns).map { |n| build_line_item(n) },
           allowance_charges: root.xpath(ALLOWANCE_CHARGE, @ns).map { |n| build_allowance_charge(n) },
+          preceding_invoices: root.xpath(PRECEDING_INVOICE, @ns).map { |n| build_preceding_invoice(n) },
           tax_breakdown: build_tax_breakdown(root.at_xpath(TAX_TOTAL, @ns)),
           monetary_totals: build_monetary_totals(root.at_xpath(MONETARY_TOTAL, @ns)),
           payment_instructions: build_payment_instructions(root),
@@ -203,6 +206,15 @@ module Zugpferd
 
         Model::Price.new(
           amount: text(node, PRICE_FIELDS[:amount]),
+          base_quantity: parse_decimal(text(node, PRICE_FIELDS[:base_quantity])),
+          base_quantity_unit_code: node.at_xpath(PRICE_FIELDS[:base_quantity_unit_code], @ns)&.text,
+        )
+      end
+
+      def build_preceding_invoice(node)
+        Model::PrecedingInvoice.new(
+          number: text(node, PRECEDING_INVOICE_FIELDS[:number]),
+          issue_date: parse_date(text(node, PRECEDING_INVOICE_FIELDS[:issue_date])),
         )
       end
 

data/lib/zugpferd/ubl/writer.rb

@@ -41,7 +41,7 @@ module Zugpferd
         xml["cbc"].ProfileID doc.profile_id if doc.profile_id
         xml["cbc"].ID doc.number
         xml["cbc"].IssueDate doc.issue_date.to_s
-        xml["cbc"].DueDate doc.due_date.to_s if doc.due_date
+        xml["cbc"].DueDate doc.due_date.to_s if doc.due_date && !@credit_note
         if @credit_note
           xml["cbc"].CreditNoteTypeCode doc.type_code
         else
@@ -51,11 +51,13 @@ module Zugpferd
         xml["cbc"].DocumentCurrencyCode doc.currency_code
         xml["cbc"].BuyerReference doc.buyer_reference if doc.buyer_reference
         build_invoice_period(xml, doc) if doc.invoicing_period_start_date || doc.invoicing_period_end_date
+        build_order_reference(xml, doc) if doc.purchase_order_reference
+        doc.preceding_invoices.each { |pi| build_preceding_invoice(xml, pi) }
 
         build_supplier(xml, doc.seller, doc.payment_instructions) if doc.seller
         build_customer(xml, doc.buyer) if doc.buyer
         build_delivery(xml, doc) if doc.delivery_date
-        build_payment_means(xml, doc.payment_instructions) if doc.payment_instructions
+        build_payment_means(xml, doc.payment_instructions, doc.due_date) if doc.payment_instructions
         build_payment_terms(xml, doc.payment_instructions) if doc.payment_instructions&.note
         doc.allowance_charges.each { |ac| build_allowance_charge(xml, ac, doc.currency_code) }
         build_tax_total(xml, doc.tax_breakdown) if doc.tax_breakdown
@@ -149,15 +151,32 @@ module Zugpferd
         end
       end
 
+      def build_order_reference(xml, doc)
+        xml["cac"].OrderReference do
+          xml["cbc"].ID doc.purchase_order_reference
+        end
+      end
+
+      def build_preceding_invoice(xml, preceding)
+        xml["cac"].BillingReference do
+          xml["cac"].InvoiceDocumentReference do
+            xml["cbc"].ID preceding.number
+            xml["cbc"].IssueDate preceding.issue_date.to_s if preceding.issue_date
+          end
+        end
+      end
+
       def build_delivery(xml, doc)
         xml["cac"].Delivery do
           xml["cbc"].ActualDeliveryDate doc.delivery_date.to_s
         end
       end
 
-      def build_payment_means(xml, payment)
+      # A credit note has no cbc:DueDate, BT-9 is written as PaymentDueDate instead.
+      def build_payment_means(xml, payment, due_date = nil)
         xml["cac"].PaymentMeans do
           xml["cbc"].PaymentMeansCode payment.payment_means_code
+          xml["cbc"].PaymentDueDate due_date.to_s if @credit_note && due_date
           xml["cbc"].PaymentID payment.payment_id if payment.payment_id
           if payment.card_account_id
             xml["cac"].CardAccount do
@@ -311,6 +330,11 @@ module Zugpferd
       def build_price(xml, price, currency_code)
         xml["cac"].Price do
           xml["cbc"].PriceAmount(format_decimal(price.amount), currencyID: currency_code)
+          if price.base_quantity
+            attrs = {}
+            attrs[:unitCode] = price.base_quantity_unit_code if price.base_quantity_unit_code
+            xml["cbc"].BaseQuantity(format_decimal(price.base_quantity), attrs)
+          end
         end
       end
 

data/lib/zugpferd.rb

@@ -1,3 +1,7 @@
+module Zugpferd
+  class Error < StandardError; end
+end
+
 require_relative "zugpferd/model/billing_document"
 require_relative "zugpferd/model/invoice"
 require_relative "zugpferd/model/credit_note"
@@ -16,11 +20,8 @@ require_relative "zugpferd/model/tax_breakdown"
 require_relative "zugpferd/model/tax_subtotal"
 require_relative "zugpferd/model/payment_instructions"
 require_relative "zugpferd/model/allowance_charge"
+require_relative "zugpferd/model/preceding_invoice"
 require_relative "zugpferd/ubl/reader"
 require_relative "zugpferd/ubl/writer"
 require_relative "zugpferd/cii/reader"
 require_relative "zugpferd/cii/writer"
-
-module Zugpferd
-  class Error < StandardError; end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zugpferd
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexander Zeitler
@@ -90,6 +90,7 @@ files:
 - lib/zugpferd/model/partial_invoice.rb
 - lib/zugpferd/model/payment_instructions.rb
 - lib/zugpferd/model/postal_address.rb
+- lib/zugpferd/model/preceding_invoice.rb
 - lib/zugpferd/model/prepayment_invoice.rb
 - lib/zugpferd/model/price.rb
 - lib/zugpferd/model/self_billed_invoice.rb