invoicehn 0.1.0 → 0.2.0

data/lib/invoicehn/compliance/validator.rb

@@ -4,7 +4,12 @@ require "date"
 
 module Invoicehn
   module Compliance
-    # Checks an invoice against the Reglamento del Régimen de Facturación.
+    # Checks a Factura, Nota de Crédito or Nota de Débito against the
+    # Reglamento del Régimen de Facturación.
+    #
+    # The Factura's content is Arts. 10 and 11; the Nota de Crédito's is
+    # Arts. 25 and 26; the Nota de Débito's, Arts. 27 and 28. Rules specific to
+    # one kind say so and return nothing for the others.
     #
     # Every rule cites the article it enforces. The validator reports all
     # failures at once rather than stopping at the first, so an operator fixing
@@ -20,18 +25,24 @@ module Invoicehn
         :authorization_present,      # Art. 10 num. 3, 4, 5
         :authorization_current,      # Art. 62
         :correlative_in_range,       # Art. 10 num. 5, 7
-        :document_type_is_factura,   # Art. 10 num. 7 lit. c
-        :line_items_present,         # Art. 11 num. 1 lit. d, e, f
-        :customer_identification,    # Art. 11 num. 1 lit. a, b / num. 2 lit. a
+        :document_type_supported,    # Art. 10 num. 7 lit. c; Arts. 25, 27 num. 5 lit. c
+        :line_items_present,         # Art. 11 num. 1 lit. d, e, f; Art. 26 num. 10; Art. 28 num. 7, 9
+        :customer_identification,    # Art. 11 num. 1 lit. a, b / num. 2 lit. a; Arts. 26, 28 num. 1, 2
         :consumidor_final_threshold, # Art. 11 num. 2
         :exonerado_documents,        # Art. 10 num. 8 / Art. 11 num. 4
         :foreign_currency_rate,      # Art. 11 closing paragraph
+        :note_currency,              # Art. 26 num. 9; Art. 28 num. 8
+        :note_reference,             # Arts. 26, 28 num. 3; Art. 4 num. 31, 32
+        :note_motivo,                # Arts. 26, 28 num. 4
         :mixed_supply_notice         # Art. 11 num. 3
       ].freeze
 
+      # The document types this library issues.
+      SUPPORTED_TYPES = [Correlative::FACTURA, Correlative::NOTA_DE_CREDITO, Correlative::NOTA_DE_DEBITO].freeze
+
       attr_reader :invoice, :on
 
-      def initialize(invoice, on: Date.today)
+      def initialize(invoice, on: Invoicehn.today)
         @invoice = invoice
         @on = on
       end
@@ -93,30 +104,44 @@ module Invoicehn
                   "el correlativo #{invoice.correlative} está fuera del rango #{auth.range_label}")
       end
 
-      # Art. 10 num. 7 lit. c — "01 = Factura".
-      def document_type_is_factura
-        return if invoice.correlative.factura?
+      # Art. 10 num. 7 lit. c — "01 = Factura"; Art. 25 num. 5 lit. c — "06 =
+      # Nota de Crédito"; Art. 27 num. 5 lit. c — "07 = Nota de Débito". The
+      # other types have contents of their own that this library does not
+      # model.
+      def document_type_supported
+        return if SUPPORTED_TYPES.include?(invoice.correlative.document_type)
 
-        violation("Art. 10 num. 7 lit. c", "Código de tipo de documento 01 para la Factura",
+        violation("Art. 10 num. 7 lit. c", "Código de tipo de documento 01, 06 o 07",
                   "el correlativo declara el tipo #{invoice.correlative.document_type} " \
-                  "(#{invoice.correlative.document_type_name})")
+                  "(#{invoice.correlative.document_type_name}), que esta biblioteca no emite")
       end
 
       # Art. 11 num. 1 lit. d, e, f — a document with nothing on it describes no
       # transferencia de bienes ni prestación de servicios.
+      #
+      # A Nota de Crédito must state the "Unidades del bien vendido o servicio
+      # prestado" (Art. 26 num. 10); a Nota de Débito, the "Descripción
+      # detallada" and the units (Art. 28 num. 7 and 9).
       def line_items_present
         return if invoice.line_items.any?
 
-        violation("Art. 11 num. 1 lit. d, e y f",
-                  "Descripción detallada, cantidad de unidades y valor unitario",
-                  "la factura no tiene líneas de detalle")
+        article = by_type("Art. 11 num. 1 lit. d, e y f", "Art. 26 num. 10", "Art. 28 num. 7 y 9")
+        violation(article, "Descripción detallada, cantidad de unidades y valor unitario",
+                  "el documento no tiene líneas de detalle")
       end
 
       # Art. 11 num. 1 lit. a and b for taxpayers; num. 2 lit. a for final
       # consumers.
+      #
+      # For the notes, Art. 26 num. 1-2 and Art. 28 num. 1-2 require
+      # "Nombres y Apellidos, Razón o Denominación Social del adquirente" and
+      # "Número de Registro Tributario Nacional (RTN) del adquirente", with no
+      # CONSUMIDOR FINAL alternative like the one Art. 11 num. 2 gives the
+      # Factura. A note to an acquirer without an RTN is therefore refused.
       def customer_identification
         customer = invoice.customer
         return violation("Art. 11", "Datos del cliente", "no se configuró el cliente") if customer.nil?
+        return note_customer_identification(customer) if invoice.note?
 
         if customer.taxpayer? || customer.exonerado?
           return if !customer.name.empty? && customer.rtn
@@ -134,6 +159,7 @@ module Invoicehn
       # identificación en el espacio destinado al RTN".
       def consumidor_final_threshold
         customer = invoice.customer
+        return unless invoice.factura?
         return unless customer.is_a?(Customer::ConsumidorFinal)
 
         # The threshold is a sum *in lempiras*, so a foreign-currency invoice is
@@ -159,7 +185,9 @@ module Invoicehn
         customer = invoice.customer
         results = []
 
-        if customer.is_a?(Customer::Exonerado) && !customer.supported?
+        # Art. 10 num. 8 is a requirement of the Factura's format; Arts. 25 and
+        # 27 have no counterpart.
+        if invoice.factura? && customer.is_a?(Customer::Exonerado) && !customer.supported?
           results << violation("Art. 10 num. 8 y Art. 11 num. 4",
                                "Orden de Compra Exenta, Constancia del Registro de Exonerados o Registro SAG",
                                "el adquirente exonerado no tiene ninguno de los tres documentos de respaldo")
@@ -181,6 +209,7 @@ module Invoicehn
       # Tributario emita facturas con otra denominación monetaria, debe indicar
       # la tasa de cambio vigente a la fecha de emisión."
       def foreign_currency_rate
+        return unless invoice.factura?
         return unless invoice.foreign_currency?
 
         rate = invoice.exchange_rate
@@ -208,6 +237,7 @@ module Invoicehn
       # las ventas gravadas." Not a defect: a notice, so the document can say so
       # and the buyer is not misled about what it supports.
       def mixed_supply_notice
+        return unless invoice.factura?
         return unless invoice.summary.mixed_supply?
         return unless invoice.customer.taxpayer?
 
@@ -217,6 +247,98 @@ module Invoicehn
                   "sustenta crédito fiscal",
                   severity: :warning)
       end
+
+      # Art. 26 num. 9 and Art. 28 num. 8 — "Denominación literal de la Moneda
+      # Nacional Lempira o símbolo (L)". The permission to use "otra
+      # denominación monetaria" with the exchange rate is in Art. 11's closing
+      # paragraph, and it speaks of "facturas" only; the notes' articles have
+      # no such paragraph. A note is therefore issued in lempiras.
+      def note_currency
+        return unless invoice.note?
+        return unless invoice.foreign_currency?
+
+        violation(by_type(nil, "Art. 26 num. 9", "Art. 28 num. 8"),
+                  "Denominación literal de la Moneda Nacional Lempira o símbolo (L)",
+                  "la nota está en #{invoice.currency}; las notas se emiten en lempiras")
+      end
+
+      # Art. 26 num. 3 and Art. 28 num. 3 — "Datos del Comprobante Fiscal que
+      # da lugar a la Nota": CAI, número correlativo and fecha de emisión.
+      def note_reference
+        return unless invoice.note?
+
+        reference = invoice.reference
+        article = by_type(nil, "Art. 26 num. 3", "Art. 28 num. 3")
+        requirement = "Datos del Comprobante Fiscal que da lugar a la Nota (CAI, correlativo y fecha de emisión)"
+        return violation(article, requirement, "la nota no indica el documento al que se aplica") if reference.nil?
+
+        [
+          reference_type_violation(reference, article, requirement),
+          reference_self_violation(reference, article, requirement),
+          reference_date_violation(reference)
+        ].compact
+      end
+
+      # Art. 26 num. 4 and Art. 28 num. 4 — "Motivo de la emisión del
+      # documento".
+      def note_motivo
+        return unless invoice.note?
+        return unless invoice.motivo.empty?
+
+        violation(by_type(nil, "Art. 26 num. 4", "Art. 28 num. 4"),
+                  "Motivo de la emisión del documento", "la nota no indica el motivo")
+      end
+
+      def note_customer_identification(customer)
+        return if !customer.name.empty? && customer.rtn
+
+        violation(by_type(nil, "Art. 26 num. 1 y 2", "Art. 28 num. 1 y 2"),
+                  "Nombres y Apellidos o Razón Social, y RTN del adquirente",
+                  "la nota debe identificar al adquirente con nombre y RTN; " \
+                  "el Reglamento no admite CONSUMIDOR FINAL en las notas")
+      end
+
+      # Art. 4 num. 32 defines the Nota de Crédito as "vinculado a un
+      # Comprobante Fiscal", and Art. 26 num. 3 lit. b) asks for the
+      # "Comprobante Fiscal al que le está aplicando la Nota" — so it must
+      # point at one of the Art. 6 types. Art. 28 num. 3 lit. b) widens the
+      # Nota de Débito to "el Comprobante Fiscal o el documento al que le está
+      # aplicando la Nota", so any recognised document type is accepted there.
+      def reference_type_violation(reference, article, requirement)
+        return unless invoice.credit_note?
+        return if reference.correlative.comprobante_fiscal?
+
+        violation(article, requirement,
+                  "#{reference.correlative} es #{reference.document_type_name}, " \
+                  "que no es un Comprobante Fiscal (Art. 6)")
+      end
+
+      def reference_self_violation(reference, article, requirement)
+        return unless reference.correlative == invoice.correlative
+
+        violation(article, requirement, "la nota no puede aplicarse a sí misma")
+      end
+
+      # Art. 4 num. 32: the Nota de Crédito records adjustments "efectuados con
+      # posterioridad a la emisión del correspondiente Comprobante Fiscal"; a
+      # Nota de Débito (num. 31) is likewise "vinculado a un Comprobante Fiscal"
+      # that must already exist. A reference dated after the note is a typo or
+      # a forgery.
+      def reference_date_violation(reference)
+        return unless reference.issue_date > invoice.issue_date
+
+        violation(by_type(nil, "Art. 4 num. 32", "Art. 4 num. 31"),
+                  "La nota es posterior al documento que la origina",
+                  "el documento de referencia es del #{reference.issue_date} " \
+                  "y la nota se emitió el #{invoice.issue_date}")
+      end
+
+      def by_type(factura, credit, debit)
+        return credit if invoice.credit_note?
+        return debit if invoice.debit_note?
+
+        factura
+      end
     end
   end
 end

data/lib/invoicehn/correlative.rb

@@ -17,22 +17,54 @@ module Invoicehn
     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.
+    # Art. 10 num. 7 lit. c) and its counterparts in every other document type.
+    # The codes are the ones in force after Acuerdo 609-2017 (La Gaceta 34,457,
+    # 2 Oct 2017), whose Art. 1 rewrote lit. c) of Arts. 15, 17, 20, 23, 25,
+    # 27, 29 and 33. Line numbers refer to doc/fuentes/acuerdo_481_2017_consolidado.txt:
+    #
+    #   01 Factura                              Art. 10 num. 7 c)  (l. 626)
+    #   04 Recibo por Honorarios Profesionales  Art. 18 num. 7 c)  (l. 1039) — not reformed
+    #   05 Comprobante de Retención             Art. 33 num. 5 c)  (l. 1750)
+    #   06 Nota de Crédito                      Art. 25 num. 5 c)  (l. 1345)
+    #   07 Nota de Débito                       Art. 27 num. 5 c)  (l. 1438)
+    #   08 Guía de Remisión                     Art. 29 num. 4 c)  (l. 1535)
+    #   09 Ticket                               Art. 17 num. 4 a)  (l. 969) *
+    #   10 Factura Prevalorada                  Art. 15 num. 6 c)  (l. 889)
+    #   11 Boleta de Compra                     Art. 20 num. 5 c)  (l. 1122)
+    #   12 Constancia de Donación               Art. 23 num. 7 c)  (l. 1259)
+    #
+    # * Art. 17's closing sentence still reads "El Ticket tendrá como código 03"
+    #   (l. 988); 609-2017 changed num. 4 only. The table follows the reformed
+    #   numeral. A Ticket's own number is ten digits, not this 16-digit shape.
+    #
+    # 02 and 03 belonged to the 2017 original (Prevalorada and Ticket) and are
+    # assigned to nothing after the reform, so they are rejected. Version 0.1.0
+    # shipped the original table; see the CHANGELOG for the migration.
     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"
+      "05" => "Comprobante de Retención",
+      "06" => "Nota de Crédito",
+      "07" => "Nota de Débito",
+      "08" => "Guía de Remisión",
+      "09" => "Ticket",
+      "10" => "Factura Prevalorada",
+      "11" => "Boleta de Compra",
+      "12" => "Constancia de Donación"
     }.freeze
 
     FACTURA = "01"
+    NOTA_DE_CREDITO = "06"
+    NOTA_DE_DEBITO = "07"
+
+    # Art. 6 — "Son Comprobantes Fiscales": Factura, Factura Prevalorada,
+    # Ticket, Recibo por Honorarios Profesionales, Boleta de Compra and
+    # Constancia de Donación.
+    COMPROBANTES_FISCALES = %w[01 10 09 04 11 12].freeze
+
+    # Art. 7 — "Son Documentos Complementarios": Notas de Crédito, Notas de
+    # Débito, Guías de Remisión and Comprobantes de Retención.
+    DOCUMENTOS_COMPLEMENTARIOS = %w[06 07 08 05].freeze
 
     attr_reader :establishment, :emission_point, :document_type, :sequence
 
@@ -87,6 +119,10 @@ module Invoicehn
 
     def document_type_name = DOCUMENT_TYPES.fetch(@document_type)
     def factura? = @document_type == FACTURA
+    def credit_note? = @document_type == NOTA_DE_CREDITO
+    def debit_note? = @document_type == NOTA_DE_DEBITO
+    def note? = credit_note? || debit_note?
+    def comprobante_fiscal? = COMPROBANTES_FISCALES.include?(@document_type)
 
     def succ
       raise RangeExhausted, "el correlativo #{self} es el último de la serie" if last?

data/lib/invoicehn/document_reference.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Invoicehn
+  # The document a Nota de Crédito or Nota de Débito applies to.
+  #
+  # Art. 26 num. 3 (Nota de Crédito) and Art. 28 num. 3 (Nota de Débito)
+  # require, at the moment of issue, the "Datos del Comprobante Fiscal que da
+  # lugar a la Nota":
+  #
+  #   a) Clave de Autorización de Impresión (CAI)
+  #   b) Número correlativo del Comprobante Fiscal al que le está aplicando la
+  #      Nota
+  #   c) Fecha de emisión del Comprobante Fiscal al que le está aplicando la
+  #      Nota
+  #
+  # These are exactly the three fields here, all mandatory. The CAI is the one
+  # printed on the original document — not the note's own CAI.
+  class DocumentReference
+    attr_reader :correlative, :cai, :issue_date
+
+    # @param correlative [String, Correlative] the original document's number
+    # @param cai [String] the CAI printed on the original document
+    # @param issue_date [Date, String] the original document's fecha de emisión
+    def initialize(correlative:, cai:, issue_date:)
+      @correlative = correlative.is_a?(Correlative) ? correlative : Correlative.parse(correlative)
+      @cai = cai.to_s.strip
+      if @cai.empty?
+        raise ValidationError, "el CAI del documento de referencia es obligatorio (Arts. 26 y 28 num. 3 lit. a)"
+      end
+
+      @issue_date = coerce_date(issue_date)
+      freeze
+    end
+
+    # Builds the reference from a document this library issued, so the three
+    # fields are copied rather than retyped.
+    def self.from_document(document)
+      new(correlative: document.correlative, cai: document.authorization.cai, issue_date: document.issue_date)
+    end
+
+    def self.from_h(hash)
+      return nil if hash.nil?
+
+      new(correlative: hash["correlative"], cai: hash["cai"], issue_date: hash["issue_date"])
+    end
+
+    def document_type = @correlative.document_type
+    def document_type_name = @correlative.document_type_name
+
+    def to_h
+      {
+        "correlative" => @correlative.to_s,
+        "document_type" => document_type,
+        "cai" => @cai,
+        "issue_date" => @issue_date.iso8601
+      }
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash = to_h.hash
+
+    def to_s = "#{document_type_name} #{@correlative} · CAI #{@cai} · #{@issue_date}"
+
+    private
+
+    def coerce_date(value)
+      case value
+      when Date then value
+      when String then Date.parse(value)
+      else
+        raise ValidationError, "fecha de emisión del documento de referencia inválida: #{value.inspect}"
+      end
+    rescue ArgumentError, TypeError
+      raise ValidationError, "fecha de emisión del documento de referencia inválida: #{value.inspect}"
+    end
+  end
+end

data/lib/invoicehn/invoice.rb

@@ -3,7 +3,16 @@
 require "date"
 
 module Invoicehn
-  # A Factura (Comprobante Fiscal, tipo de documento 01).
+  # A Factura (Comprobante Fiscal, tipo 01), or one of the two Documentos
+  # Complementarios that adjust it: the Nota de Crédito (tipo 06) and the Nota
+  # de Débito (tipo 07). The type is the one the correlative declares (Art. 10
+  # num. 7 lit. c; Arts. 25 and 27 num. 5 lit. c).
+  #
+  # The three share their content: issuer, CAI, rango, fecha límite,
+  # correlative, customer, detail lines, ISV by rate and total in words. A note
+  # adds what Arts. 26 and 28 require at the moment of issue: the data of the
+  # document it applies to (`reference`, a DocumentReference) and the reason
+  # for issuing it (`motivo`). A Factura carries neither.
   #
   # 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
@@ -18,24 +27,32 @@ module Invoicehn
 
     attr_reader :correlative, :issuer, :customer, :authorization, :line_items,
                 :issue_date, :currency, :exchange_rate, :status,
-                :annulment_reason, :annulled_at, :notes
+                :annulment_reason, :annulled_at, :notes, :reference, :motivo
 
     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)
+                   notes: nil, reference: nil, motivo: 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)
+      @issue_date    = coerce_date(issue_date || Invoicehn.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
+      @reference     = coerce_reference(reference)
+      @motivo        = motivo.to_s.strip
+
+      if !note? && (@reference || !@motivo.empty?)
+        raise ValidationError,
+              "sólo las notas de crédito y de débito llevan documento de referencia y motivo " \
+              "(Arts. 26 y 28 num. 3 y 4); #{@correlative} es #{document_name}"
+      end
 
       @summary = TaxSummary.new(@line_items, currency: @currency)
       freeze
@@ -56,6 +73,17 @@ module Invoicehn
 
     def foreign_currency? = @currency != "HNL"
 
+    def document_type = @correlative.document_type
+
+    # "Factura", "Nota de Crédito" or "Nota de Débito" — the denominación each
+    # article fixes (Art. 10 num. 2, Art. 25 num. 2, Art. 27 num. 2).
+    def document_name = @correlative.document_type_name
+
+    def factura? = @correlative.factura?
+    def credit_note? = @correlative.credit_note?
+    def debit_note? = @correlative.debit_note?
+    def note? = @correlative.note?
+
     # 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.
@@ -75,8 +103,8 @@ module Invoicehn
 
     # 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?
+    def annul(reason:, on: Invoicehn.today)
+      raise ImmutableDocument, "#{document_name} #{@correlative} ya está anulada" if annulled?
 
       reason = reason.to_s.strip
       raise ValidationError, "debe indicarse el motivo de la anulación" if reason.empty?
@@ -86,22 +114,23 @@ module Invoicehn
 
     # 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)
+    def validate!(on: Invoicehn.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 compliant?(on: Invoicehn.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 violations(on: Invoicehn.today) = Compliance::Validator.new(self, on: on).violations
+    def warnings(on: Invoicehn.today) = Compliance::Validator.new(self, on: on).warnings
 
     def to_h
       {
         "correlative" => @correlative.to_s,
-        "document_name" => DOCUMENT_NAME,
+        "document_name" => document_name,
+        "document_type" => document_type,
         "status" => @status,
         "issue_date" => @issue_date.iso8601,
         "currency" => @currency,
@@ -114,7 +143,9 @@ module Invoicehn
         "total_in_words" => total_in_words,
         "annulment_reason" => @annulment_reason,
         "annulled_at" => @annulled_at&.iso8601,
-        "notes" => @notes
+        "notes" => @notes,
+        "reference" => @reference&.to_h,
+        "motivo" => (@motivo unless @motivo.empty?)
       }.compact
     end
 
@@ -131,12 +162,14 @@ module Invoicehn
         status: hash["status"] || STATUS_ISSUED,
         annulment_reason: hash["annulment_reason"],
         annulled_at: hash["annulled_at"],
-        notes: hash["notes"]
+        notes: hash["notes"],
+        reference: DocumentReference.from_h(hash["reference"]),
+        motivo: hash["motivo"]
       )
     end
 
     def to_s
-      "#{DOCUMENT_NAME} #{@correlative} · #{@issue_date} · #{total}#{" · ANULADA" if annulled?}"
+      "#{document_name} #{@correlative} · #{@issue_date} · #{total}#{" · ANULADA" if annulled?}"
     end
 
     private
@@ -147,10 +180,21 @@ module Invoicehn
         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
+        annulled_at: @annulled_at, notes: @notes, reference: @reference,
+        motivo: @motivo, **changes
       )
     end
 
+    def coerce_reference(value)
+      case value
+      when nil, DocumentReference then value
+      when Hash then DocumentReference.from_h(value.transform_keys(&:to_s))
+      else
+        raise ValidationError,
+              "el documento de referencia debe ser un Invoicehn::DocumentReference: #{value.inspect}"
+      end
+    end
+
     def coerce_date(value)
       case value
       when Date then value