zugpferd 0.1.0

data/lib/zugpferd/model/allowance_charge.rb

@@ -0,0 +1,48 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # Document-level allowance (BG-20) or charge (BG-21).
+    #
+    # @example Create a charge
+    #   charge = AllowanceCharge.new(charge_indicator: true, amount: "50.00")
+    #   charge.charge? # => true
+    #
+    # @example Create an allowance
+    #   allowance = AllowanceCharge.new(charge_indicator: false, amount: "10.00")
+    #   allowance.allowance? # => true
+    class AllowanceCharge
+      # @return [Boolean] +true+ for charge (BG-21), +false+ for allowance (BG-20)
+      # @return [String, nil] BT-97/BT-104 Allowance/charge reason
+      # @return [String, nil] BT-98/BT-105 Allowance/charge reason code
+      # @return [BigDecimal] BT-92/BT-99 Allowance/charge amount
+      # @return [BigDecimal, nil] BT-93/BT-100 Base amount
+      # @return [BigDecimal, nil] BT-94/BT-101 Percentage
+      # @return [String, nil] BT-95/BT-102 Tax category code
+      # @return [BigDecimal, nil] BT-96/BT-103 Tax rate
+      # @return [String, nil] Currency code
+      attr_accessor :charge_indicator, :reason, :reason_code,
+                    :amount, :base_amount, :multiplier_factor,
+                    :tax_category_code, :tax_percent, :currency_code
+
+      # @param charge_indicator [Boolean] +true+ for charge, +false+ for allowance
+      # @param amount [String, BigDecimal] Allowance/charge amount
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(charge_indicator:, amount:, **rest)
+        @charge_indicator = charge_indicator
+        @amount = BigDecimal(amount.to_s)
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+
+      # @return [Boolean] whether this is a charge
+      def charge?
+        charge_indicator
+      end
+
+      # @return [Boolean] whether this is an allowance
+      def allowance?
+        !charge_indicator
+      end
+    end
+  end
+end

data/lib/zugpferd/model/contact.rb

@@ -0,0 +1,16 @@
+module Zugpferd
+  module Model
+    # Contact information (BG-6 / BG-9).
+    class Contact
+      # @return [String, nil] BT-41/BT-56 Contact name
+      # @return [String, nil] BT-42/BT-57 Telephone
+      # @return [String, nil] BT-43/BT-58 Email address
+      attr_accessor :name, :telephone, :email
+
+      # @param attrs [Hash] attributes set via accessors
+      def initialize(**attrs)
+        attrs.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/invoice.rb

@@ -0,0 +1,51 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # The root invoice document (BG-0).
+    #
+    # @example
+    #   invoice = Invoice.new(number: "INV-001", issue_date: Date.today)
+    #   invoice.seller = TradeParty.new(name: "Seller GmbH")
+    class Invoice
+      # @return [String] BT-1 Invoice number
+      # @return [Date] BT-2 Issue date
+      # @return [Date, nil] BT-9 Payment due date
+      # @return [String] BT-3 Invoice type code (default: "380")
+      # @return [String] BT-5 Document currency code (default: "EUR")
+      # @return [String, nil] BT-10 Buyer reference
+      # @return [String, nil] BT-24 Specification identifier
+      # @return [String, nil] BT-23 Business process type
+      # @return [String, nil] BT-22 Invoice note
+      # @return [TradeParty, nil] BG-4 Seller party
+      # @return [TradeParty, nil] BG-7 Buyer party
+      # @return [Array<LineItem>] BG-25 Invoice lines
+      # @return [TaxBreakdown, nil] BG-23 VAT breakdown
+      # @return [MonetaryTotals, nil] BG-22 Document totals
+      # @return [PaymentInstructions, nil] BG-16 Payment information
+      # @return [Array<AllowanceCharge>] BG-20/BG-21 Document-level allowances and charges
+      attr_accessor :number, :issue_date, :due_date, :type_code,
+                    :currency_code, :buyer_reference, :customization_id,
+                    :profile_id, :note, :seller, :buyer, :line_items,
+                    :tax_breakdown, :monetary_totals, :payment_instructions,
+                    :allowance_charges
+
+      # @param number [String] BT-1 Invoice number
+      # @param issue_date [Date] BT-2 Issue date
+      # @param type_code [String] BT-3 Invoice type code
+      # @param currency_code [String] BT-5 Document currency code
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(number:, issue_date:, type_code: "380",
+                     currency_code: "EUR", **rest)
+        @number = number
+        @issue_date = issue_date
+        @type_code = type_code
+        @currency_code = currency_code
+        @line_items = []
+        @allowance_charges = []
+        @tax_breakdown = nil
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/item.rb

@@ -0,0 +1,23 @@
+module Zugpferd
+  module Model
+    # Item information (BG-31).
+    class Item
+      # @return [String] BT-153 Item name
+      # @return [String, nil] BT-154 Item description
+      # @return [String, nil] BT-155 Seller's item identifier
+      # @return [String, nil] BT-151 Invoiced item VAT category code
+      # @return [BigDecimal, nil] BT-152 Invoiced item VAT rate
+      # @return [Array] BT-158 Item classification codes
+      attr_accessor :name, :description, :sellers_identifier,
+                    :tax_category, :tax_percent, :classification_codes
+
+      # @param name [String] BT-153 Item name
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(name:, **rest)
+        @name = name
+        @classification_codes = []
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/line_item.rb

@@ -0,0 +1,32 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # An invoice line (BG-25).
+    class LineItem
+      # @return [String] BT-126 Line identifier
+      # @return [BigDecimal] BT-129 Invoiced quantity
+      # @return [String] BT-130 Unit of measure code
+      # @return [BigDecimal] BT-131 Line extension amount
+      # @return [String, nil] BT-127 Invoice line note
+      # @return [Item, nil] BG-31 Item information
+      # @return [Price, nil] BG-29 Price details
+      attr_accessor :id, :invoiced_quantity, :unit_code,
+                    :line_extension_amount, :note, :item, :price
+
+      # @param id [String] BT-126 Line identifier
+      # @param invoiced_quantity [String, BigDecimal] BT-129 Quantity
+      # @param unit_code [String] BT-130 Unit of measure code
+      # @param line_extension_amount [String, BigDecimal] BT-131 Line total
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(id:, invoiced_quantity:, unit_code:,
+                     line_extension_amount:, **rest)
+        @id = id
+        @invoiced_quantity = BigDecimal(invoiced_quantity.to_s)
+        @unit_code = unit_code
+        @line_extension_amount = BigDecimal(line_extension_amount.to_s)
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/monetary_totals.rb

@@ -0,0 +1,35 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # Document level monetary totals (BG-22).
+    class MonetaryTotals
+      # @return [BigDecimal] BT-106 Sum of invoice line net amounts
+      # @return [BigDecimal] BT-109 Invoice total without VAT
+      # @return [BigDecimal] BT-112 Invoice total with VAT
+      # @return [BigDecimal] BT-115 Amount due for payment
+      # @return [BigDecimal, nil] BT-113 Paid amount
+      # @return [BigDecimal, nil] BT-114 Rounding amount
+      # @return [BigDecimal, nil] BT-107 Sum of allowances on document level
+      # @return [BigDecimal, nil] BT-108 Sum of charges on document level
+      attr_accessor :line_extension_amount, :tax_exclusive_amount,
+                    :tax_inclusive_amount, :payable_amount,
+                    :prepaid_amount, :payable_rounding_amount,
+                    :allowance_total_amount, :charge_total_amount
+
+      # @param line_extension_amount [String, BigDecimal] BT-106
+      # @param tax_exclusive_amount [String, BigDecimal] BT-109
+      # @param tax_inclusive_amount [String, BigDecimal] BT-112
+      # @param payable_amount [String, BigDecimal] BT-115
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(line_extension_amount:, tax_exclusive_amount:,
+                     tax_inclusive_amount:, payable_amount:, **rest)
+        @line_extension_amount = BigDecimal(line_extension_amount.to_s)
+        @tax_exclusive_amount = BigDecimal(tax_exclusive_amount.to_s)
+        @tax_inclusive_amount = BigDecimal(tax_inclusive_amount.to_s)
+        @payable_amount = BigDecimal(payable_amount.to_s)
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/payment_instructions.rb

@@ -0,0 +1,29 @@
+module Zugpferd
+  module Model
+    # Payment instructions (BG-16) including payment card (BG-18)
+    # and direct debit (BG-19) information.
+    class PaymentInstructions
+      # @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-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)
+      # @return [String, nil] BT-89 Mandate reference identifier
+      # @return [String, nil] BT-90 Bank assigned creditor identifier
+      # @return [String, nil] BT-91 Debited account identifier
+      attr_accessor :payment_means_code, :payment_id, :account_id, :note,
+                    :card_account_id, :card_holder_name, :card_network_id,
+                    :mandate_reference, :creditor_reference_id,
+                    :debited_account_id
+
+      # @param payment_means_code [String] BT-81 Payment means type code
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(payment_means_code:, **rest)
+        @payment_means_code = payment_means_code
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/postal_address.rb

@@ -0,0 +1,19 @@
+module Zugpferd
+  module Model
+    # Postal address (BG-5 / BG-8).
+    class PostalAddress
+      # @return [String, nil] BT-35/BT-50 Street name
+      # @return [String, nil] BT-37/BT-52 City name
+      # @return [String, nil] BT-38/BT-53 Postal zone
+      # @return [String] BT-40/BT-55 Country code
+      attr_accessor :street_name, :city_name, :postal_zone, :country_code
+
+      # @param country_code [String] BT-40/BT-55 Country code (ISO 3166-1 alpha-2)
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(country_code:, **rest)
+        @country_code = country_code
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/price.rb

@@ -0,0 +1,19 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # Price details (BG-29).
+    class Price
+      # @return [BigDecimal] BT-146 Item net price
+      # @return [BigDecimal, nil] BT-149 Item price base quantity
+      attr_accessor :amount, :base_quantity
+
+      # @param amount [String, BigDecimal] BT-146 Item net price
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(amount:, **rest)
+        @amount = BigDecimal(amount.to_s)
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/tax_breakdown.rb

@@ -0,0 +1,23 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # VAT breakdown (BG-23).
+    class TaxBreakdown
+      # @return [BigDecimal] BT-110 Invoice total VAT amount
+      # @return [String] Tax currency code
+      # @return [Array<TaxSubtotal>] Individual VAT category breakdowns
+      attr_accessor :tax_amount, :currency_code, :subtotals
+
+      # @param tax_amount [String, BigDecimal] BT-110 Total VAT amount
+      # @param currency_code [String] Tax currency code
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(tax_amount:, currency_code:, **rest)
+        @tax_amount = BigDecimal(tax_amount.to_s)
+        @currency_code = currency_code
+        @subtotals = []
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/tax_subtotal.rb

@@ -0,0 +1,32 @@
+require "bigdecimal"
+
+module Zugpferd
+  module Model
+    # A single VAT category breakdown within {TaxBreakdown}.
+    class TaxSubtotal
+      # @return [BigDecimal] BT-116 VAT category taxable amount
+      # @return [BigDecimal] BT-117 VAT category tax amount
+      # @return [String] BT-118 VAT category code
+      # @return [BigDecimal, nil] BT-119 VAT category rate
+      # @return [String] Currency code
+      # @return [String, nil] BT-120 VAT exemption reason text
+      # @return [String, nil] BT-121 VAT exemption reason code
+      attr_accessor :taxable_amount, :tax_amount, :category_code,
+                    :percent, :currency_code,
+                    :exemption_reason, :exemption_reason_code
+
+      # @param taxable_amount [String, BigDecimal] BT-116
+      # @param tax_amount [String, BigDecimal] BT-117
+      # @param category_code [String] BT-118
+      # @param currency_code [String] Currency code
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(taxable_amount:, tax_amount:, category_code:, currency_code:, **rest)
+        @taxable_amount = BigDecimal(taxable_amount.to_s)
+        @tax_amount = BigDecimal(tax_amount.to_s)
+        @category_code = category_code
+        @currency_code = currency_code
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/model/trade_party.rb

@@ -0,0 +1,32 @@
+module Zugpferd
+  module Model
+    # A seller (BG-4) or buyer (BG-7) party.
+    #
+    # @example
+    #   party = TradeParty.new(name: "Seller GmbH")
+    #   party.vat_identifier = "DE123456789"
+    class TradeParty
+      # @return [String] BT-27/BT-44 Legal name
+      # @return [String, nil] BT-28/BT-45 Trading name
+      # @return [String, nil] BT-29/BT-46 Party identifier
+      # @return [String, nil] BT-30/BT-47 Legal registration identifier
+      # @return [String, nil] BT-33 Company legal form
+      # @return [String, nil] BT-31/BT-48 VAT identifier
+      # @return [String, nil] BT-34/BT-49 Electronic address
+      # @return [String, nil] BT-34-1/BT-49-1 Electronic address scheme
+      # @return [PostalAddress, nil] BG-5/BG-8 Postal address
+      # @return [Contact, nil] BG-6/BG-9 Contact information
+      attr_accessor :name, :trading_name, :identifier,
+                    :legal_registration_id, :legal_form, :vat_identifier,
+                    :electronic_address, :electronic_address_scheme,
+                    :postal_address, :contact
+
+      # @param name [String] BT-27/BT-44 Legal name
+      # @param rest [Hash] additional attributes set via accessors
+      def initialize(name:, **rest)
+        @name = name
+        rest.each { |k, v| public_send(:"#{k}=", v) }
+      end
+    end
+  end
+end

data/lib/zugpferd/ubl/mapping.rb

@@ -0,0 +1,135 @@
+module Zugpferd
+  module UBL
+    module Mapping
+      NS = {
+        "ubl" => "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
+        "cac" => "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
+        "cbc" => "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
+      }.freeze
+
+      # Invoice (BG-0)
+      INVOICE = {
+        number:             "cbc:ID",
+        issue_date:         "cbc:IssueDate",
+        due_date:           "cbc:DueDate",
+        type_code:          "cbc:InvoiceTypeCode",
+        currency_code:      "cbc:DocumentCurrencyCode",
+        buyer_reference:    "cbc:BuyerReference",
+        customization_id:   "cbc:CustomizationID",
+        profile_id:         "cbc:ProfileID",
+        note:               "cbc:Note",
+      }.freeze
+
+      # Seller (BG-4)
+      SELLER = "cac:AccountingSupplierParty/cac:Party"
+      # Buyer (BG-7)
+      BUYER = "cac:AccountingCustomerParty/cac:Party"
+
+      # TradeParty fields
+      PARTY = {
+        name:                    "cac:PartyLegalEntity/cbc:RegistrationName",
+        trading_name:            "cac:PartyName/cbc:Name",
+        identifier:              "cac:PartyIdentification/cbc:ID",
+        legal_registration_id:   "cac:PartyLegalEntity/cbc:CompanyID",
+        legal_form:              "cac:PartyLegalEntity/cbc:CompanyLegalForm",
+        vat_identifier:          "cac:PartyTaxScheme[cac:TaxScheme/cbc:ID='VAT']/cbc:CompanyID",
+        electronic_address:      "cbc:EndpointID",
+      }.freeze
+
+      # PostalAddress (BG-5 / BG-8)
+      POSTAL_ADDRESS = "cac:PostalAddress"
+      ADDRESS = {
+        street_name:  "cbc:StreetName",
+        city_name:    "cbc:CityName",
+        postal_zone:  "cbc:PostalZone",
+        country_code: "cac:Country/cbc:IdentificationCode",
+      }.freeze
+
+      # Contact (BG-6 / BG-9)
+      CONTACT = "cac:Contact"
+      CONTACT_FIELDS = {
+        name:      "cbc:Name",
+        telephone: "cbc:Telephone",
+        email:     "cbc:ElectronicMail",
+      }.freeze
+
+      # PaymentMeans (BG-16)
+      PAYMENT_MEANS = "cac:PaymentMeans"
+      PAYMENT = {
+        payment_means_code: "cbc:PaymentMeansCode",
+        payment_id:         "cbc:PaymentID",
+        account_id:         "cac:PayeeFinancialAccount/cbc:ID",
+        card_account_id:    "cac:CardAccount/cbc:PrimaryAccountNumberID",
+        card_network_id:    "cac:CardAccount/cbc:NetworkID",
+        card_holder_name:   "cac:CardAccount/cbc:HolderName",
+        mandate_reference:  "cac:PaymentMandate/cbc:ID",
+        debited_account_id: "cac:PaymentMandate/cac:PayerFinancialAccount/cbc:ID",
+      }.freeze
+      PAYMENT_TERMS_NOTE = "cac:PaymentTerms/cbc:Note"
+
+      # TaxTotal (BG-23)
+      TAX_TOTAL = "cac:TaxTotal"
+      TAX_SUBTOTAL = "cac:TaxSubtotal"
+      TAX = {
+        taxable_amount:        "cbc:TaxableAmount",
+        tax_amount:            "cbc:TaxAmount",
+        category_code:         "cac:TaxCategory/cbc:ID",
+        percent:               "cac:TaxCategory/cbc:Percent",
+        exemption_reason:      "cac:TaxCategory/cbc:TaxExemptionReason",
+        exemption_reason_code: "cac:TaxCategory/cbc:TaxExemptionReasonCode",
+      }.freeze
+
+      # LegalMonetaryTotal (BG-22)
+      MONETARY_TOTAL = "cac:LegalMonetaryTotal"
+      TOTALS = {
+        line_extension_amount:  "cbc:LineExtensionAmount",
+        tax_exclusive_amount:   "cbc:TaxExclusiveAmount",
+        tax_inclusive_amount:    "cbc:TaxInclusiveAmount",
+        prepaid_amount:          "cbc:PrepaidAmount",
+        payable_rounding_amount: "cbc:PayableRoundingAmount",
+        allowance_total_amount:  "cbc:AllowanceTotalAmount",
+        charge_total_amount:     "cbc:ChargeTotalAmount",
+        payable_amount:          "cbc:PayableAmount",
+      }.freeze
+
+      # AllowanceCharge (BG-20 / BG-21)
+      ALLOWANCE_CHARGE = "cac:AllowanceCharge"
+      ALLOWANCE_CHARGE_FIELDS = {
+        charge_indicator: "cbc:ChargeIndicator",
+        reason:           "cbc:AllowanceChargeReason",
+        reason_code:      "cbc:AllowanceChargeReasonCode",
+        amount:           "cbc:Amount",
+        base_amount:      "cbc:BaseAmount",
+        multiplier_factor: "cbc:MultiplierFactorNumeric",
+        tax_category_code: "cac:TaxCategory/cbc:ID",
+        tax_percent:       "cac:TaxCategory/cbc:Percent",
+      }.freeze
+
+      # InvoiceLine (BG-25)
+      INVOICE_LINE = "cac:InvoiceLine"
+      LINE = {
+        id:                    "cbc:ID",
+        invoiced_quantity:     "cbc:InvoicedQuantity",
+        unit_code:             "cbc:InvoicedQuantity/@unitCode",
+        line_extension_amount: "cbc:LineExtensionAmount",
+        note:                  "cbc:Note",
+      }.freeze
+
+      # Item (BG-31)
+      ITEM = "cac:Item"
+      ITEM_FIELDS = {
+        name:              "cbc:Name",
+        description:       "cbc:Description",
+        sellers_identifier: "cac:SellersItemIdentification/cbc:ID",
+        tax_category:      "cac:ClassifiedTaxCategory/cbc:ID",
+        tax_percent:       "cac:ClassifiedTaxCategory/cbc:Percent",
+      }.freeze
+
+      # Price (BG-29)
+      PRICE = "cac:Price"
+      PRICE_FIELDS = {
+        amount: "cbc:PriceAmount",
+      }.freeze
+    end
+  end
+end