verifactu-rails 0.1.0.pre

data/lib/verifactu_rails/libro/reconciliacion.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # Contraste entre lo que dice el libro registro y lo que la AEAT tiene
+    # realmente anotado.
+    #
+    # SOLO LEE. No corrige nada, ni siquiera lo que parece obvio, y es una
+    # decisión, no una versión reducida: lo que esto detecta es divergencia entre
+    # el sistema de registro y la AEAT, y un job que reescribiera el estado local
+    # para "cuadrar" taparía justo lo que se le ha pedido revelar. Además no hace
+    # falta: Remesa ya reintenta sola lo que quedó en 'enviando', porque un
+    # duplicado cuenta como éxito.
+    #
+    # QUÉ PUEDE Y QUÉ NO PUEDE COMPROBAR. La consulta devuelve una FOTO POR
+    # FACTURA, no el histórico de registros (comprobado contra preproducción: 6
+    # registros sobre 4 facturas devolvieron 4 filas). Una subsanación sustituye
+    # al alta original y la anulación sustituye a lo anulado, así que los
+    # eslabones intermedios ya no se devuelven. Consecuencias directas:
+    #
+    #   - Se reconcilia el ESTADO ACTUAL de cada factura. Es lo que esto hace.
+    #   - NO se puede auditar el encadenamiento contra la AEAT. Los registros
+    #     sustituidos faltan, y los que encadenaban tras ellos parecen huérfanos
+    #     aunque la cadena esté intacta. Detectar una bifurcación sigue siendo
+    #     cosa del índice único local, no de aquí.
+    #
+    # Por eso se compara contra el registro VIGENTE de cada factura -el último
+    # anotado con ese IDFactura-, que es el que la AEAT debería estar
+    # devolviendo.
+    class Reconciliacion
+      # La AEAT avisa de que preproducción es para pruebas puntuales, no para
+      # carga. Un tope explícito evita que un fallo de paginación se convierta en
+      # una tromba de peticiones; que se ha alcanzado se DICE (Informe#truncado?)
+      # en vez de devolver medio informe con cara de completo.
+      MAXIMO_PAGINAS = 100
+
+      # Los importes no se comparan: la AEAT los devuelve sin ceros a la derecha
+      # ('121' por '121.00'), así que un cotejo textual daría falsos positivos a
+      # mansalva. No se pierde nada, porque los importes entran en la huella y la
+      # huella sí se compara.
+      Divergencia = Struct.new(:tipo, :id_emisor, :num_serie, :fecha_expedicion,
+                               :local, :remoto, :detalle, keyword_init: true) do
+        def to_s = "#{num_serie}: #{tipo} — #{detalle}"
+      end
+
+      Informe = Struct.new(:ejercicio, :periodo, :facturas_locales, :filas_aeat,
+                           :ajenas, :divergencias, :truncado, keyword_init: true) do
+        def cuadra? = divergencias.empty?
+        def truncado? = truncado == true
+
+        def to_s
+          base = "#{ejercicio}-#{periodo}: #{facturas_locales} facturas locales, " \
+                 "#{filas_aeat} filas de la AEAT, #{divergencias.size} divergencias"
+          base += ", #{ajenas} de otra instalación" if ajenas.positive?
+          base += ' (INFORME TRUNCADO: se alcanzó el tope de páginas)' if truncado?
+          base
+        end
+      end
+
+      def initialize(cadena, transporte:)
+        @cadena = cadena
+        @transporte = transporte
+      end
+
+      # @param periodo [String, Integer] mes de imputación (8 y '08' valen igual).
+      # @return [Informe]
+      def revisar(ejercicio:, periodo:)
+        periodo = format('%<mes>02d', mes: periodo.to_i)
+        remotas, truncado = descargar(ejercicio: ejercicio, periodo: periodo)
+        nuestras, ajenas = remotas.partition { |fila| de_esta_instalacion?(fila) }
+        pendientes = nuestras.index_by { |fila| clave(fila) }
+
+        divergencias = vigentes(ejercicio: ejercicio, periodo: periodo).flat_map do |id, local|
+          comparar(local, pendientes.delete(id))
+        end
+        # Lo que sobra está en la AEAT y no en el libro. Es el caso grave: o
+        # factura otro sistema para este obligado, o se reutilizó un número de
+        # instalación que ya tenía historia.
+        divergencias += pendientes.each_value.map { |fila| solo_en_aeat(fila) }
+
+        Informe.new(ejercicio: ejercicio.to_s, periodo: periodo,
+                    facturas_locales: vigentes(ejercicio: ejercicio, periodo: periodo).size,
+                    filas_aeat: nuestras.size, ajenas: ajenas.size,
+                    divergencias: divergencias, truncado: truncado)
+      end
+
+      private
+
+      attr_reader :cadena, :transporte
+
+      # El registro VIGENTE de cada factura: el último anotado con ese IDFactura.
+      # El índice (id_emisor, num_serie, fecha_expedicion) NO es único a
+      # propósito -una subsanación reutiliza el mismo IDFactura-, así que aquí
+      # puede haber varias filas por factura y solo la última cuenta.
+      #
+      # Se filtra por mes de expedición asumiendo que la AEAT imputa por ella. Es
+      # la lectura natural y la que usó la campaña contra preproducción, pero es
+      # una suposición: si algún día no cuadra, mira aquí primero.
+      def vigentes(ejercicio:, periodo:)
+        @vigentes ||= {}
+        @vigentes[[ejercicio.to_s, periodo]] ||=
+          cadena.registros
+                .where('fecha_expedicion LIKE ?', "%-#{periodo}-#{ejercicio}")
+                .order(:id)
+                .each_with_object({}) { |fila, h| h[clave(fila)] = fila }
+      end
+
+      def clave(fila)
+        [fila.id_emisor, fila.num_serie, fila.fecha_expedicion]
+      end
+
+      # La fila es de esta cadena si la AEAT la atribuye a nuestra instalación.
+      #
+      # Se filtra AQUÍ, en cliente, además de mandar el SistemaInformatico en el
+      # filtro de la consulta. Todo apunta a que el servidor aplica ese cotejo (6
+      # facturas del mismo NIF y periodo en dos instalaciones, la consulta
+      # devolvió solo las 2 de la consultada), pero no está cerrado: falta
+      # verificar que las otras 4 siguieran almacenadas. Ver doc/FUENTES.md.
+      #
+      # Sea o no redundante, esto se queda: es barato, y hace que el informe siga
+      # siendo correcto tanto si la premisa falla como si algún día cambia el
+      # cotejo del servidor, en vez de llenarse de :solo_en_aeat por facturas de
+      # otras tiendas.
+      #
+      # Una fila sin NumeroInstalacion se da por nuestra: preferimos revisarla de
+      # más a dejar pasar una factura ajena sin mirar.
+      def de_esta_instalacion?(fila)
+        fila.numero_instalacion.nil? ||
+          fila.numero_instalacion == cadena.numero_instalacion
+      end
+
+      def comparar(local, remoto)
+        return [] if remoto.nil? && sin_constancia_esperada?(local)
+        return [divergencia(:no_consta, local, nil, detalle_no_consta(local))] if remoto.nil?
+        return [divergencia(:consta_sin_enviar, local, remoto, detalle_sin_enviar(local, remoto))] if sin_enviar?(local)
+
+        # Si la huella no coincide, lo que la AEAT guarda NO es este registro, y
+        # comparar además el estado solo añadiría ruido sobre otro documento.
+        if remoto.huella != local.huella
+          return [divergencia(:huella_distinta, local, remoto,
+                              "la AEAT guarda la huella #{remoto.huella} y el libro " \
+                              "#{local.huella} para esta factura")]
+        end
+
+        esperado = estado_esperado(local)
+        return [] if remoto.estado == esperado
+
+        [divergencia(:estado_distinto, local, remoto,
+                     "la AEAT dice #{remoto.estado} y el libro esperaba #{esperado}")]
+      end
+
+      # Que no conste no siempre es divergencia: lo que aún no se ha enviado no
+      # tiene por qué estar, y un registro RECHAZADO no se almacena en la AEAT,
+      # así que su ausencia es justo lo correcto.
+      def sin_constancia_esperada?(local)
+        sin_enviar?(local) || local.estado == 'rechazado'
+      end
+
+      def sin_enviar?(local) = %w[pendiente enviando].include?(local.estado)
+
+      def estado_esperado(local)
+        return 'Anulado' if local.tipo == 'anulacion'
+        return 'AceptadoConErrores' if local.estado == 'aceptado_con_errores'
+
+        'Correcto'
+      end
+
+      def detalle_no_consta(local)
+        "el libro la da por #{local.estado} pero la AEAT no la devuelve; " \
+          'no consta remitida'
+      end
+
+      def detalle_sin_enviar(local, remoto)
+        coincide = remoto.huella == local.huella ? 'y la huella coincide' : 'pero con OTRA huella'
+        "el libro la tiene en '#{local.estado}' y la AEAT ya la tiene anotada " \
+          "#{coincide}: el envío llegó y no nos enteramos"
+      end
+
+      def solo_en_aeat(fila)
+        Divergencia.new(
+          tipo: :solo_en_aeat, id_emisor: fila.id_emisor, num_serie: fila.num_serie,
+          fecha_expedicion: fila.fecha_expedicion, local: nil, remoto: fila,
+          detalle: 'la AEAT tiene esta factura en esta instalación y el libro no ' \
+                   'la conoce: o factura otro sistema para este obligado, o se ' \
+                   'reutilizó un número de instalación con historia'
+        )
+      end
+
+      def divergencia(tipo, local, remoto, detalle)
+        Divergencia.new(tipo: tipo, id_emisor: local.id_emisor,
+                        num_serie: local.num_serie,
+                        fecha_expedicion: local.fecha_expedicion,
+                        local: local, remoto: remoto, detalle: detalle)
+      end
+
+      def descargar(ejercicio:, periodo:)
+        filas = []
+        clave = nil
+
+        MAXIMO_PAGINAS.times do
+          respuesta = pedir(ejercicio: ejercicio, periodo: periodo, clave: clave)
+          filas.concat(respuesta.registros)
+
+          return [filas, false] unless respuesta.hay_mas_paginas?
+
+          clave = respuesta.clave_paginacion
+          # Paginación "S" sin clave dejaría un bucle infinito pidiendo lo mismo.
+          return [filas, false] if clave.nil?
+        end
+
+        [filas, true]
+      end
+
+      def pedir(ejercicio:, periodo:, clave:)
+        consulta = Consulta.new(
+          nif_obligado: cadena.nif_obligado, nombre_obligado: cadena.nombre_obligado,
+          ejercicio: ejercicio, periodo: periodo,
+          sistema_informatico: cadena.sistema_informatico, clave_paginacion: clave
+        )
+        RespuestaConsulta.new(transporte.enviar(consulta.to_xml).fetch(:cuerpo))
+      end
+    end
+  end
+end

data/lib/verifactu_rails/libro/registro.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # Una anotación del libro registro: un registro de facturación tal y como se
+    # generó, con su sitio en la cadena.
+    #
+    # Es el SISTEMA DE REGISTRO, no una caché de lo que tiene la AEAT. Está
+    # comprobado que la consulta de la AEAT devuelve una foto por factura y no el
+    # histórico: los eslabones sustituidos desaparecen de allí. Si esta tabla se
+    # pierde, el histórico de la cadena no existe en ninguna otra parte.
+    class Registro < ActiveRecord::Base
+      self.table_name = 'verifactu_registros'
+
+      # Lo que define la posición en la cadena no se toca nunca más. El estado del
+      # envío sí cambia; el encadenamiento no.
+      attr_readonly :cadena_id, :tipo, :id_emisor, :num_serie, :fecha_expedicion,
+                    :tipo_factura, :cuota_total, :importe_total,
+                    :huella, :huella_anterior, :fecha_hora_gen, :payload,
+                    :payload_version, :qr_url
+
+      ESTADOS = %w[pendiente enviando anotado aceptado_con_errores rechazado].freeze
+
+      belongs_to :cadena, class_name: 'VerifactuRails::Libro::Cadena'
+
+      scope :pendientes, -> { where(estado: 'pendiente').order(:id) }
+      scope :con_anomalias, -> { where.not(anomalias: nil) }
+
+      def primero? = huella_anterior == ''
+      def anomalias? = anomalias.present?
+
+      def anomalias_lista
+        anomalias.nil? ? [] : JSON.parse(anomalias).map(&:to_sym)
+      end
+
+      # El eslabón anterior, buscado por su huella. Funciona porque (cadena_id,
+      # huella) es único.
+      def anterior
+        return nil if primero?
+
+        cadena.registros.find_by(huella: huella_anterior)
+      end
+
+      # Para encadenar el siguiente.
+      def a_registro_anterior
+        RegistroAnterior.new(id_emisor: id_emisor, num_serie: num_serie,
+                             fecha_expedicion: fecha_expedicion, huella: huella)
+      end
+
+      # La marca temporal tal y como entró en la huella, con su huso.
+      def momento = Time.iso8601(fecha_hora_gen)
+
+      # Recalcula la huella desde las columnas, sin tocar el payload ni volver a
+      # construir el objeto de dominio. Es lo que permite detectar que alguien
+      # editó la fila: si el recálculo no da lo almacenado, la anotación está
+      # alterada.
+      def huella_recalculada
+        if tipo == 'anulacion'
+          Huella.anulacion(id_emisor: id_emisor, num_serie: num_serie,
+                           fecha_expedicion: fecha_expedicion,
+                           fecha_hora_gen: fecha_hora_gen,
+                           huella_anterior: huella_anterior)
+        else
+          Huella.alta(id_emisor: id_emisor, num_serie: num_serie,
+                      fecha_expedicion: fecha_expedicion, tipo_factura: tipo_factura,
+                      cuota_total: cuota_total, importe_total: importe_total,
+                      fecha_hora_gen: fecha_hora_gen, huella_anterior: huella_anterior)
+        end
+      end
+
+      def huella_cuadra? = huella_recalculada == huella
+    end
+  end
+end

data/lib/verifactu_rails/libro/remesa.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  module Libro
+    # Remisión a la AEAT de los registros que una cadena tiene pendientes.
+    #
+    # Va SEPARADO de anotar! a propósito. El encadenamiento es síncrono y bajo
+    # lock porque no se puede diferir; el envío es asíncrono y reintentable
+    # porque sí. Confundir las dos cosas es lo que llevaría a bloquear una venta
+    # porque la AEAT no responde.
+    #
+    # Sobre el tamaño del lote: agrupar NO es el modo normal. Las FAQs exigen que
+    # la remisión sea "inmediata o sin demora apreciable" a la expedición, así que
+    # un comercio que factura cada diez minutos mandará siempre un registro por
+    # petición. El tope de 1000 es un techo para quien factura rápido, y el lote
+    # acaba siendo del tamaño que dicte el ritmo de facturación, no una decisión.
+    class Remesa
+      MAXIMO = Envio::MAXIMO_REGISTROS
+
+      # Se envían también los que quedaron 'enviando': si un envío dio timeout no
+      # se sabe si llegó, y reintentar es seguro porque un duplicado se trata como
+      # éxito. Dejarlos fuera los abandonaría para siempre.
+      ENVIABLES = %w[pendiente enviando].freeze
+
+      Resultado = Struct.new(:estado, :respuesta, :enviados, keyword_init: true) do
+        def enviado? = estado == :enviado
+      end
+
+      def initialize(cadena, transporte:)
+        @cadena = cadena
+        @transporte = transporte
+      end
+
+      # @return [Resultado] con estado :enviado, :esperando, :nada_pendiente o
+      #   :bloqueada_por_rechazo
+      def enviar!(ahora: Time.now)
+        return sin_enviar(:esperando) if esperando?(ahora)
+        return sin_enviar(:bloqueada_por_rechazo) if rechazo_sin_resolver?
+
+        lote = cadena.registros.where(estado: ENVIABLES).order(:id).limit(MAXIMO).to_a
+        return sin_enviar(:nada_pendiente) if lote.empty?
+
+        marcar_enviando(lote)
+        respuesta = transmitir(lote)
+        aplicar!(lote, respuesta)
+        cadena.update!(no_enviar_antes_de: ahora + respuesta.tiempo_espera.to_i)
+
+        Resultado.new(estado: :enviado, respuesta: respuesta, enviados: lote)
+      end
+
+      private
+
+      attr_reader :cadena, :transporte
+
+      def sin_enviar(estado) = Resultado.new(estado: estado, enviados: [])
+
+      def esperando?(ahora)
+        cadena.no_enviar_antes_de.present? && cadena.no_enviar_antes_de > ahora
+      end
+
+      # Un registro rechazado NO consta en la AEAT, así que todo lo que encadena
+      # detrás apunta a un eslabón que allí no existe. Seguir enviando funcionaría
+      # -está comprobado que la AEAT no valida el eslabón al recibir- y dejaría una
+      # cadena incoherente aceptada en silencio. Se para y se avisa: resolver un
+      # rechazo es una decisión de negocio, no algo que un job deba improvisar.
+      def rechazo_sin_resolver?
+        cadena.registros.exists?(estado: 'rechazado')
+      end
+
+      def marcar_enviando(lote)
+        cadena.registros.where(id: lote.map(&:id)).update_all(estado: 'enviando')
+      end
+
+      def transmitir(lote)
+        xml = Envio.xml_desde_fragmentos(
+          nif_obligado: cadena.nif_obligado, nombre_obligado: cadena.nombre_obligado,
+          fragmentos: lote.map(&:payload)
+        )
+        Respuesta.new(transporte.enviar(xml).fetch(:cuerpo))
+      end
+
+      def aplicar!(lote, respuesta)
+        por_serie = respuesta.lineas.group_by(&:num_serie)
+        lote.each do |fila|
+          linea = por_serie[fila.num_serie]&.shift
+          next if linea.nil? # sin veredicto: se queda 'enviando' y se reintenta
+
+          fila.update!(estado: estado_de(linea), csv: respuesta.csv,
+                       codigo_error: linea.codigo_error,
+                       descripcion_error: descripcion_de(linea),
+                       enviado_at: Time.now)
+        end
+      end
+
+      # Un duplicado es un ÉXITO, no un fallo: significa que el registro ya consta
+      # en la AEAT, que es justo lo que se quería. Pasa al reintentar un envío que
+      # dio timeout. La validación local de numeración hace que un choque real no
+      # pueda existir en la tabla, así que este caso es casi siempre el reintento.
+      #
+      # "Casi siempre" no es "siempre": podría venir de otro sistema facturando
+      # para el mismo obligado. Por eso el estado del duplicado se guarda en la
+      # descripción en vez de tragárselo, y si figura Anulada hay un problema real.
+      def estado_de(linea)
+        return 'anotado' if linea.duplicado?
+        return 'anotado' if linea.correcto?
+        return 'aceptado_con_errores' if linea.aceptado_con_errores?
+
+        'rechazado'
+      end
+
+      def descripcion_de(linea)
+        return linea.descripcion_error unless linea.duplicado?
+
+        "Duplicado: el registro ya constaba en la AEAT con estado " \
+          "#{linea.duplicado.estado} (petición #{linea.duplicado.id_peticion}). " \
+          "#{linea.descripcion_error}".strip
+      end
+    end
+  end
+end

data/lib/verifactu_rails/libro.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'json'
+
+begin
+  require 'active_record'
+rescue LoadError
+  raise LoadError, <<~TXT
+    verifactu_rails/libro necesita ActiveRecord y no se ha podido cargar.
+
+    La gema lo declara como dependencia, así que esto suele significar un bundle
+    a medias o que se ha copiado lib/ a mano. Con `bundle install` debería bastar.
+
+    Si lo que quieres es solo calcular huellas y generar XML, no cargues esta
+    capa: `require 'verifactu-rails'` no necesita ActiveRecord para nada.
+  TXT
+end
+
+require_relative '../verifactu-rails'
+
+module VerifactuRails
+  # El libro registro: la capa de persistencia.
+  #
+  # Se carga APARTE del núcleo (`require 'verifactu_rails/libro'`), porque exige
+  # ActiveRecord y el núcleo no depende de Rails. Quien solo quiera generar XML y
+  # huellas no arrastra nada de esto.
+  #
+  # POR QUÉ ESTA CAPA EXISTE. No es una caché de lo que tiene la AEAT: es el
+  # sistema de registro. Está comprobado que la consulta de la AEAT devuelve una
+  # foto por factura, no el histórico, así que los eslabones sustituidos por una
+  # subsanación desaparecen de allí. El histórico de la cadena no existe en
+  # ninguna otra parte.
+  module Libro
+    # Lo que identifica al SOFTWARE. Lo que identifica a la INSTALACIÓN
+    # (NumeroInstalacion) y al obligado va en la tabla de cadenas, no aquí: hay
+    # una instalación por fuente de facturación, no una por despliegue.
+    Configuracion = Struct.new(:productor_nombre, :productor_nif, :nombre_sistema,
+                               :id_sistema, :version, :multi_ot, :multiples_ot,
+                               :entorno, :al_detectar_anomalia,
+                               keyword_init: true) do
+      def sistema_para(cadena)
+        SistemaInformatico.new(
+          nombre_razon: productor_nombre, nif: productor_nif,
+          nombre_sistema: nombre_sistema, id_sistema: id_sistema, version: version,
+          numero_instalacion: cadena.numero_instalacion,
+          multi_ot: multi_ot || false, multiples_ot: multiples_ot || false
+        )
+      end
+    end
+
+    class << self
+      def configuracion
+        @configuracion ||= Configuracion.new(entorno: :pruebas)
+      end
+
+      def configure = yield(configuracion)
+
+      # El fragmento XML del registro, ya construido y con su huella dentro. Se
+      # guarda hecho para que lo que se envíe sea exactamente lo que se calculó:
+      # si nadie vuelve a derivarlo, la huella y el XML no pueden divergir.
+      #
+      # Los namespaces se declaran en el propio fragmento aunque luego se anide
+      # dentro del envío, que los repite: es redundante pero válido, y hace que
+      # cada fragmento se pueda leer y validar por separado.
+      def fragmento_xml(registro, anterior)
+        constructor = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+          xml['sum'].RegistroFactura('xmlns:sum' => NS_LR, 'xmlns:sum1' => NS_SF) do
+            registro.construir(xml, anterior: anterior)
+          end
+        end
+        constructor.doc.root.to_xml
+      end
+
+      # Las anomalías del art. 7.i no interrumpen la facturación, pero tienen que
+      # llegar a alguien. Por defecto no se hace nada: quien despliega decide si
+      # las manda a un log, a Sentry o a un panel.
+      def avisar_de(anomalias, registro)
+        configuracion.al_detectar_anomalia&.call(anomalias, registro)
+      end
+    end
+  end
+end
+
+require_relative 'libro/migracion'
+require_relative 'libro/cadena'
+require_relative 'libro/registro'
+require_relative 'libro/autochequeo'
+require_relative 'libro/remesa'
+require_relative 'libro/reconciliacion'

data/lib/verifactu_rails/qr.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'error'
+
+module VerifactuRails
+  # URL de cotejo del código QR que debe llevar la factura.
+  #
+  # La AEAT NO devuelve esta URL en ninguna respuesta: la construye el propio SIF
+  # con datos que ya tiene. Por eso el QR no depende del envío y se puede generar
+  # en el momento de crear el registro, aunque la AEAT esté caída.
+  #
+  # Ojo al matiz: que el QR sea válido no significa que la factura conste. Si el
+  # envío nunca llega a completarse, quien escanee obtendrá un "no consta".
+  module QR
+    # El host NO es el de los envíos: el cotejo va por prewww2 / www2, mientras
+    # que el SOAP va por prewww1/prewww10 y www1/www10.
+    BASES = {
+      pruebas: 'https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR',
+      produccion: 'https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR'
+    }.freeze
+
+    module_function
+
+    # @param registro [RegistroAlta]
+    def url(registro, entorno: :pruebas)
+      componer(nif: registro.id_emisor, num_serie: registro.num_serie,
+               fecha: registro.fecha_expedicion, importe: registro.importe_total,
+               entorno: entorno)
+    end
+
+    # Los cuatro parámetros sueltos. Se expone aparte del registro para poder
+    # reproducir el ejemplo oficial del PDF, cuya fecha (01-01-2024) es anterior
+    # a la entrada en vigor y por tanto no se puede montar como RegistroAlta.
+    def componer(nif:, num_serie:, fecha:, importe:, entorno: :pruebas)
+      base = BASES.fetch(entorno) do
+        raise ValidacionError, "Entorno desconocido para el QR: #{entorno.inspect}"
+      end
+      pares = { 'nif' => nif, 'numserie' => num_serie,
+                'fecha' => fecha, 'importe' => importe }
+
+      "#{base}?#{pares.map { |k, v| "#{k}=#{codificar(v)}" }.join('&')}"
+    end
+
+    # El PDF de especificaciones dedica un apartado a esto y pone como
+    # contraejemplo un numserie=12345678&G33 sin codificar, que parte la URL. Y el
+    # caso es alcanzable: Formato.num_serie prohíbe " ' < > = pero SÍ admite &, %,
+    # + y espacios.
+    #
+    # El espacio se codifica como %20 y no como "+": ambos son válidos en un query
+    # string, pero "+" solo se interpreta como espacio bajo
+    # application/x-www-form-urlencoded, y aquí no hay forma de saber cómo lo
+    # decodifica la AEAT. %20 significa espacio en cualquier lectura.
+    def codificar(valor) = URI.encode_www_form_component(valor.to_s).gsub('+', '%20')
+  end
+end

data/lib/verifactu_rails/railtie.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module VerifactuRails
+  # Enganche con Rails. Se carga SOLO si Rails está delante (ver el final de
+  # lib/verifactu-rails.rb): el núcleo -huella, XML, transporte- no depende de
+  # Rails y no debe empezar a depender por esto.
+  #
+  # Hace una sola cosa: cargar la capa Libro cuando ActiveRecord esté listo.
+  #
+  # Fuera de Rails esa capa es opt-in a propósito (`require
+  # 'verifactu_rails/libro'`), porque exige ActiveRecord y quien solo quiera
+  # calcular huellas no tiene por qué arrastrarlo. Dentro de Rails ActiveRecord
+  # está siempre, así que mantener el require manual solo conseguiría que
+  # `Cadena` no existiera hasta que alguien se acordara de escribirlo.
+  #
+  # Va por `on_load(:active_record)` y no por un require directo porque
+  # libro.rb declara modelos, y declarar un modelo fuerza la carga de
+  # ActiveRecord::Base. Hacerlo en el arranque le quita a la app la carga
+  # diferida para todo el resto.
+  #
+  # Los generadores NO se registran aquí: Rails los descubre solo buscando
+  # lib/generators/**/*_generator.rb por el $LOAD_PATH.
+  class Railtie < ::Rails::Railtie
+    initializer 'verifactu.libro' do
+      ActiveSupport.on_load(:active_record) do
+        require 'verifactu_rails/libro'
+      end
+    end
+  end
+end