verifactu-rails 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cce658f6fc7e521b621da490c3e3dac1e1e3045ab0daad5d7d23f2b467276ad6
+  data.tar.gz: 6c00392ff5e3ebfbe4560b9928c5748f23bd9eb16c3cc46d0a0f46bec7593c4e
+SHA512:
+  metadata.gz: fc8492295003368381071c2a0754e790e69edd714660ddf1baad2869b9a02ebe57ca8c67e6db6dd168a80e0dc92f7d1134c644fcfb42e633e261acdded35cafe
+  data.tar.gz: 0dc9752420bba0ef62fe72297ab7bce5267c5d629f4c0a73b277b69c8a86f2a436d22a18e75ecc92cb13b2a8e7f4639da009082711d962b164b48c3b3e086e52

data/COMPLIANCE.md

@@ -0,0 +1,149 @@
+# Cumplimiento: qué cubre esta gema y qué te sigue tocando a ti
+
+Este documento delimita responsabilidades. No es asesoramiento legal, no es una
+certificación, y **usar `verifactu-rails` no te hace cumplidor** del RD 1007/2023
+ni de la Orden HAC/1177/2024. Es un componente de tu sistema de facturación; el
+sistema es tuyo.
+
+Las citas normativas de aquí vienen de las fuentes recogidas en
+[doc/FUENTES.md](doc/FUENTES.md) (el propio texto de la Orden, las FAQs de
+Desarrolladores y los PDF de Validaciones de la AEAT). Antes de apoyarte en
+cualquiera de ellas para una decisión con consecuencias, contrástala con el BOE:
+esto es documentación de una librería, no una fuente jurídica.
+
+## Quién responde de qué
+
+La pieza que ordena todo lo demás: **la declaración responsable del art. 13 la
+firma quien produce el sistema informático de facturación**, y quien produce el
+SIF eres tú, no esta gema. Si desarrollas el software para tu propio uso, eres
+productor y usuario a la vez; si lo vendes, sigues siendo el productor.
+
+Además, la obligación de trazabilidad recae legalmente sobre el productor y no
+solo sobre quien factura (art. 29.2.j LGT). Certificar por declaración
+responsable un SIF que no cumple el RD 1007/2023 es sancionable.
+
+Consecuencia práctica: nadie va a mirar el `Gemfile` de tu aplicación para
+repartir culpas. Lo que se mira es el sistema que has declarado.
+
+## Alcance: solo VERI\*FACTU
+
+Esta gema implementa **únicamente la modalidad VERI\*FACTU**, la de remisión
+continua a la AEAT. No implementa el modo NO VERI\*FACTU, que exigiría firma
+XAdES de cada registro y llevar registro de eventos.
+
+Esa reducción de alcance es legítima y la AEAT la contempla explícitamente (FAQs
+Desarrolladores v1.3, ap. 15, nota 1). Se refleja en el código: el campo
+`TipoUsoPosibleSoloVerifactu` va fijo a `'S'` y **no se puede configurar**.
+Declarar `'N'` significaría que tu SIF puede operar en modo no VERI\*FACTU, y eso
+te obligaría a un registro de eventos que aquí no existe. Si necesitas `'N'`,
+esta no es tu librería.
+
+## Qué pone la gema
+
+| Requisito | Dónde |
+|---|---|
+| Huella SHA-256 con serialización canónica, alta y anulación | `Huella` |
+| Encadenamiento de cada registro con el anterior | `Libro::Cadena#anotar_alta!`, bajo lock |
+| Imposibilidad de bifurcar la cadena | índice único `(cadena_id, huella_anterior)` |
+| Comprobaciones del art. 7.i) antes de generar cada registro | `Libro::Autochequeo` |
+| Orden cronológico de generación | serialización bajo `SELECT … FOR UPDATE` |
+| XML conforme a los XSD de la AEAT | `RegistroAlta` / `RegistroAnulacion` / `Envio` |
+| Remisión con TLS mutuo al endpoint correcto | `Transporte` |
+| Reenvío de lo pendiente, con control de flujo y reintentos | `Libro::Remesa` |
+| URL de cotejo del código QR | `QR` |
+| Contraste contra lo que la AEAT tiene anotado | `Libro::Reconciliacion` |
+| Conservación del registro tal y como se remitió | columna `payload` del libro |
+
+Sobre la última fila, que es la que más peso tiene si algún día hay una
+inspección: el libro guarda el **fragmento XML ya construido**, no los argumentos
+con que se construyó. Lo que se envía es exactamente lo que se calculó, y la
+huella se puede recalcular años después desde las columnas sin volver a derivar
+nada.
+
+## Qué NO pone la gema, y tienes que poner tú
+
+- **La declaración responsable.** Ver arriba.
+- **El registro de eventos.** No existe. Solo hace falta en modo NO VERI\*FACTU,
+  que está fuera de alcance, pero conviene que sepas por qué no está.
+- **La imagen del código QR.** La gema construye la URL de cotejo; convertirla en
+  un QR y ponerlo en la factura es tuyo. La AEAT no devuelve esa URL: la
+  construye el SIF.
+- **La factura en sí.** Esto no es un sistema de facturación: no numera, no
+  calcula impuestos, no emite PDF ni gestiona clientes.
+- **La custodia del certificado.** `Certificado` recibe los bytes ya cargados y
+  deliberadamente no sabe leer ficheros ni variables de entorno. Dónde vive el
+  `.p12` y quién puede leerlo es decisión y responsabilidad tuyas.
+- **El `NumeroInstalacion`.** No se autogenera **nunca**, y no es un descuido: si
+  la gema lo inventara, un contenedor que se recrea en cada despliegue abriría
+  una instalación por despliegue y la cadena dejaría de demostrar nada. Elegirlo
+  —y no reutilizarlo jamás, ni al reinstalar el mismo software en la misma
+  máquina— es un acto deliberado tuyo.
+- **La conservación y el respaldo del libro.** Ver el apartado siguiente, porque
+  es el punto que más se subestima.
+- **La política de retención, acceso y borrado** de los datos, y todo lo que
+  tenga que ver con protección de datos.
+
+## Tres límites que conviene entender antes de firmar nada
+
+**1. El libro local es el sistema de registro, no una caché.** Está comprobado
+contra el servicio real que la consulta de la AEAT devuelve **una foto por
+factura, no el histórico**: una subsanación sustituye al alta original y la
+anulación sustituye a lo anulado, así que los eslabones intermedios desaparecen.
+Si pierdes la tabla `verifactu_registros`, el histórico de tu cadena no existe en
+ninguna otra parte. Respáldala como respaldarías la contabilidad.
+
+**2. La AEAT acepta una cadena bifurcada sin avisar.** Comprobado, también contra
+el servicio real. No valida el eslabón al recibir, así que un encadenamiento
+incoherente se aceptaría en silencio y quedaría anotado. La única red que hay es
+el índice único local. Si migras el esquema a mano, o replicas la tabla, o
+permites escrituras que esquiven `anotar_alta!`, esa red desaparece y no te vas a
+enterar por la AEAT.
+
+**3. Una anomalía de trazabilidad no interrumpe la facturación, por norma.** El
+autochequeo del art. 7.i) se anota y se notifica, pero **no lanza excepción**: la
+Orden dice que ante una anomalía la facturación "nunca debe interrumpirse".
+Traducción operativa: si no enganchas `al_detectar_anomalia` a algo que mires de
+verdad, las anomalías se pierden. Que no bloqueen no significa que no importen.
+
+## Cómo demostrar que esto hace lo que dice
+
+Si tienes que justificar el componente ante un cliente o un auditor, esto es lo
+que hay:
+
+- **Suite de tests** que incluye un caso con ocho hilos demostrando que la cadena
+  no se puede bifurcar (quitando el lock, para que el índice tenga que
+  sostenerlo), y validación de todo el XML contra los XSD oficiales de la AEAT,
+  que se versionan en el repo con su procedencia documentada.
+- **[doc/FUENTES.md](doc/FUENTES.md)**: el registro de qué se ha contrastado
+  contra el servicio real de preproducción, con fechas y resultados. Incluye lo
+  que salió distinto de lo esperado y lo que sigue siendo suposición.
+- **`Libro::Reconciliacion`**: contraste de solo lectura entre tu libro y lo que
+  la AEAT tiene anotado, factura a factura.
+- **`Registro#huella_cuadra?`**: recalcula la huella desde las columnas
+  almacenadas. Si alguien editó una fila por debajo del modelo, se ve.
+
+## Antes de poner esto en producción
+
+Una lista corta de lo que hay que haber decidido, no de lo que hay que programar:
+
+1. Quién firma la declaración responsable y con qué versión del SIF.
+2. Qué `NumeroInstalacion` lleva cada fuente de facturación, y quién lo asigna.
+   Una por tienda, TPV o sede: son SIF virtuales distintos.
+3. Dónde vive el certificado, quién lo puede leer y qué pasa cuando caduque
+   (`Certificado#caduca_pronto?` avisa, pero alguien tiene que escucharlo).
+4. A dónde van las anomalías del art. 7.i) y quién las mira.
+5. Qué se hace cuando un registro es **rechazado**. La remesa detiene la cadena a
+   propósito, porque seguir enviando dejaría una cadena incoherente aceptada en
+   silencio. Resolverlo es una decisión de negocio, no algo que un job deba
+   improvisar.
+6. Cómo se respalda y se restaura el libro, y cada cuánto se prueba la
+   restauración.
+7. Con qué frecuencia se reconcilia contra la AEAT y quién lee el informe.
+
+## Si algo de aquí no te cuadra
+
+Este documento es tan bueno como lo que hay contrastado detrás, y
+[doc/FUENTES.md](doc/FUENTES.md) dice explícitamente qué está comprobado contra
+el servicio real y qué sigue siendo una suposición razonable. Si encuentras una
+afirmación que no se sostiene, es un fallo del documento y merece un issue igual
+que un fallo del código.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Valero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,404 @@
+# verifactu-rails
+
+Integración con **VERI\*FACTU** (AEAT) para aplicaciones Rails: libro registro
+encadenado, remisión a la AEAT y reconciliación de lo anotado.
+
+Es una librería, no un sistema de facturación: calcula la huella encadenada,
+genera el XML de los registros y habla con la AEAT por TLS mutuo. No numera
+facturas, no calcula impuestos y no emite PDF.
+
+> **Estado: en desarrollo, sin release público.** Ejercitada de punta a punta
+> contra el entorno de pruebas de la AEAT —altas encadenadas, lotes, anulación,
+> rectificativa, subsanación y reconciliación—. La API puede cambiar sin aviso.
+
+**Solo modalidad VERI\*FACTU** (remisión continua). El modo NO VERI\*FACTU
+exigiría firma XAdES y registro de eventos, y no se implementa; la AEAT contempla
+esta reducción de alcance (FAQs Desarrolladores v1.3, ap. 15, nota 1). Fuera de
+alcance: Facturae/B2G, TicketBAI/Batuz, TPV.
+
+Usar esta gema no te hace cumplidor del RD 1007/2023 ni de la Orden HAC/1177/2024.
+Quién responde de qué está en **[COMPLIANCE.md](COMPLIANCE.md)**, y conviene
+leerlo antes de poner esto en producción.
+
+## Requisitos
+
+- Ruby >= 3.0, Rails >= 7.0
+- Certificado del obligado tributario en PKCS12. Vale el de representante, que es
+  el camino contrastado contra el servicio real. El de sello de entidad también
+  está soportado (la AEAT le da endpoints propios); con él, declara `sello: true`
+  explícitamente en `Transporte`.
+
+## Instalación
+
+```ruby
+# Gemfile
+gem 'verifactu-rails'
+```
+
+```sh
+rails g verifactu:install
+rails db:migrate
+```
+
+El generador deja la migración del libro y `config/initializers/verifactu.rb`. La
+migración no copia el esquema: hereda de `VerifactuRails::Libro::Migracion`, así
+que lo que instalas es exactamente lo que ejercita la suite de tests de la gema.
+
+## Puesta en marcha
+
+### 1. Identifica tu SIF
+
+En el initializer que dejó el generador. Describe **tu** sistema, no esta gema:
+verifactu-rails es un componente del SIF, no el SIF. Viene con valores inválidos
+a propósito, para que falle pronto en vez de remitir una identificación
+inventada.
+
+```ruby
+VerifactuRails::Libro.configure do |c|
+  c.productor_nombre = 'Tu Empresa SL'   # quién PRODUCE el software
+  c.productor_nif    = '89890001K'
+  c.nombre_sistema   = 'TuFactura'
+  c.id_sistema       = '01'              # dos posiciones, mayúscula o dígito
+  c.version          = TuApp::VERSION
+  c.entorno          = Rails.env.production? ? :produccion : :pruebas
+
+  # Las anomalías del art. 7.i) no interrumpen la facturación, pero si no las
+  # mandas a algún sitio que mires, se pierden.
+  c.al_detectar_anomalia = ->(anomalias, registro) { Rails.logger.warn(...) }
+end
+```
+
+### 2. Abre una cadena por fuente de facturación
+
+Una vez, y a conciencia: en un seed, una tarea rake o tu panel de administración.
+Nunca en un initializer. Cada tienda, TPV o sede es un SIF virtual distinto y
+lleva su propia cadena.
+
+```ruby
+VerifactuRails::Libro::Cadena.abrir!(
+  numero_instalacion: 'TIENDA-VALENCIA-20260807120000',
+  nif_obligado: '89890001K', nombre_obligado: 'Tu Empresa SL'
+)
+```
+
+El `numero_instalacion` **no se autogenera nunca** y no se reutiliza jamás, ni al
+reinstalar el mismo software en la misma máquina. Guárdalo en tu modelo (la
+tienda, el TPV) para recuperar la cadena después.
+
+### 3. Anota cada factura
+
+```ruby
+cadena = VerifactuRails::Libro::Cadena.find_by!(numero_instalacion: tienda.numero_instalacion)
+
+registro = cadena.anotar_alta!(
+  id_emisor: '89890001K', num_serie: 'FA/2026/0001',
+  fecha_expedicion: Date.current, nombre_razon_emisor: 'Tu Empresa SL',
+  tipo_factura: 'F1', descripcion_operacion: 'Servicios de agosto',
+  desglose: [VerifactuRails::Detalle.new(base_imponible: BigDecimal('100.00'),
+                                         calificacion: 'S1',
+                                         tipo_impositivo: BigDecimal('21.00'),
+                                         cuota_repercutida: BigDecimal('21.00'))],
+  cuota_total: BigDecimal('21.00'), importe_total: BigDecimal('121.00'),
+  fecha_hora_gen: Time.now,
+  destinatarios: [VerifactuRails::Destinatario.new(nombre_razon: 'Cliente SL',
+                                                   nif: '89890002E')]
+)
+
+registro.qr_url   # ya disponible: el QR no depende de la AEAT
+```
+
+Calcula la huella, encadena y genera el QR en una transacción con la fila de la
+cadena bloqueada. Es síncrono a propósito: el encadenamiento no se puede diferir,
+aunque el envío sí. También hay `anotar_anulacion!`.
+
+### 4. Envía
+
+```ruby
+class EnviarRemesaJob < ApplicationJob
+  def perform(numero_instalacion)
+    cadena = VerifactuRails::Libro::Cadena.find_by!(numero_instalacion: numero_instalacion)
+    certificado = VerifactuRails::Certificado.desde_pkcs12(bytes_del_p12, password)
+    transporte  = VerifactuRails::Transporte.new(
+      certificado: certificado, entorno: VerifactuRails::Libro.configuracion.entorno
+    )
+
+    VerifactuRails::Libro::Remesa.new(cadena, transporte: transporte).enviar!
+    # => #<Resultado estado: :enviado|:esperando|:nada_pendiente|:bloqueada_por_rechazo>
+  end
+end
+```
+
+La remesa no recibe registros: coge de la base de datos lo que esa cadena tenga
+pendiente. Encólalo tras `anotar_alta!` y ponle además un cron de seguridad por
+si un job se perdió; es idempotente, y un duplicado cuenta como éxito.
+
+Construye certificado y transporte **dentro del job**, no al arrancar:
+`Transporte` no guarda conexión (reutilizarlo no ahorra ningún handshake) y
+`Certificado` comprueba la caducidad al construirse, que es un aviso que pierdes
+si lo cacheas durante meses.
+
+### 5. Reconcilia
+
+La respuesta a un envío dice si la AEAT **aceptó** el registro; no dice qué queda
+almacenado después. La consulta añade `Anulado`, un estado que el canal de envío
+ni siquiera puede expresar.
+
+```ruby
+informe = VerifactuRails::Libro::Reconciliacion
+          .new(cadena, transporte: transporte)
+          .revisar(ejercicio: 2026, periodo: 8)
+
+informe.cuadra?      # => true si el libro y la AEAT dicen lo mismo de cada factura
+informe.divergencias # => [#<Divergencia tipo: :no_consta, num_serie: 'FA/7', ...>]
+```
+
+Solo lee: nunca corrige el libro. Los tipos de divergencia son `:no_consta`,
+`:huella_distinta`, `:estado_distinto`, `:consta_sin_enviar` y `:solo_en_aeat`.
+
+## Lo que conviene saber antes de integrarlo
+
+- **El libro local es el sistema de registro, no una caché.** La consulta de la
+  AEAT devuelve una foto por factura, no el histórico: una subsanación sustituye
+  al alta original y desaparece de allí. Si pierdes la tabla, el histórico de tu
+  cadena no existe en ninguna otra parte. Respáldala.
+- **Bifurcar la cadena es imposible por un índice único**, no por el lock. La
+  AEAT acepta una cadena bifurcada sin avisar, así que esa restricción es la
+  única red que hay.
+- **Una anomalía nunca interrumpe la facturación.** El autochequeo del art. 7.i)
+  se anota y se notifica, pero no lanza: la norma dice que la facturación "nunca
+  debe interrumpirse". Con datos inválidos sí se falla, que ahí tampoco hay
+  factura que emitir.
+- **Un rechazo detiene la cadena.** Lo rechazado no consta en la AEAT y todo lo
+  que encadena detrás apuntaría a un eslabón inexistente. Resolverlo es una
+  decisión de negocio.
+- **Agrupar no es el modo normal.** Las FAQs exigen remisión "inmediata o sin
+  demora apreciable"; el tope de 1000 por envío es un techo para quien factura
+  rápido, no un objetivo.
+- **`Float` está prohibido** en importes: usa `BigDecimal`, `Integer` o `String`.
+  La huella se calcula sobre el string del importe y la AEAT la recalcula sobre
+  el XML, así que el importe tiene que ser exacto y su formateo determinista;
+  `Float` no da ninguna de las dos cosas. El redondeo se fija explícitamente a
+  `ROUND_HALF_UP` porque `BigDecimal.mode` es estado global del proceso.
+- **Los espacios al borde se rechazan**, no se recortan. Es más estricto que la
+  norma a propósito: casi siempre son un defecto de los datos de origen.
+- **Nunca `VERIFY_NONE`.** Desde noviembre de 2025 la AEAT sirve con CA públicas,
+  así que `ca_file` no hace falta. Si falla, sospecha del almacén del sistema o
+  de un proxy que intercepte el TLS.
+- **Los números de factura anulada no se reutilizan.** La excepción es la
+  subsanación, que reusa el mismo `IDFactura` a propósito con `subsanacion: 'S'`.
+
+El porqué de cada una, con lo que se comprobó contra el servicio real, está en
+[doc/FUENTES.md](doc/FUENTES.md).
+
+## Tipos de factura
+
+`tipo_factura:`. Las descripciones son literales del XSD oficial, que va
+versionado en el repo:
+
+| Clave | Qué es | Destinatario | Exige además |
+|---|---|---|---|
+| `F1` | Factura (art. 6, 7.2 y 7.3 del RD 1619/2012) | obligatorio | — |
+| `F2` | Factura simplificada y facturas sin identificación del destinatario (art. 6.1.d) | **prohibido** | — |
+| `F3` | Factura emitida en sustitución de facturas simplificadas facturadas y declaradas | obligatorio | `facturas_sustituidas:` (opcional) |
+| `R1` | Rectificativa (art. 80.1 y 80.2 y error fundado en derecho) | obligatorio | `tipo_rectificativa:` |
+| `R2` | Rectificativa (art. 80.3) | obligatorio | `tipo_rectificativa:` |
+| `R3` | Rectificativa (art. 80.4) | obligatorio | `tipo_rectificativa:` |
+| `R4` | Rectificativa (resto) | obligatorio | `tipo_rectificativa:` |
+| `R5` | Rectificativa en facturas simplificadas | **prohibido** | `tipo_rectificativa:` |
+
+La columna del destinatario no es un matiz: en `F2` y `R5` informarlo es un
+error, y en los demás omitirlo también. `facturas_rectificadas:` es opcional pero
+exclusiva de `R1`–`R5`, y `Cupon` solo se admite con `R1` o `R5`.
+
+### Rectificativas: sustitutiva o incremental
+
+- **`'S'` sustitutiva** — la factura reexpresa el importe corregido completo, así
+  que hay que declarar el original en `importe_rectificacion:`.
+- **`'I'` incremental** — los importes ya *son* la diferencia, y
+  `importe_rectificacion:` se rechaza.
+
+El XSD deja casi todos estos campos opcionales, así que estas reglas las impone
+la gema: sin ellas se monta un `R1` válido para el esquema que la AEAT rechaza
+con un error mucho menos claro.
+
+## Calificación de cada línea del desglose
+
+Cada `Detalle` lleva **o** `calificacion:` **o** `exenta:`, exactamente una. No es
+una preferencia de la gema: el esquema las modela como un `choice`, así que
+informar las dos —o ninguna— produce un documento inválido.
+
+| Clave | Qué significa |
+|---|---|
+| `S1` | Operación sujeta y no exenta, **sin** inversión del sujeto pasivo |
+| `S2` | Operación sujeta y no exenta, **con** inversión del sujeto pasivo |
+| `N1` | Operación no sujeta (art. 7, 14, otros) |
+| `N2` | Operación no sujeta por reglas de localización |
+
+```ruby
+# Lo normal: sujeta y no exenta, con su tipo y su cuota.
+Detalle.new(base_imponible: BigDecimal('100.00'), calificacion: 'S1',
+            tipo_impositivo: BigDecimal('21.00'),
+            cuota_repercutida: BigDecimal('21.00'))
+
+# Exenta: el importe va en base_imponible y NO se informa tipo ni cuota.
+Detalle.new(base_imponible: BigDecimal('100.00'), exenta: 'E1')
+```
+
+Tres reglas que conviene tener presentes, porque la AEAT tiene un código de error
+para cada una:
+
+- **`N1`, `N2` y las exentas no admiten** `tipo_impositivo:`, `cuota_repercutida:`
+  ni recargo. Informarlos da error 1237 o 1238.
+- **`S2` (inversión del sujeto pasivo) solo cabe en `F1`, `F3` y `R1`–`R4`.**
+- **`E7` y `E8` solo existen con IGIC.** Para IVA, las exenciones son `E1`–`E6`.
+
+### Causas de exención
+
+El XSD las lleva desnudas, sin descripción. La correspondencia es esta, en
+palabras de la propia AEAT, y los artículos son de la Ley 37/1992 del IVA:
+
+| Clave | Texto de la AEAT | De qué trata ese artículo |
+|---|---|---|
+| `E1` | *exenta por el artículo 20* | Exenciones en operaciones interiores |
+| `E2` | *exenta por el artículo 21* | Exportaciones de bienes |
+| `E3` | *exenta por el artículo 22* | Operaciones asimiladas a las exportaciones |
+| `E4` | *exenta por los artículos 23 y 24* | Zonas y depósitos francos, regímenes aduaneros y fiscales |
+| `E5` | *exenta por el artículo 25* | Entregas intracomunitarias |
+| `E6` | *exenta por otros* | El resto |
+
+La AEAT añade que **si no se dispone de esa información basta con indicar que la
+operación es exenta**. Ojo: eso vale para el libro registro, pero el esquema de
+VERI\*FACTU exige un valor concreto en `OperacionExenta`, así que en la práctica
+hay que elegir uno; `E6` es el cajón previsto para ello.
+
+El mapeo sale de la documentación del SII, que comparte esta lista de códigos,
+porque la documentación técnica de VERI\*FACTU no la desarrolla. Las FAQs de la
+propia AEAT sobre el libro registro lo corroboran para los dos casos que citan
+con nombre: exportaciones (`E2`) y entregas intracomunitarias (`E5`).
+
+### Impuesto, régimen y tipos
+
+`impuesto:` y `clave_regimen:` van **en cada línea del desglose**, no en la
+factura: son parámetros de `Detalle`. En los ejemplos de arriba no se ven porque
+tienen valor por defecto —`'01'` en los dos, IVA y régimen general—, que es el
+caso normal. Explícitos:
+
+```ruby
+Detalle.new(base_imponible: BigDecimal('50.00'), calificacion: 'S1',
+            impuesto: '03', clave_regimen: '01',        # IGIC
+            tipo_impositivo: BigDecimal('7.00'),
+            cuota_repercutida: BigDecimal('3.50'))
+```
+
+Cada línea acaba en su propio `<DetalleDesglose>` con su `<Impuesto>`, así que
+**una misma factura puede mezclar impuestos**. Los valores son `01` IVA, `02`
+IPSI, `03` IGIC y `05` otros.
+
+### Clave de régimen
+
+Y aquí está la trampa: **qué significa `clave_regimen:` depende del impuesto**.
+Las claves `18`, `19` y `20` no quieren decir lo mismo en IVA que en IPSI, así
+que copiar un valor de un ejemplo de IVA a una línea de IPSI declara otra cosa.
+
+Qué admite cada impuesto (la gema lo valida y rechaza el resto):
+
+| Impuesto | Claves admitidas |
+|---|---|
+| `01` IVA | `01`–`11`, `14`, `15`, `17`, `18`, `19`, `20` (lista L8A) |
+| `03` IGIC | las de L8A más `20` (operaciones sujetas al IPSI) y `21` (régimen simplificado) |
+| `02` IPSI | solo `01`, `08`, `11`, `18`, `19`, `20`, y con significado propio |
+| `05` Otros | **ninguna**: el campo no se puede informar en absoluto |
+
+Las de IPSI, en palabras de la AEAT: `01` régimen general, `08` operaciones
+sujetas al IGIC/IVA, `11` arrendamiento de local de negocio, `18` operaciones del
+art. 73.4 y 5 de la Ordenanza fiscal IPSI (solo Ceuta), `19` operaciones
+interiores exentas y `20` régimen de estimación objetiva.
+
+Para IVA las más frecuentes son `01` régimen general, `02` exportación, `07`
+criterio de caja, `11` arrendamiento de local de negocio sujeto a retención y
+`18` recargo de equivalencia. La lista completa con su descripción es la L8A de
+los Diseños de registro de la AEAT; aquí no se reproduce entera porque cambia con
+las versiones y no queremos una copia que envejezca en silencio.
+
+Cada clave arrastra además sus propias reglas, que la gema aplica antes de
+enviar (Validaciones ap. 15.6): con `02` solo cabe `OperacionExenta`; con `03`,
+si hay calificación, solo `S1`; con `04`, `S2` o exenta; con `07` no valen `S2`,
+`N1`, `N2` ni las exenciones `E2`–`E5`; con `08` y con `20` en IGIC tiene que ser
+`N2`; con `11` el único tipo admitido es el 21; con `10` la factura tiene que ser
+`F1` y todos los destinatarios llevar NIF; y con `14` hace falta `fecha_operacion:`
+posterior a la de expedición y destinatarios con NIF de administración pública.
+
+Dos avisos sobre esto:
+
+- **En IPSI no aplican.** La norma las acota a IVA e IGIC, y en IPSI las claves
+  `18`, `19` y `20` significan otra cosa. La gema respeta esa frontera.
+- **La clave `06` no se puede usar.** Exige `BaseImponibleACoste`, un campo que
+  la gema no emite, así que se rechaza en local con ese motivo en vez de armar un
+  registro que la AEAT va a rechazar igual.
+
+Los tipos impositivos de IVA y el recargo de equivalencia que admite cada uno se
+validan contra la fecha de la operación:
+
+| Tipo | Recargo de equivalencia admitido | Vigencia del tipo |
+|---|---|---|
+| `21.00` | `5.20` o `1.75` | siempre |
+| `10.00` | `1.40` | siempre |
+| `4.00` | `0.50` | siempre |
+| `0.00` | `0.00`, y solo entre 01-01-2023 y 30-09-2024 | siempre |
+| `5.00` | `0.50` hasta 31-12-2022; `0.62` desde 01-01-2023 | **01-07-2022 – 30-09-2024** |
+| `2.00` | `0.26` | **01-10-2024 – 31-12-2024** |
+| `7.50` | `1.00` | **01-10-2024 – 31-12-2024** |
+
+Las dos columnas se validan por separado: un tipo puede estar vigente y aun así
+rechazarse el recargo que le acompañe.
+
+Los tres marcados fueron rebajas temporales. Y aquí hay una consecuencia que
+sorprende: como `FechaExpedicionFactura` no puede ser anterior al 28-10-2024,
+**el 5 % ya no es declarable** salvo que informes una `fecha_operacion:` dentro
+de su ventana. Es el origen de los errores 1235 y 1236 de la AEAT.
+
+## Componentes
+
+| Módulo | Qué hace |
+|---|---|
+| `Libro` | Capa Rails: libro registro, encadenamiento bajo lock y autochequeo |
+| `Libro::Remesa` | Envío por lotes de lo pendiente, con control de flujo y reintentos |
+| `Libro::Reconciliacion` | Contraste de solo lectura contra lo que la AEAT tiene anotado |
+| `Huella` | Serialización canónica y SHA-256 del registro |
+| `RegistroAlta` / `RegistroAnulacion` | El registro: calcula su huella y emite su XML |
+| `Envio` | Documento `RegFactuSistemaFacturacion` (lote de hasta 1000) |
+| `Consulta` / `RespuestaConsulta` | Consulta de lo anotado, con paginación |
+| `Certificado` / `Transporte` | PKCS12, caducidad y cliente HTTP con TLS mutuo |
+| `QR` | URL de cotejo. La AEAT no la devuelve: la construye el SIF |
+| `Detalle` / `Desglose` / `Destinatario` / `Tercero` | Piezas del registro |
+| `Importe` / `Formato` | Importes, fechas y NIF normalizados en un único sitio |
+
+## Uso sin Rails
+
+El núcleo no depende de Rails ni de ActiveRecord: `require 'verifactu-rails'` da
+`Huella`, los registros, `Envio`, `Consulta` y `Transporte` para construir y
+remitir el XML por tu cuenta. La capa `Libro` se carga aparte
+(`require 'verifactu_rails/libro'`) y sí exige ActiveRecord.
+
+## Tests
+
+```sh
+createdb verifactu_rails_test   # solo la primera vez
+bundle exec rake test
+```
+
+Los tests del libro necesitan una base de datos de verdad: hay que demostrar que
+un índice único impide bifurcar la cadena y que el lock serializa, y eso no se
+simula con dobles. Si no la encuentra, la suite **aborta** en vez de saltárselos.
+Si el nombre de la base no parece de tests, también aborta: la suite vacía tablas
+y no debe correr contra datos reales.
+
+Incluye los tres vectores oficiales de la AEAT (Especificaciones huella v0.1.2,
+ap. 6), verificación cruzada de la huella contra `josemmo/Verifactu-PHP` y
+`mybooking-es/verifactu-rb`, y validación del XML contra los XSD oficiales,
+versionados en
+[lib/verifactu_rails/schemas](lib/verifactu_rails/schemas/PROCEDENCIA.md).
+
+## Licencia
+
+MIT. Se distribuye sin garantía de ningún tipo; ver [LICENSE](LICENSE).