snoopy_afip 4.3.0 → 4.3.1

data/README.md

@@ -1,238 +1,136 @@
 # snoopy_afip
-conexión con Web Service de Factura Electrónica de AFIP (WSFE)
 
-## Instalación
-
-Añadir esta linea en el Gemfile:
-
-```ruby
-gem 'snoopy_afip'
-```
-
-Luego ejecuta:
-
-    $ bundle
-
-O instala la gema a mano:
-
-    $ gem install snoopy_afip
-
-### Versiones
-
-- `2.1.1`. Usada en producción. (**Stable**)
-- `3.0.0`. Aun en entorono de testing. (**Beta**)
-
-## Antes que nada
-
-* Link con el manual para desarrolladores.
+Gema Ruby que adapta la **Facturación Electrónica de AFIP (Argentina)**. Expone el módulo `Snoopy` y resuelve, vía SOAP (`savon`), los dos servicios de AFIP necesarios para emitir comprobantes electrónicos:
 
-- [Especificación Técnica WSAA]('http://www.afip.gov.ar/ws/WSAA/Especificacion_Tecnica_WSAA_1.2.0.pdf'): Especificación técnica para la comunicación con el **WSAA** (servicio de autenticación), su propósito es solicitar un _tocken_ y _sign_ para poder emitir facturas con el servicio de **WSFE** (Servicio de autorización de facturas)
-
-- [Manual desarrollador](http://www.afip.gob.ar/fe/documentos/manual_desarrollador_COMPG_v2_9.pdf): Especificación técnica para la comunicación con **WSFE** (Servicio de autorización de facturas).
-
-* Es recomendable descargar los **Wsdl** para evitar tener que pedirlo en cada request
-
-- Wsdl **WSAA** (servicio de autenticación)
-
-  - Testing:    [https://wsaahomo.afip.gov.ar/ws/services/LoginCms?wsdl]('https://wsaahomo.afip.gov.ar/ws/services/LoginCms?wsdl')
-  - Producción: [https://wsaa.afip.gov.ar/ws/services/LoginCms?wsdl]('https://wsaa.afip.gov.ar/ws/services/LoginCms?wsdl')
-
-- **WSFE** (Servicio de autorización de facturas)
-
-  - Testing:    [https://wswhomo.afip.gov.ar/wsfev1/service.asmx?wsdl]('https://wswhomo.afip.gov.ar/wsfev1/service.asmx?wsdl')
-  - Producción: [https://servicios1.afip.gov.ar/wsfev1/service.asmx?WSDL]('https://servicios1.afip.gov.ar/wsfev1/service.asmx?WSDL')
-
-* Explicación detallada de los pasos a seguir para obtener el certificado desde el sitio web AFIP para emitir facturas electrónicas.
-
-[obtención de certificado](https://www.afip.gob.ar/ws/WSAA/WSAA.ObtenerCertificado.pdf)
-
-## USO
-
-### Inicialización de parametros generales
-
-```ruby
-Snoopy.default_currency      = :peso
-Snoopy.default_concept       = 'Servicios'
-Snoopy.default_document_type = 'CUIT' || 'DNI' # O alguna key de Snoopy::DOCUMENTS
-# Para el caso de produccion
-Snoopy.auth_url    = 'https://wsaa.afip.gov.ar/ws/services/LoginCms?wsdl' || PATH_WSAA_PROP_WSDL
-Snoopy.service_url = 'https://servicios1.afip.gov.ar/wsfev1/service.asmx?WSDL' || PATH_WSFE_PROP_WSDL
-# Para el caso de desarrollo
-Snoopy.auth_url    = 'https://wsaahomo.afip.gov.ar/ws/services/LoginCms?wsdl' || PATH_WSAA_TEST_WSDL
-Snoopy.service_url = 'https://wswhomo.afip.gov.ar/wsfev1/service.asmx?wsdl' || PATH_WSFE_TEST_WSDL
-```
+- **WSAA** (autenticación): obtiene `token`/`sign` a partir de clave privada + certificado.
+- **WSFE** (facturación electrónica v1): autoriza facturas y notas de crédito, devuelve el CAE.
 
-En caso de trabajar con `Ruby on Rails`, es recomendable crear un archivo con esta conf en `config/initializers/snoopy.rb`.
+Versión actual: `4.3.0`.
 
-### Generar Clave privada
+## Instalación
 
 ```ruby
-Snoopy::AuthenticationAdapter.generate_pkey(2048) # Si no se pasa argumento se generar una de 8192
+# Gemfile
+gem 'snoopy_afip'
 ```
 
-Este metodo retorna el `RAW` de la pkey, la cual debera guardarse en algun archivo o alguna base de datos.
-
-### Generar solicitud de pedido de certificado
-
-#### With ruby
-
-Este metodo aun no ha sido testeado, por lo que agredezco si alguien logra probarlo.
-
-```ruby
-Snoopy::AuthenticationAdapter.generate_certificate_request_with_ruby(pkey_path, subj_o, subj_cn, subj_cuit)
+```bash
+bundle install
+# o
+gem install snoopy_afip
 ```
 
-#### With bash
-
-Mantiene la generación de versiones pasadas de `Snoopy`
+## Setup (desarrollo)
 
 ```bash
-Snoopy::AuthenticationAdapter.generate_certificate_request_with_bash(pkey_path, subj_o, subj_cn, subj_cuit)
+bundle install
+bundle exec rspec   # ver estado de la suite en docs/test/testing.md
 ```
 
-- `pkey_path`: Ruta absoluta de la llave privada.
-- `subj_o`: Nombre de la compañia.
-- `subj_cn`: Hostname del server que generará las solicitudes. En ruby se obtiene con `%x(hostname).chomp`
-- `subj_cuit`: Cuit registrado en la AFIP de la compañia que emita facturas.
-
-Una vez generado este archivo debe hacerse el tramite en el sitio web de la **AFIP** para obtener el certificado que permitirá autorizar facturas al webservice.
-
-### Solicitar autorización para la emisión de facturas
-
-Para poder emitir o autorizar facturas en el web service de la **AFIP** es necesario solicitar autorización.
-
-```ruby
-# pkey_path: Ruta absoluta de la llave privada.
-# cert_path: Ruta absoluta del cetificado obtendio del sitio oficial de la **AFIP**.
-authentication_adapter = Snoopy::AuthenticationAdapter.new(pkey_path, pkey_cert)
-authentication_adapter.authenticate!
-```
+Dependencia de runtime: `savon ~> 2.12.1`. Gestión de Ruby con **chruby**, dependencias con **Bundler**.
 
-`authentication_adapter.authenticate!` deberá retornar un `Hash` con las siguientes keys: `:token`, `:sign` y `:expiration_time`
+## Configuración
 
-La key `:expiration_time` determina hasta cuando se podrá autorizar facturas, el tiempo esta prefijado por **AFIP** y es el de 24 Horas desde el momento de la solicitud del **token sign**, superado este tiempo deberá solicitarse nuevamente un **token sign**.
+La gema se configura en el host (típicamente `config/initializers/snoopy.rb`):
 
 ```ruby
-# Response example
-{ token: "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pgo8c3NvIHZlcnNpb249IjIuMCI+CiAgICA8aWQgdW5pcXVlX2lkPSI5MDIxNDczOTEiIHNyYz0iQ049d3NhYWhvbW8sIE89QUZJUCwgQz1BUiwgU0VSSUFMTlVNQkVSPUNVSVQgMzM2OTM0NTAyMzkiIGdlbl90aW1lPSIxNDk4NDk0NDQ1IiBleHBfdGltZT0iMTQ5ODUzNzcwNSIgZHN0PSJDTj13c2ZlLCBPPUFGSVAsIEM9QVIiLz4KICAgIDxvcGVyYXRpb24gdmFsdWU9ImdyYW50ZWQiIHR5cGU9ImxvZ2luIj4KICAgICAgICA8bG9naW4gdWlkPSJDPWFyLCBPPXNlcXVyZSBzYSwgU0VSSUFMTlVNQkVSPUNVSVQgMjAyNDE2MDgxNjcsIENOPXBjIiBzZXJ2aWNlPSJ3c2ZlIiByZWdtZXRob2Q9IjIyIiBlbnRpdHk9IjMzNjkzNDUwMjM5IiBhdXRobWV0aG9kPSJjbXMiPgogICAgICAgICAgICA8cmVsYXRpb25zPgogICAgICAgICAgICAgICAgPHJlbGF0aW9uIHJlbHR5cGU9IjQiIGtleT0iMjAyNDE2MDgxNjciLz4KICAgICAgICAgICAgPC9yZWxhdGlvbnM+CiAgICAgICAgPC9sb2dpbj4KICAgIDwvb3BlcmF0aW9uPgo8L3Nzbz4KCg==",
-  sign: "iSpp/5qxQntuzOQcqs6GlShFaOKtEagLY17TFDwMTiErquT/fEw5ki9Ff4RYGndc/49UGmUTnVjUqB0mxuJk2IG4t+J4AAyVsY6+xiBGvMXAM/5sAI78NDl7ibMxAcdPi+nBIrdydp5DLy2SB4u/G46kguc6+srBp2fo20f/+wM=",
-  expiration_time: #<DateTime: 2017-06-27T01:28:25-03:00 ((2457932j,16105s,963000000n),-10800s,2299161j)>}}
+Snoopy.default_currency      = :peso
+Snoopy.default_concept       = 'Servicios'
+Snoopy.default_document_type = 'CUIT'           # alguna key de Snoopy::DOCUMENTS
+
+# Homologación (testing)
+Snoopy.auth_url    = 'https://wsaahomo.afip.gov.ar/ws/services/LoginCms?wsdl'
+Snoopy.service_url = 'https://wswhomo.afip.gov.ar/wsfev1/service.asmx?wsdl'
+# Producción
+# Snoopy.auth_url    = 'https://wsaa.afip.gov.ar/ws/services/LoginCms?wsdl'
+# Snoopy.service_url = 'https://servicios1.afip.gov.ar/wsfev1/service.asmx?WSDL'
+
+Snoopy.pkey = '<path-o-PEM-de-la-clave-privada>'   # secreto — nunca commitear
+Snoopy.cert = '<path-o-PEM-del-certificado-AFIP>'  # secreto — nunca commitear
+Snoopy.cuit = '<CUIT-del-emisor>'
 ```
 
-En caso de producirse algun tipo de error este será devuelto a traves de raise exception. El error mas comun puede deberse al que certificado obtenido a treves del pedido de cetificado no sea correcto.
-
-### Autorizar factura
-
-#### Crear `Bill`
-```ruby
-Snoopy::Bill.new(attrs)
-
-```
-Donde `attrs` debe estar conformado de la siguiente manera:
-* `attrs[:cuit]`                    CUIT del emisor de la factura.
-* `attrs[:concept]`                 Concepto de la factura, por defecto `Snoopy.default_concept`.
-* `attrs[:imp_iva]`                 Monto total de impuestos.
-* `attrs[:currency]`                Tipo de moneda a utilizar, por default `Snoopy.default_currency`.
-* `attrs[:alicivas]`                Impuestos asociados a la factura.
-* `attrs[:total_net]`               Monto neto por defecto es 0.
-* `attrs[:sale_point]`              Punto de venta del emisor de la factura.
-* `attrs[:document_type]`           Tipo de documento a utilizar, por default `Snoopy.default_document`. Valores posibles `Snoopy::DOCUMENTS`
-* `attrs[:document_num]`            Numero de documento o cuit, el valor depende de `attrs[:document_type]`.
-* `attrs[:issuer_iva_cond]`         Condición de IVA del emisor de la factura. [`Snoopy::RESPONSABLE_INSCRIPTO` o `Snoopy::RESPONSABLE_MONOTRIBUTO`]
-* `attrs[:receiver_iva_cond]`       valores posibles `Snoopy::BILL_TYPE`
-* `attrs[:service_date_from]`       Inicio de vigencia de la factura.
-* `attrs[:service_date_to]`         Fin de vigencia de la factura.
-* `attrs[:cbte_asoc_num]`           Numero de la factura a la cual se quiere crear una nota de crédito (Solo pasar si se esta creando una nota de crédito).
-* `attrs[:cbte_asoc_to_sale_point]` Punto de venta de la factura a la cual se quiere crear una nota de crédito (Solo pasar si se esta creando una nota de crédito).
-
-El `attrs[:alicivas]` discrimina la información de los items. Es posible que en la factura se discriminen diferentes items con diferentes impuestos. Para ello el `attrs[:alicivas]` es un arreglo de `Hash`. Donde cada uno de ellos tiene la información sobre un determinado impuesto.
+> El inventario completo de opciones (tipos, defaults, secretos, failure-mode) está en [`docs/config/configuracion.md`](docs/config/configuracion.md). Nunca incrustar CUIT, claves ni certificados reales en el código ni en el repo.
 
-```ruby
-{ id:            tax_rate.round_with_precision(2),    # Porcentaje. Ej: "0.105", "0.21", "0.27"
-  amount:        tax_amount.round_with_precision(2),  # Monto total del impuesto del item.
-  taxeable_base: net_amount.round_with_precision(2) } # Monto total del item sin considerar el impuesto.
-```
+## Uso
 
-Por ejemplo si se tiene 5 items, donde 3 de ellos tienen un impuesto del 10.5% y los 2 restantes del 21%. Los primeros 3 deben, se debera de crear dos hashes de la siguientes forma.
+### 1. Autenticar (WSAA)
 
 ```ruby
-attrs[:alicivas] = [ { id: (10.5 / 100 ).to_s 
-                       amount: X,            # De los 3 items de 10.5
-                       taxeable_base: Y },   # De los 3 items de 10.5
-                     { id: (21 / 100 ).to_s 
-                       amount: X,            # De los 2 items de 21
-                       taxeable_base: Y } ]  # De los 2 items de 21
+auth = Snoopy::AuthenticationAdapter.new(pkey: pkey_path, cert: cert_path)
+credentials = auth.authenticate!
+# => { token: "<token>", sign: "<sign>", expiration_time: <DateTime> }  (válido 12h)
 ```
-Donde: 
 
-* `X`: Es la parte del monto que le corresponde al impuesto.
-* `Y`: Es la partes del monto sin impuesto.
+Helpers para generar clave/CSR: `Snoopy::AuthenticationAdapter.generate_pkey`, `.generate_certificate_request_with_ruby`, `.generate_certificate_request_with_bash`. Trámite del certificado: [AFIP — Obtener certificado](https://www.afip.gob.ar/ws/WSAA/WSAA.ObtenerCertificado.pdf).
 
-Los `tax_rates` soportados por AFIP son los siguientes:
+### 2. Crear el comprobante (`Bill`)
 
 ```ruby
-Snoopy::ALIC_IVA
+bill = Snoopy::Bill.new(
+  cuit:                   cuit,
+  sale_point:             sale_point,
+  concept:                'Servicios',
+  document_type:          'CUIT',
+  document_num:           '30710151543',
+  issuer_iva_cond:        Snoopy::RESPONSABLE_INSCRIPTO,
+  receiver_iva_cond:      :factura_a,           # key de Snoopy::BILL_TYPE → cbte_type
+  receiver_iva_condition: :responsable_inscripto,
+  total_net:             1000.0,
+  alicivas: [ { id: 0.21, amount: 210.0, taxeable_base: 1000.0 } ]
+)
+bill.valid?   # corre validaciones → bill.errors
 ```
 
-* Tips:
+`alicivas` discrimina el IVA por ítem (`id` = porcentaje, `amount` = monto del impuesto, `taxeable_base` = neto sin IVA). Tasas soportadas: `Snoopy::ALIC_IVA`. Detalle de términos en [`docs/glossary/glossary.md`](docs/glossary/glossary.md).
 
-El `taxeable_base` se calcula de la siguiente manera:
+### 3. Autorizar (WSFE)
 
 ```ruby
-total_amount / (1 + tax_percentage)
-```
-  
-- Metodos de interes
-  - **valid?**            valida si la `bill` cumple lo minimo indispensable.
-  - **partial_approved?** si fue _Aprobada parcialmente_ por el webserice.
-  - **rejected?**         si fue _Rechazada_ por el webservice.
-  - **approved?**         si fue _Aprobada_ por el webservice.
-  - **errors**            errores presentados durante la validación `valid?`
-
-#### Autorizar el `Bill`
-```ruby
-authorize_adapter = Snoopy::AuthorizeAdapter.new({ bill: bill,        # Obtenido en el paso anterior
-                                                   pkey: pkey,        # PATH de la clave privada generada anteriormente.
-                                                   cert: certificate, # PATH del certificado descargado del sitio web de la AFIP.
-                                                   cuit: cuit,        # CUIT del emisor de la factura, mismo con el que se hizo el tramite.
-                                                   sign: sign,        # SIGN obtenido en la autenticación
-                                                   token: token})     # TOKEN obtenido en la autenticación
-                                                   
-authorize_adapter.set_bill_number!
-
-authorize_adapter.authorize!
+adapter = Snoopy::AuthorizeAdapter.new(
+  bill:  bill,
+  pkey:  pkey, cert: cert, cuit: cuit,
+  token: credentials[:token], sign: credentials[:sign]
+)
+adapter.set_bill_number!   # numera con el último autorizado + 1
+adapter.authorize!         # => true/false; setea bill.cae, bill.result, ...
 ```
 
-- Metodos de interes del `Snoopy::AuthorizeAdapter`
+Lecturas de la respuesta: `adapter.afip_errors`, `adapter.afip_events`, `adapter.afip_observations`, `adapter.errors`, `adapter.response`. Estado del comprobante: `bill.approved?`, `bill.partial_approved?`, `bill.rejected?`.
 
-  - **request** Información enviada al webservice de **AFIP**
-  - **response** Respuesta completa obtenida del webservice de **AFIP**
-  - **afip_errors** Errores parseados de la **response**. Pueden presentarse los motivos por los que no se autorizo la `bill`
-  - **afip_events** Eventos parseados de la **response** . Generalmente la **AFIP** los usa para informar de posibles cambios.
-  - **afip_observations** Observaciones parseados de la **response**. Pueden presentarse los motivos por los que no se autorizo la `bill`
-  - **errors** Errores presentados en el proceso de autorización. Explicado en el apartado siguiente.
+### Manejo de errores
 
-### Manejo de excepciones
+- **Explota** (`raise`): fallo de comunicación con AFIP (`Snoopy::Exception::ServerTimeout`, `ClientError`) → no se autorizó el comprobante.
+- **No explota**: AFIP respondió pero el parseo de la respuesta falló o devolvió errores de negocio → se acumulan en `adapter.errors` / `afip_errors` (parseo en 4 capas independientes para que un cambio de formato de AFIP no tumbe todo).
 
-#### Explota
+Catálogo y política completos en [`docs/errors/errors.md`](docs/errors/errors.md).
 
-Hay errores que producirán que `Snoopy` generé un `raise`, estos son los casos que se produzcan errores previo o durante la comunicación con la **AFIP**. En estos casos se produce un `raise` debido a que no se logro la comunicación con la **AFIP** por lo que se puede asegurar que no se autorizo la `bill`
+## Índice de artefactos (`docs/`)
 
-#### No Explota
-Existe otro caso que se produzca un error posterior a la comunicación con el webservice, en este caso se pudo obtener una respuesta , pero se producierón errores en el parseo de la misma (Por ejemplo **AFIP** cambia el formato de la response), para ellos se puede consultar las exceptiones generadas por los parseadores con `authorize_adapter.errors`. 
+| capa | artefacto | contenido |
+|---|---|---|
+| interfaz | [`docs/interface/interface.md`](docs/interface/interface.md) | API Ruby pública (`Snoopy`, adapters, `Bill`, constantes) |
+| comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | secuencias WSAA / WSFE |
+| glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | términos AFIP (CAE, cbte_type, alicivas, IVA cond) |
+| consumidas | [`docs/consumed/afip.md`](docs/consumed/afip.md) | contrato SOAP consumido (WSAA + WSFE) |
+| errores | [`docs/errors/errors.md`](docs/errors/errors.md) | jerarquía `Snoopy::Exception::*` + política |
+| configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | inventario de opciones runtime |
+| topología | [`docs/topology/topology.md`](docs/topology/topology.md) | dependencias + servicios externos |
+| test | [`docs/test/testing.md`](docs/test/testing.md) | suite, gaps de cobertura |
+| operaciones (api) | n/a | gema sin superficie HTTP/CLI propia |
+| datos | n/a | sin base de datos |
+| eventos · multi-tenancy | n/a | no aplica |
 
-Hay 4 nivel de parser:
-- **Obtención del resultado, cae, fecha de vencimiento del cae y el bill number**: Este es el nivel de parser mas **importante** dado que si este no se pudo realizar, es imposible saber que sucedio durante la autorización. Pero no preocuparse por que esta la response completa en `authorize_adapter.response`
-- **Parseo de errores**: Parsea los errores retornados por la **AFIP**.
-- **Parseo de eventos**: Parsea los eventos retornados por la **AFIP**.
-- **Parseo de observaciones**: Parsea las observaciones retornados por la **AFIP**.
+## Referencias AFIP
 
-Implemente esto de esta manera debido a que sucedio que **AFIP** cambio algo en la estructura de los eventos, y al tener todo en un solo parser explotaba todo y no sabia que habia sucedido con la autorización de la factura.
+- [Especificación Técnica WSAA 1.2.0](http://www.afip.gov.ar/ws/WSAA/Especificacion_Tecnica_WSAA_1.2.0.pdf)
+- [Manual del desarrollador WSFE](http://www.afip.gob.ar/fe/documentos/manual_desarrollador_COMPG_v2_9.pdf)
 
 ## TO DO
-- **Mejor parseo de los errores obtenidos en AFIP**: La idea seria poder identificar cada uno de los errores posibles obtenido, y agregar los errores en la `bill` al atributo que corresponda.
-- **Batch**: Permitir a `Snoopy::AuthorizeAdapter` autorizar un pool de `Snoopy::Bill` en una sola request.
+
+- Mejor parseo de los errores de AFIP (mapear cada código al atributo del `Bill`).
+- Batch: autorizar un pool de `Bill` en una sola request.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+MIT — ver [LICENSE.txt](LICENSE.txt).

data/docs/behavior/behavior.md

@@ -0,0 +1,84 @@
+# Comportamiento — snoopy_afip
+> meta: artefacto · RFC-007 · generado arch-enrich · anclado a 7813cf2 · cobertura: 3 flujos documentados / 0 pendientes localizados
+
+## Cobertura
+
+| flujo | estado |
+|---|---|
+| Autenticación WSAA (`authenticate!`) | documentado |
+| Numeración del comprobante (`set_bill_number!`) | documentado |
+| Autorización WSFE (`authorize!`) | documentado |
+| Consulta de comprobante (`invoice_informed?`) | no documentado (variante de lectura de `fe_comp_consultar`) |
+
+## 1. Resumen
+
+Dos flujos de negocio encadenados: autenticación (WSAA, una vez por 12h) y autorización (WSFE, por comprobante). El segundo asume credenciales ya obtenidas. El diseño separa el parseo de la respuesta WSFE en capas que no se tumban entre sí.
+
+## 2. Flujos
+
+### Autenticación WSAA — `authenticate!`
+
+Contexto: obtiene `token`/`sign` firmando un TRA con cert+pkey.
+
+```mermaid
+sequenceDiagram
+  participant Host
+  participant Auth as AuthenticationAdapter
+  participant Cli as Client
+  participant WSAA as AFIP WSAA
+  Host->>Auth: new(pkey, cert)
+  Host->>Auth: authenticate!
+  Auth->>Auth: build_tra (XML loginTicketRequest)
+  Auth->>Auth: build_cms (PKCS7 sign cert+pkey)
+  Auth->>Cli: call(:login_cms, in0 cms)
+  Cli->>WSAA: SOAP login_cms
+  WSAA-->>Cli: loginTicketResponse
+  Cli-->>Auth: body
+  Auth->>Auth: Nori.parse + extrae credentials
+  Auth-->>Host: {token, sign, expiration_time}
+```
+
+### Autorización WSFE — `set_bill_number!` + `authorize!`
+
+Contexto: numera y autoriza un `Bill` válido; setea CAE y parsea errores/eventos/observaciones en capas independientes.
+
+```mermaid
+sequenceDiagram
+  participant Host
+  participant Adapter as AuthorizeAdapter
+  participant Bill
+  participant Cli as Client
+  participant WSFE as AFIP WSFE
+  Host->>Adapter: new(bill, token, sign, cuit, pkey, cert)
+  Host->>Adapter: set_bill_number!
+  Adapter->>Cli: call(:fe_comp_ultimo_autorizado)
+  Cli->>WSFE: SOAP
+  WSFE-->>Adapter: cbte_nro
+  Adapter->>Bill: number = cbte_nro + 1
+  Host->>Adapter: authorize!
+  Adapter->>Bill: valid?
+  alt bill invalido
+    Adapter-->>Host: false
+  else valido
+    Adapter->>Adapter: build_body_request (FeCAEReq)
+    Adapter->>Cli: call(:fecae_solicitar)
+    Cli->>WSFE: SOAP
+    WSFE-->>Adapter: FECAEDetResponse
+    Adapter->>Bill: cae, due_date_cae, result, number
+    Adapter->>Adapter: parse_errors / parse_events / parse_observations
+    Adapter-->>Host: true
+  end
+```
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `set_bill_number!` se llama antes de `authorize!` | inferred | el README los muestra en ese orden; confirmar si `authorize!` exige número previo |
+| El parseo en capas no propaga (acumula en `errors`/`afip_*`) | declared | diseño "No Explota" del README; confirmado en código |
+
+## 4. Cobertura y fronteras
+
+- `invoice_informed?` (lectura `fe_comp_consultar`) no diagramado — acreta en próximo PR que lo toque.
+- La firma CMS/OpenSSL detallada (PKCS7) no se desglosa; ver `build_cms`.
+- Comportamiento de fallo (timeout/degradación) → `docs/consumed/afip.md §e`.

data/docs/config/configuracion.md

@@ -0,0 +1,94 @@
+# Configuración runtime — snoopy_afip
+> meta: artefacto · RFC-012 · generado arch-structure · enriquecido arch-enrich · anclado a 7813cf2 · cobertura: inventario base 14/14; §f 6/14
+
+## 2.a Hecho verificable
+
+| métrica | valor |
+|---|---|
+| total opciones | 14 |
+| requeridas | 0 (ninguna lanza sin default; faltantes fallan en uso, no en boot) |
+| con default | 3 (`open_timeout`, `read_timeout`, `SNOOPY_SSL_VERSION`) |
+| derivadas | 0 |
+| secretas | 2 (`pkey`, `cert`) |
+| origen ENV | 1 (`SNOOPY_SSL_VERSION`) |
+
+Es **gema con configuración pública**: el grueso se setea por código en el host (`Snoopy.<attr> = …`, típicamente un initializer), no por ENV.
+
+## 2.b Inventario base
+
+| nombre | tipo | requerida | default | origen | consumidor | secret? |
+|---|---|---|---|---|---|---|
+| `Snoopy.cuit` | String | no | `nil` | code-default | `auth_hash`, `AuthorizeAdapter#auth` | no |
+| `Snoopy.sale_point` | String | no | `nil` | code-default | host / `Bill#sale_point` | no |
+| `Snoopy.service_url` | String (URL/WSDL) | no | `nil` | code-default | `AuthorizeAdapter#client_configuration:186` | no |
+| `Snoopy.auth_url` | String (URL/WSDL) | no | `nil` | code-default | `AuthenticationAdapter#client_configuration:115` | no |
+| `Snoopy.pkey` | String (path/PEM) | no | `nil` | code-default | `AuthorizeAdapter#client_configuration:193` | **sí** |
+| `Snoopy.cert` | String (path/PEM) | no | `nil` | code-default | `AuthorizeAdapter#client_configuration:192` | **sí** |
+| `Snoopy.default_document_type` | String | no | `nil` | code-default | `Bill#initialize:30` | no |
+| `Snoopy.default_concept` | String | no | `nil` | code-default | `Bill#initialize:22` | no |
+| `Snoopy.default_currency` | Symbol | no | `nil` | code-default | `Bill#initialize:24` | no |
+| `Snoopy.own_iva_cond` | Symbol | no | `nil` | code-default | host | no |
+| `Snoopy.verbose` | String/bool | no | `nil` | code-default | `snoopy_afip.rb:55` (comentado) | no |
+| `Snoopy.open_timeout` | Integer | no | `30` | code-default (`lib/snoopy_afip.rb:23`) | `Client#call:10`, `AuthorizeAdapter:191` | no |
+| `Snoopy.read_timeout` | Integer | no | `30` | code-default (`lib/snoopy_afip.rb:24`) | `AuthorizeAdapter:190` | no |
+| `SNOOPY_SSL_VERSION` | Symbol | no | `:TLSv1` | env (`constants.rb:24`) | `client_configuration` (ambos adapters) | no |
+
+## 2.c Meta-templates
+
+Ninguna (sin patrones `{SERVICE}_{HOST|PORT}` repetidos).
+
+## 2.d Derivaciones simples
+
+- `Snoopy::SNOOPY_SSL_VERSION = (ENV['SNOOPY_SSL_VERSION'] || 'TLSv1').to_sym` — leído **una vez al cargar** `constants.rb` y **congelado** como constante (cambiar el ENV en runtime no tiene efecto).
+
+## 2.e Scheduling
+
+`n/a` (sin sidekiq/queue/cron).
+
+## 2.i Inyecciones al host
+
+- **Monkey-patches globales** (cargados incondicionalmente en `lib/snoopy_afip.rb:7-9`): `core_ext/float.rb`, `core_ext/hash.rb`, `core_ext/string.rb` reabren `Float`/`Hash`/`String`. `Float#round_with_precision`/`round_up_with_precision` y `String#underscore` se redefinen **siempre**; los de `Hash` solo `unless method_defined?`. Sin Railtie/Engine.
+
+## 2.j Inyección a gemas configuradas
+
+`—` (no aplica: no configura gemas de terceros vía bloque).
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `secret?` de `pkey`/`cert` por contenido (clave privada + certificado), no por nombre | inferred | confirmar manejo (¿path en disco vs PEM inline?) |
+| `verbose` consumido solo en línea comentada (`snoopy_afip.rb:55`) | declared | accessor vivo pero sin efecto actual — posible config muerta |
+
+## f. Enriquecimiento semántico
+
+> cobertura: 6/14 vars enriquecidas; ausencia ≠ "no aplica".
+
+### f.1 credenciales (`cuit`, `pkey`, `cert`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `Snoopy.pkey` | infra | runtime-error al firmar CMS (`CmsBuilder`) si falta/inválida | restart (se relee por request al construir cliente) | mutable-singleton | clave privada que firma el CMS de WSAA y el mTLS de WSFE; **secreto** |
+| `Snoopy.cert` | infra | runtime-error (`CmsBuilder`) / handshake TLS si inválido | restart | mutable-singleton | certificado emitido por AFIP; identifica al emisor; **secreto** |
+| `Snoopy.cuit` | business | request rechazado por AFIP si no coincide con el cert | per-request | mutable-singleton | CUIT del emisor; debe coincidir con el del trámite del certificado |
+
+### f.2 endpoints (`auth_url`, `service_url`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `Snoopy.auth_url` | integration | `ClientError` (WSDL inalcanzable) | restart | mutable-singleton | WSDL de WSAA; **homologación vs producción** se elige acá (riesgo: emitir contra prod por error) |
+| `Snoopy.service_url` | integration | `ClientError` | restart | mutable-singleton | WSDL de WSFE; mismo riesgo homo/prod |
+
+### f.3 tuning de red (`open_timeout`, `read_timeout`, `SNOOPY_SSL_VERSION`)
+
+| var | categoría | failure-mode | side-effect | scope-override | business-reason / definición |
+|---|---|---|---|---|---|
+| `SNOOPY_SSL_VERSION` | tuning | handshake TLS falla si AFIP no soporta la versión | **compile-time-only** (congelado al cargar `constants.rb`) | boot-only | default `:TLSv1` quedó **desactualizado** — AFIP exige TLS ≥1.2; revisar (`inferred`) |
+
+**Ramificadores:** `issuer_iva_cond = :responsable_monotributo` ramifica `alicivas` (monotributo no informa IVA — `authorize_adapter.rb:75`). Es ramificador de payload, no intra-config.
+
+## 4. Cobertura y fronteras
+
+- **Valores reales prohibidos**: solo shape. CUIT/pkey/cert se setean en el host; nunca commitear valores.
+- `ENV["CUIT"]` aparece en `spec/spec_helper.rb` pero es **config de test**, no de la gema → ver `docs/test/`.
+- Enriquecimiento (`categoría`, `failure-mode`, `side-effect`, `business reason`, threading) → arch-enrich (§f).

data/docs/consumed/afip.md

@@ -0,0 +1,61 @@
+# Dependencias consumidas — AFIP (WSAA + WSFE)
+> meta: artefacto · RFC-018 · generado arch-structure · enriquecido arch-enrich · anclado a 7813cf2 · cobertura: subset SOAP invocado; §c 1/1 · §e 1/1
+
+Entrada de **familia** (RFC-018 §4 r2): ambos servicios externos se invocan por el mismo cliente base `Snoopy::Client` (wrapper de `Savon.client`). Difieren en WSDL, headers y operaciones.
+
+## 2.a Identidad
+
+| campo | valor |
+|---|---|
+| proveedor / servicio | AFIP (Argentina) — Facturación Electrónica |
+| sub-tipo | **externo** |
+| transporte | SOAP sobre HTTP/HTTPS |
+| cliente nuestro | `Snoopy::Client` (`lib/snoopy_afip/client.rb`) sobre `savon` |
+| auth | WSAA: firma CMS/PKCS7 (cert + pkey) → `token`/`sign`. WSFE: `Auth = {Token, Sign, Cuit}` + mTLS (`ssl_cert_file`/`ssl_cert_key_file`) |
+| ancla | doc oficial AFIP — ver §5 |
+
+### Miembros de la familia
+
+| miembro | WSDL (config) | cliente | particularidades |
+|---|---|---|---|
+| **WSAA** (autenticación) | `Snoopy.auth_url` | `AuthenticationAdapter#client_configuration` | `ssl_version`, `pretty_print_xml`; sin headers extra |
+| **WSFE** (facturación electrónica v1) | `Snoopy.service_url` | `AuthorizeAdapter#client_configuration` | headers `Accept-Encoding`/`Connection`; namespace `http://ar.gov.afip.dif.FEV1/`; mTLS con `cert`/`pkey`; `read_timeout`/`open_timeout` |
+
+## 2.b Operaciones consumidas (subset usado)
+
+| servicio | operación SOAP | destino (código) | qué mandamos / esperamos |
+|---|---|---|---|
+| WSAA | `:login_cms` | `AuthenticationAdapter#authenticate!` | enviamos CMS firmado (TRA `loginTicketRequest`, service=`wsfe`); esperamos `loginTicketResponse` con `credentials.token`/`.sign` + `header.expirationTime` |
+| WSFE | `:fecae_solicitar` | `AuthorizeAdapter#authorize!` | enviamos `Auth` + `FeCAEReq` (cabecera + detalle: tipo, punto venta, importes, IVA, doc, fechas); esperamos `FECAEDetResponse` con `cae`, `cae_fch_vto`, `resultado`, `cbte_desde` + `errors`/`events`/`observaciones` |
+| WSFE | `:fe_comp_ultimo_autorizado` | `AuthorizeAdapter#set_bill_number!` | enviamos `Auth` + `PtoVta` + `CbteTipo`; esperamos `cbte_nro` (último autorizado) → `+1` |
+| WSFE | `:fe_comp_consultar` | `AuthorizeAdapter#invoice_informed?` | enviamos `Auth` + `FeCompConsReq` (tipo, nro, punto venta); esperamos `result_get` con estado del comprobante |
+
+## 2.c Semántica de retry / idempotencia
+
+- **La gema NO reintenta**: `Client#call` envuelve la llamada en `Timeout` y al fallar levanta `ServerTimeout`/`ClientError` — el retry queda a cargo del host.
+- **`authorize!` (`fecae_solicitar`) NO es idempotente por sí solo**: reenviar el mismo `FeCAEReq` puede generar un comprobante nuevo. La idempotencia se logra usando `set_bill_number!` (lee el último autorizado) o `invoice_informed?` (`fe_comp_consultar`) para verificar antes de reintentar. Reintentar a ciegas tras timeout es **inseguro**: el comprobante pudo haberse autorizado del lado de AFIP. `inferred` — confirmar política con AFIP.
+- **`set_bill_number!` / `invoice_informed?` (lecturas) son idempotentes**: reintento seguro.
+
+## 2.d Errores del proveedor → mapeo nuestro
+
+| condición del proveedor | excepción nuestra (ver `docs/errors/`) |
+|---|---|
+| `Timeout::Error` (corte por `Timeout::timeout(Snoopy.open_timeout)`) | `Snoopy::Exception::ServerTimeout` |
+| cualquier otro fallo de transporte/SOAP (`rescue => e`) | `Snoopy::Exception::ClientError` (con `e.message`) |
+| errores de negocio AFIP (`FeCAEReq` rechazado, etc.) | **no se levantan**: se parsean a `afip_errors`/`afip_events`/`afip_observations` (code→msg) y el flujo sigue |
+| fallo de parseo de la respuesta AFIP | excepciones `Snoopy::Exception::AuthorizeAdapter::*Parser` (ver `docs/errors/`) |
+
+Códigos de error documentados por AFIP para WSAA (`coe.notAuthorized`, `cms.*`, `xml.*`, `wsn.*`, `wsaa.*`) están listados como comentario en `authentication_adapter.rb:17-35` — referencia, no se mapean uno a uno.
+
+## 2.e Degradación
+
+- Si AFIP **no responde** (timeout/red): `Snoopy::Exception::ServerTimeout`/`ClientError` propaga al host. No hay fallback ni cola en la gema — la emisión del comprobante **no procede**. El host decide reintento/cola.
+- Si AFIP responde pero **rechaza** (errores de negocio): no hay excepción; `afip_errors` se puebla y `bill.result` queda `R`/`P`. La degradación es "comprobante no aprobado", consultable sin reintentar la red.
+- **SLA de AFIP**: no garantizado; ventanas de mantenimiento frecuentes (códigos `wsn.unavailable`/`wsaa.unavailable`). Diseñar el host para tolerar caídas. `inferred`.
+
+## 5. Cobertura y fronteras
+
+- Subset invocado, **no** la API completa de WSFE (la gema usa 4 operaciones de las ~decenas del WS).
+- Timeout/SSL: `open_timeout`/`read_timeout` (default 30) y `SNOOPY_SSL_VERSION` parametrizados en el repo → ver `docs/config/`.
+- Doc oficial: [Espec. Técnica WSAA 1.2.0](http://www.afip.gov.ar/ws/WSAA/Especificacion_Tecnica_WSAA_1.2.0.pdf) · [Manual desarrollador WSFE](http://www.afip.gob.ar/fe/documentos/manual_desarrollador_COMPG_v2_9.pdf).
+- WSDLs: WSAA homo `wsaahomo.afip.gov.ar` / prod `wsaa.afip.gov.ar`; WSFE homo `wswhomo.afip.gov.ar` / prod `servicios1.afip.gov.ar`.

data/docs/errors/errors.md

@@ -0,0 +1,69 @@
+# Errores / fallos públicos — snoopy_afip
+> meta: artefacto · RFC-020 · generado arch-structure · enriquecido arch-enrich · anclado a 7813cf2 · cobertura: jerarquía `Snoopy::Exception::*`; §c 13/13
+
+## 1. Resumen
+
+Gema sin superficie HTTP → no hay códigos de estado (§b n/a). El contrato del unhappy path es la jerarquía de excepciones `Snoopy::Exception::*` que la gema **levanta** hacia el host, más el patrón "no explota": los errores de negocio de AFIP no se levantan, se acumulan en hashes (`afip_errors`/`afip_events`/`afip_observations`) y los fallos de parseo se acumulan en `errors`.
+
+## 2.a Inventario de excepciones públicas
+
+| excepción | jerarquía base | qué la levanta |
+|---|---|---|
+| `Snoopy::Exception::Exception` | `< ::StandardError` | base de la gema; `initialize(msg, backtrace)` |
+| `Snoopy::Exception::ClientError` | `< Exception` | `Client#call` ante cualquier fallo no-timeout de la llamada SOAP |
+| `Snoopy::Exception::ServerTimeout` | `< Timeout::Error` | `Client#call` cuando expira `Timeout::timeout(Snoopy.open_timeout)` — **no** hereda de la base de la gema |
+| `Snoopy::Exception::AuthenticationAdapter::CmsBuilder` | `< Exception` | `AuthenticationAdapter#build_cms` si falla la firma PKCS7 / lectura de pkey-cert |
+| `Snoopy::Exception::AuthorizeAdapter::SetBillNumberParser` | `< Exception` | `#set_bill_number!` ante fallo de parseo de `fe_comp_ultimo_autorizado` |
+| `Snoopy::Exception::AuthorizeAdapter::BuildBodyRequest` | `< Exception` | `#build_body_request` si falla armar el `FeCAEReq` |
+| `Snoopy::Exception::AuthorizeAdapter::FecaeSolicitarResultParser` | `< Exception` | `#parse_fecae_solicitar_response` (capa resultado/CAE) |
+| `Snoopy::Exception::AuthorizeAdapter::FecaeResponseParser` | `< Exception` | `#parse_fecae_solicitar_response` (capa response) — se **acumula** en `errors`, no se raise-a |
+| `Snoopy::Exception::AuthorizeAdapter::ObservationParser` | `< Exception` | `#parse_observations` — se acumula en `errors` |
+| `Snoopy::Exception::AuthorizeAdapter::ErrorParser` | `< Exception` | `#parse_errors` — se acumula en `errors` |
+| `Snoopy::Exception::AuthorizeAdapter::EventsParser` | `< Exception` | `#parse_events` — se acumula en `errors` |
+| `Snoopy::Exception::Bill::MissingAttributes` | `< Exception` | validación de presencia (`Bill#valid?`) — mensaje, se acumula en `bill.errors` |
+| `Snoopy::Exception::Bill::InvalidValueAttribute` | `< Exception` | validación de valor estándar (currency/iva/doc/concept) — se acumula en `bill.errors` |
+
+## 2.b Códigos HTTP por superficie
+
+`n/a` — la gema no expone superficie HTTP (no hay controllers/routes). El transporte HTTP lo gestiona `savon` internamente.
+
+## 2.c Política por error
+
+| excepción | retriable? | backoff | idempotencia req. | acción |
+|---|---|---|---|---|
+| `ServerTimeout` | condicional | sí (host) | **sí** — verificar con `invoice_informed?` antes de reintentar `authorize!` | propagate + report |
+| `ClientError` | condicional | sí (host) | sí (idem) | propagate + report |
+| `AuthenticationAdapter::CmsBuilder` | no | — | — | propagate (config/cert inválido — no reintentable) |
+| `AuthorizeAdapter::BuildBodyRequest` | no | — | — | propagate (datos del bill mal formados) |
+| `AuthorizeAdapter::SetBillNumberParser` | no | — | — | propagate + report (AFIP cambió formato) |
+| `AuthorizeAdapter::FecaeSolicitarResultParser` | no | — | — | propagate + report (capa crítica: revisar `response` cruda) |
+| `…FecaeResponseParser` / `…ObservationParser` / `…ErrorParser` / `…EventsParser` | no | — | — | log/acumular en `errors` (no fatal: el CAE ya pudo parsearse) |
+| `Bill::MissingAttributes` / `Bill::InvalidValueAttribute` | no | — | — | log en `bill.errors` (validación local, corregir input) |
+
+Notas:
+- `report` = candidato a Sentry/exis_ray (observabilidad = otra capa).
+- Tras `ServerTimeout`/`ClientError` en `authorize!`, **nunca** reintentar a ciegas: el comprobante pudo haberse emitido en AFIP (ver `docs/consumed/afip.md §c`).
+- `inferred`: la criticidad/acción la deduje del diseño "No Explota" + flujo; el humano confirma la política operacional real.
+
+## 2.d Shape del payload de error
+
+No hay payload serializado (no es servicio). Las formas que cruzan la frontera:
+
+- **Excepción Ruby**: `message` + `backtrace` (la base guarda `backtrace` en `attr_accessor`).
+- **`bill.errors`**: `Hash` `{ attr_symbol => [String mensajes] }` (validación).
+- **`authorize_adapter.errors`**: colección de excepciones de parseo no-fatales.
+- **`afip_errors` / `afip_events` / `afip_observations`**: `Hash` `{ code => msg }` con lo devuelto por AFIP.
+
+## 3. Inferencias
+
+| ítem | confidence | a verificar |
+|---|---|---|
+| `ServerTimeout < Timeout::Error` (no `< Snoopy::Exception::Exception`) | declared | un `rescue Snoopy::Exception::Exception` **no** atrapa timeouts — confirmar si es intencional |
+| `authorize_adapter.rb:182` referencia `Snoopy::Exception::FecompConsultResponseParser` pero la clase definida es `…::AuthorizeAdapter::FecompConsultResponseParser` | declared | el `raise` levantaría `NameError` en ese path — posible bug latente (código existente, no tocar sin decisión) |
+| `errors <<` en varios `parse_*` rescue trata `errors` como Array, pero se inicializa `{}` (Hash) | declared | `Hash#<<` no existe → `NoMethodError` en ese rescue — posible bug latente |
+
+## 4. Cobertura y fronteras
+
+- Solo errores **públicos** (cruzan la frontera de la gema). Rescates internos no listados.
+- Errores del proveedor AFIP que consumimos → su mapeo en `docs/consumed/afip.md §d`.
+- Política de retry/acción → `docs/errors` §c, lo completa arch-enrich.