invoicehn 0.1.0

data/lib/invoicehn/correlative.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  # The 16-digit document number of Art. 10 num. 7: NNN-NNN-NN-NNNNNNNN.
+  #
+  #   a) first 3 digits  — establecimiento; the casa matriz is assigned 000
+  #   b) next 3 digits   — punto de emisión
+  #   c) next 2 digits   — tipo de documento (01 = Factura)
+  #   d) last 8 digits   — sequence, starting at 00000001 and restarting after
+  #                        99999999
+  #
+  # The first three groups together are the "identificador del documento".
+  class Correlative
+    include Comparable
+
+    SEQUENCE_MIN = 1
+    SEQUENCE_MAX = 99_999_999
+    PATTERN = /\A(\d{3})-(\d{3})-(\d{2})-(\d{8})\z/
+
+    # Codes verified in the decree. 09 is deliberately absent: it was not
+    # confirmed in the text, and guessing a fiscal document code is not worth
+    # the risk.
+    DOCUMENT_TYPES = {
+      "01" => "Factura",
+      "02" => "Factura Prevalorada",
+      "03" => "Ticket",
+      "04" => "Recibo por Honorarios Profesionales",
+      "05" => "Boleta de Compra",
+      "06" => "Constancia de Donación",
+      "07" => "Nota de Crédito",
+      "08" => "Nota de Débito",
+      "10" => "Comprobante de Retención"
+    }.freeze
+
+    FACTURA = "01"
+
+    attr_reader :establishment, :emission_point, :document_type, :sequence
+
+    class << self
+      def parse(value)
+        match = PATTERN.match(value.to_s.strip)
+        raise ValidationError, "correlativo inválido: #{value.inspect} (se espera NNN-NNN-NN-NNNNNNNN)" unless match
+
+        new(
+          establishment: match[1],
+          emission_point: match[2],
+          document_type: match[3],
+          sequence: match[4].to_i
+        )
+      end
+
+      def valid?(value)
+        parse(value)
+        true
+      rescue ValidationError
+        false
+      end
+    end
+
+    def initialize(establishment:, emission_point:, document_type:, sequence:)
+      @establishment  = pad(establishment, 3, "establecimiento")
+      @emission_point = pad(emission_point, 3, "punto de emisión")
+      @document_type  = pad(document_type, 2, "tipo de documento")
+      @sequence       = Integer(sequence)
+
+      unless DOCUMENT_TYPES.key?(@document_type)
+        raise ValidationError,
+              "tipo de documento no reconocido: #{@document_type} " \
+              "(válidos: #{DOCUMENT_TYPES.keys.join(", ")})"
+      end
+
+      unless @sequence.between?(SEQUENCE_MIN, SEQUENCE_MAX)
+        raise ValidationError,
+              "correlativo fuera de rango: #{@sequence} " \
+              "(debe estar entre #{SEQUENCE_MIN} y #{SEQUENCE_MAX})"
+      end
+
+      freeze
+    end
+
+    # The (establecimiento, punto de emisión, tipo de documento) triple. SAR
+    # authorizes a CAI and range per emission point and document type, so this
+    # is the key a sequence is allocated against.
+    def identifier
+      "#{@establishment}-#{@emission_point}-#{@document_type}"
+    end
+
+    def document_type_name = DOCUMENT_TYPES.fetch(@document_type)
+    def factura? = @document_type == FACTURA
+
+    def succ
+      raise RangeExhausted, "el correlativo #{self} es el último de la serie" if last?
+
+      with_sequence(@sequence + 1)
+    end
+    alias next succ
+
+    def last? = @sequence == SEQUENCE_MAX
+
+    def with_sequence(value)
+      self.class.new(
+        establishment: @establishment,
+        emission_point: @emission_point,
+        document_type: @document_type,
+        sequence: value
+      )
+    end
+
+    def to_s
+      "#{@establishment}-#{@emission_point}-#{@document_type}-#{format("%08d", @sequence)}"
+    end
+
+    def inspect = "#<Invoicehn::Correlative #{self}>"
+
+    # Ordering is only meaningful inside one identifier — two different emission
+    # points run independent sequences.
+    def <=>(other)
+      return nil unless other.is_a?(self.class)
+      return nil unless identifier == other.identifier
+
+      @sequence <=> other.sequence
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_s == to_s
+    end
+    alias eql? ==
+
+    def hash = to_s.hash
+
+    private
+
+    def pad(value, width, label)
+      digits = value.to_s.strip
+      digits = format("%0#{width}d", digits.to_i) if digits.match?(/\A\d+\z/) && digits.length < width
+
+      unless digits.match?(/\A\d{#{width}}\z/)
+        raise ValidationError, "#{label} inválido: #{value.inspect} (se esperan #{width} dígitos)"
+      end
+
+      digits
+    end
+  end
+end

data/lib/invoicehn/customer.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  # The purchaser. Art. 11 distinguishes three situations, and which fields are
+  # mandatory depends on which one applies — so each is a separate class rather
+  # than a flag on one.
+  #
+  #   Taxpayer       — num. 1: a buyer who needs the invoice to support crédito
+  #                    fiscal. Name and RTN are both required.
+  #   ConsumidorFinal— num. 2: name and identification, or the legend
+  #                    "CONSUMIDOR FINAL". Above L 10,000.00 the client's data
+  #                    becomes mandatory.
+  #   Exonerado      — num. 4 with Art. 10 num. 8: a buyer holding an
+  #                    exoneration, which brings its own supporting numbers.
+  class Customer
+    CONSUMIDOR_FINAL_LEGEND = "CONSUMIDOR FINAL"
+
+    # Art. 11 num. 2: "Cuando la venta de bienes o prestación de servicios se
+    # realice al Consumidor Final y excediera la suma de diez mil Lempiras
+    # (L 10,000.00), debe consignarse obligatoriamente los datos del cliente".
+    #
+    # The reforms moved the power to change this figure to the Secretaría de
+    # Finanzas, so it is a constant here and not a guess at a future value.
+    IDENTIFICATION_THRESHOLD = Money.new("10000.00", "HNL")
+
+    attr_reader :name
+
+    def initialize(name:)
+      @name = name.to_s.strip
+    end
+
+    def consumidor_final? = false
+    def exonerado? = false
+    def taxpayer? = false
+    def rtn = nil
+
+    # What goes in the space reserved for the RTN on the printed document.
+    def identification_line = rtn&.formatted.to_s
+
+    def to_h = { "kind" => kind, "name" => @name }
+
+    def self.from_h(hash)
+      case hash["kind"]
+      when "taxpayer" then Taxpayer.from_h(hash)
+      when "consumidor_final" then ConsumidorFinal.from_h(hash)
+      when "exonerado" then Exonerado.from_h(hash)
+      else
+        raise ValidationError, "tipo de cliente desconocido: #{hash["kind"].inspect}"
+      end
+    end
+
+    # A buyer supporting crédito fiscal — Art. 11 num. 1 lit. a) and b).
+    class Taxpayer < Customer
+      attr_reader :rtn
+
+      def initialize(name:, rtn:)
+        super(name: name)
+        @rtn = rtn.is_a?(Rtn) ? rtn : Rtn.new(rtn)
+        freeze
+      end
+
+      def kind = "taxpayer"
+      def taxpayer? = true
+
+      def to_h = super.merge("rtn" => @rtn.to_s)
+
+      def self.from_h(hash) = new(name: hash["name"], rtn: hash["rtn"])
+
+      def to_s = "#{@name} (RTN #{@rtn.formatted})"
+    end
+
+    # Art. 11 num. 2 lit. a) — "Nombres y Apellidos, Número de identificación o
+    # consignar la leyenda 'CONSUMIDOR FINAL'".
+    class ConsumidorFinal < Customer
+      attr_reader :identification_type, :identification_number
+
+      # @param name [String, nil] omit for an anonymous sale, which prints the
+      #   legend instead.
+      # @param identification_type [String, nil] e.g. "DNI", "Pasaporte".
+      def initialize(name: nil, identification_type: nil, identification_number: nil)
+        super(name: name)
+        @identification_type = identification_type.to_s.strip
+        @identification_number = identification_number.to_s.strip
+        freeze
+      end
+
+      def kind = "consumidor_final"
+      def consumidor_final? = true
+
+      def identified? = !@name.empty? && !@identification_number.empty?
+
+      # Above the threshold Art. 11 requires "nombres y apellidos, el tipo y
+      # número de documento de identificación en el espacio destinado al RTN".
+      #
+      # @param total [Money] must be in lempiras: the article states the
+      #   threshold as a sum in lempiras, so a foreign-currency invoice is
+      #   measured by its converted equivalent. The caller does the conversion.
+      def identification_required?(total)
+        unless total.currency == "HNL"
+          raise CurrencyMismatch,
+                "el umbral del Art. 11 num. 2 se mide en lempiras; se recibió #{total.currency}"
+        end
+
+        total > IDENTIFICATION_THRESHOLD
+      end
+
+      def display_name = @name.empty? ? CONSUMIDOR_FINAL_LEGEND : @name
+
+      def identification_line
+        return CONSUMIDOR_FINAL_LEGEND unless identified?
+
+        [@identification_type, @identification_number].reject(&:empty?).join(" ")
+      end
+
+      def to_h
+        super.merge(
+          "identification_type" => @identification_type,
+          "identification_number" => @identification_number
+        )
+      end
+
+      def self.from_h(hash)
+        new(
+          name: hash["name"],
+          identification_type: hash["identification_type"],
+          identification_number: hash["identification_number"]
+        )
+      end
+
+      def to_s = identified? ? "#{@name} (#{identification_line})" : CONSUMIDOR_FINAL_LEGEND
+    end
+
+    # Art. 11 num. 4 with Art. 10 num. 8 — an exonerated purchaser. At least one
+    # of the three supporting numbers must be present:
+    #   a) Número correlativo de la Orden de Compra Exenta
+    #   b) Número correlativo de la Constancia del Registro de Exonerados
+    #   c) Número identificativo del Registro de la Secretaría de Estado en el
+    #      Despacho de Agricultura y Ganadería
+    class Exonerado < Customer
+      attr_reader :rtn, :purchase_order, :exoneration_registry, :sag_registry
+
+      def initialize(name:, rtn:, purchase_order: nil, exoneration_registry: nil, sag_registry: nil)
+        super(name: name)
+        @rtn = rtn.is_a?(Rtn) ? rtn : Rtn.new(rtn)
+        @purchase_order = purchase_order.to_s.strip
+        @exoneration_registry = exoneration_registry.to_s.strip
+        @sag_registry = sag_registry.to_s.strip
+        freeze
+      end
+
+      def kind = "exonerado"
+      def exonerado? = true
+
+      def supporting_documents
+        {
+          "Orden de Compra Exenta" => @purchase_order,
+          "Constancia del Registro de Exonerados" => @exoneration_registry,
+          "Registro SAG" => @sag_registry
+        }.reject { |_label, value| value.empty? }
+      end
+
+      # "según corresponda" — the article accepts whichever of the three applies
+      # to the buyer, so one is enough, but none is not.
+      def supported? = supporting_documents.any?
+
+      def to_h
+        super.merge(
+          "rtn" => @rtn.to_s,
+          "purchase_order" => @purchase_order,
+          "exoneration_registry" => @exoneration_registry,
+          "sag_registry" => @sag_registry
+        )
+      end
+
+      def self.from_h(hash)
+        new(
+          name: hash["name"],
+          rtn: hash["rtn"],
+          purchase_order: hash["purchase_order"],
+          exoneration_registry: hash["exoneration_registry"],
+          sag_registry: hash["sag_registry"]
+        )
+      end
+
+      def to_s = "#{@name} (RTN #{@rtn.formatted}, exonerado)"
+    end
+  end
+end

data/lib/invoicehn/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Invoicehn
+  # Base for every error this library raises.
+  class Error < StandardError; end
+
+  # A value does not satisfy the format the law or this library requires.
+  class ValidationError < Error; end
+
+  # Arithmetic across mismatched currencies.
+  class CurrencyMismatch < Error; end
+
+  # Raised when a document fails one or more compliance rules. Carries the
+  # violations so a caller can report every problem at once rather than
+  # discovering them one at a time.
+  class ComplianceError < Error
+    attr_reader :violations
+
+    def initialize(violations)
+      @violations = Array(violations)
+      super(@violations.join("\n"))
+    end
+  end
+
+  # The authorization's fecha límite de emisión has passed (Art. 62).
+  class AuthorizationExpired < Error; end
+
+  # The next correlative would fall outside the authorized range (Art. 10 num. 5).
+  class RangeExhausted < Error; end
+
+  # No authorization on file covers the document being issued.
+  class NoAuthorization < Error; end
+
+  # The requested document was not found in the store.
+  class DocumentNotFound < Error; end
+
+  # An issued document may not be altered (Art. 41 — correct by annulment).
+  class ImmutableDocument < Error; end
+end

data/lib/invoicehn/exchange_rate.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+
+module Invoicehn
+  # The exchange rate shown on an invoice denominated in a currency other than
+  # the Lempira.
+  #
+  # Art. 11 closes with a paragraph that governs both invoice types: "En ambos
+  # casos, cuando el Obligado Tributario emita facturas con otra denominación
+  # monetaria, debe indicar la tasa de cambio vigente a la fecha de emisión."
+  #
+  # Note what the norm does *not* say. It does not require a computed Lempira
+  # equivalent, does not name a rate source, and does not fix the rate's
+  # precision — and no further SAR guidance on the point exists. The Banco
+  # Central de Honduras daily reference rate is the market default and is what
+  # this library names when no source is given, but a bank or negotiated rate is
+  # not visibly prohibited, so the source is a free-text field.
+  class ExchangeRate
+    DEFAULT_SOURCE = "Banco Central de Honduras"
+
+    attr_reader :rate, :date, :source, :currency
+
+    # @param rate [BigDecimal, String, Integer] lempiras per one unit of
+    #   +currency+.
+    # @param date [Date, String] must equal the invoice's issue date — the
+    #   article requires the rate "vigente a la fecha de emisión".
+    def initialize(rate:, date:, currency: "USD", source: DEFAULT_SOURCE)
+      @rate = coerce_rate(rate)
+      @date = coerce_date(date)
+      @currency = currency.to_s.upcase
+      @source = source.to_s.strip
+      @source = DEFAULT_SOURCE if @source.empty?
+
+      raise ValidationError, "la tasa de cambio debe ser mayor que cero" unless @rate.positive?
+      raise ValidationError, "moneda no soportada: #{currency}" unless Money.currency?(@currency)
+
+      freeze
+    end
+
+    # Whether this rate is the one in effect on the given issue date.
+    def current_on?(issue_date) = @date == issue_date
+
+    # The Lempira equivalent of a foreign-currency amount. Not required by the
+    # norm, but useful on the face of the document and for the ledger.
+    def to_lempiras(money)
+      unless money.currency == @currency
+        raise CurrencyMismatch,
+              "la tasa convierte desde #{@currency}, no desde #{money.currency}"
+      end
+
+      Money.new(money.amount * @rate, "HNL").round_statutory
+    end
+
+    # "1 USD = L 24.6543 (Banco Central de Honduras, 2026-08-28)"
+    def to_s
+      "1 #{@currency} = L #{@rate.to_s("F")} (#{@source}, #{@date.iso8601})"
+    end
+
+    def to_h
+      {
+        "rate" => @rate.to_s("F"),
+        "date" => @date.iso8601,
+        "currency" => @currency,
+        "source" => @source
+      }
+    end
+
+    def self.from_h(hash)
+      return nil if hash.nil?
+
+      new(
+        rate: hash["rate"],
+        date: hash["date"],
+        currency: hash["currency"] || "USD",
+        source: hash["source"]
+      )
+    end
+
+    private
+
+    def coerce_rate(value)
+      case value
+      when BigDecimal then value
+      when Integer then BigDecimal(value)
+      when String then BigDecimal(value)
+      when Float
+        raise ValidationError, "Float no está permitido en la tasa de cambio; use BigDecimal o String"
+      else
+        raise ValidationError, "tasa de cambio no numérica: #{value.inspect}"
+      end
+    rescue ArgumentError
+      raise ValidationError, "tasa de cambio no numérica: #{value.inspect}"
+    end
+
+    def coerce_date(value)
+      case value
+      when Date then value
+      when String then Date.parse(value)
+      else
+        raise ValidationError, "fecha de la tasa de cambio inválida: #{value.inspect}"
+      end
+    rescue ArgumentError, TypeError
+      raise ValidationError, "fecha de la tasa de cambio inválida: #{value.inspect}"
+    end
+  end
+end

data/lib/invoicehn/invoice.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Invoicehn
+  # A Factura (Comprobante Fiscal, tipo de documento 01).
+  #
+  # An issued invoice is immutable. Art. 41 provides the only correction: "En el
+  # caso de emisión de Comprobantes Fiscales y/o Documentos Complementarios con
+  # errores, estos deben ser anulados, consignando en los mismos la leyenda
+  # 'ANULADA'." Annulment returns a new object; it does not mutate the record,
+  # and the correlative it consumed is never reused.
+  class Invoice
+    DOCUMENT_NAME = "Factura" # Art. 10 num. 2
+
+    STATUS_ISSUED = "emitida"
+    STATUS_ANNULLED = "anulada"
+
+    attr_reader :correlative, :issuer, :customer, :authorization, :line_items,
+                :issue_date, :currency, :exchange_rate, :status,
+                :annulment_reason, :annulled_at, :notes
+
+    def initialize(correlative:, issuer:, customer:, authorization:, line_items:,
+                   issue_date: nil, currency: "HNL", exchange_rate: nil,
+                   status: STATUS_ISSUED, annulment_reason: nil, annulled_at: nil,
+                   notes: nil)
+      @correlative   = correlative.is_a?(Correlative) ? correlative : Correlative.parse(correlative)
+      @issuer        = issuer
+      @customer      = customer
+      @authorization = authorization
+      @line_items    = Array(line_items).freeze
+      @issue_date    = coerce_date(issue_date || Date.today)
+      @currency      = currency.to_s.upcase
+      @exchange_rate = exchange_rate
+      @status        = status
+      @annulment_reason = annulment_reason
+      @annulled_at   = annulled_at && coerce_date(annulled_at)
+      @notes         = notes.to_s.strip
+
+      @summary = TaxSummary.new(@line_items, currency: @currency)
+      freeze
+    end
+
+    # The per-rate breakdown required by Art. 11 num. 1 lit. g) h) i) and l).
+    attr_reader :summary
+
+    def subtotal  = @summary.subtotal
+    def discount  = @summary.discount
+    def isv_total = @summary.isv_total
+    def total     = @summary.total
+
+    # Art. 11 num. 1 lit. k) — "Importe total en números y letras". Always
+    # rendered: required for a crédito-fiscal invoice and permitted for a
+    # consumidor final, so there is one path rather than a conditional.
+    def total_in_words = SpanishNumerals.money_to_words(total)
+
+    def foreign_currency? = @currency != "HNL"
+
+    # The Lempira equivalent of the total. Not required by the norm, which asks
+    # only for the rate, but shown when a rate is present and used to measure
+    # the Art. 11 num. 2 threshold, which the article states in lempiras.
+    #
+    # Returns nil rather than raising when no usable rate is on file: a missing
+    # or mismatched rate is already reported by the Art. 11 closing-paragraph
+    # rule, and a query used during validation must not blow up the validator.
+    def total_in_lempiras
+      return total unless foreign_currency?
+      return nil if @exchange_rate.nil? || @exchange_rate.currency != @currency
+
+      @exchange_rate.to_lempiras(total)
+    end
+
+    def annulled? = @status == STATUS_ANNULLED
+    def issued? = @status == STATUS_ISSUED
+
+    # Art. 41. Returns a new invoice carrying the ANULADA legend; the original
+    # object is untouched and the correlative stays consumed.
+    def annul(reason:, on: Date.today)
+      raise ImmutableDocument, "la factura #{@correlative} ya está anulada" if annulled?
+
+      reason = reason.to_s.strip
+      raise ValidationError, "debe indicarse el motivo de la anulación" if reason.empty?
+
+      with(status: STATUS_ANNULLED, annulment_reason: reason, annulled_at: coerce_date(on))
+    end
+
+    # Raises on errors only. Warnings (Art. 11 num. 3's mixed-supply notice) are
+    # information the document should carry, not grounds to refuse it.
+    def validate!(on: Date.today)
+      errors = Compliance::Validator.new(self, on: on).errors
+      raise ComplianceError, errors if errors.any?
+
+      self
+    end
+
+    def compliant?(on: Date.today) = Compliance::Validator.new(self, on: on).valid?
+
+    def violations(on: Date.today) = Compliance::Validator.new(self, on: on).violations
+    def warnings(on: Date.today) = Compliance::Validator.new(self, on: on).warnings
+
+    def to_h
+      {
+        "correlative" => @correlative.to_s,
+        "document_name" => DOCUMENT_NAME,
+        "status" => @status,
+        "issue_date" => @issue_date.iso8601,
+        "currency" => @currency,
+        "issuer" => @issuer.to_h,
+        "customer" => @customer.to_h,
+        "authorization" => @authorization.to_h,
+        "line_items" => @line_items.map(&:to_h),
+        "exchange_rate" => @exchange_rate&.to_h,
+        "totals" => @summary.to_h,
+        "total_in_words" => total_in_words,
+        "annulment_reason" => @annulment_reason,
+        "annulled_at" => @annulled_at&.iso8601,
+        "notes" => @notes
+      }.compact
+    end
+
+    def self.from_h(hash)
+      new(
+        correlative: hash["correlative"],
+        issuer: Issuer.from_h(hash["issuer"]),
+        customer: Customer.from_h(hash["customer"]),
+        authorization: Authorization.from_h(hash["authorization"]),
+        line_items: Array(hash["line_items"]).map { |h| LineItem.from_h(h) },
+        issue_date: hash["issue_date"],
+        currency: hash["currency"],
+        exchange_rate: ExchangeRate.from_h(hash["exchange_rate"]),
+        status: hash["status"] || STATUS_ISSUED,
+        annulment_reason: hash["annulment_reason"],
+        annulled_at: hash["annulled_at"],
+        notes: hash["notes"]
+      )
+    end
+
+    def to_s
+      "#{DOCUMENT_NAME} #{@correlative} · #{@issue_date} · #{total}#{" · ANULADA" if annulled?}"
+    end
+
+    private
+
+    def with(**changes)
+      self.class.new(
+        correlative: @correlative, issuer: @issuer, customer: @customer,
+        authorization: @authorization, line_items: @line_items,
+        issue_date: @issue_date, currency: @currency, exchange_rate: @exchange_rate,
+        status: @status, annulment_reason: @annulment_reason,
+        annulled_at: @annulled_at, notes: @notes, **changes
+      )
+    end
+
+    def coerce_date(value)
+      case value
+      when Date then value
+      when String then Date.parse(value)
+      else
+        raise ValidationError, "fecha inválida: #{value.inspect}"
+      end
+    rescue ArgumentError, TypeError
+      raise ValidationError, "fecha inválida: #{value.inspect}"
+    end
+  end
+end