cobro_digital 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e41a79daf849e19e3837748c1c93ba14738177b947ddcccf4570e3db21ebd95b
-  data.tar.gz: c01ad7889786e3b955cfe8d06b48eda64221b8d925160fcaab0717d2755c2b3a
+  metadata.gz: 1afc2d401df0ab220743405f8a5df6da4592b2b434f045b788870a3c04898e98
+  data.tar.gz: 3fc154767f9baea467ec0f12bf3243cb77222a1f4bac73cde098b2a57dd50e11
 SHA512:
-  metadata.gz: 8ec8262e47ab17b8484a5bf59afa875d90f48e7f6cf5e19c86fc8823501d145723183b229bceb87fc409bd571ae14fb38a5ab120a533c55094a33fc91d6829fe
-  data.tar.gz: edcefcb8462b7f281e6907ce78d81aa834acfa5295f79cd8bf31fefcccdbabd1c284880fc763e14c20646e09164ac31d21812b4c26598e1fe157aa55946229e9
+  metadata.gz: aca153572c2ca467b8cb3696edcaeccb989f98a5d888065bd41cf8308e9c04fe06fc8c7b947c1df843a3286e64439370557b77d990b3b1cba4839875cb0bc31c
+  data.tar.gz: b547264116c81700608a1760b556c83e7ab9001d4c8d21f7fb3db362bf4c90f84d197c4ff9df813a7638b8a8b56c2b25402d7199e0555a6ca246bc7e525936de

data/.github/workflows/main.yml

@@ -0,0 +1,35 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          # savon ~> 2.12.1 corre sobre httpi 2.x, que usa URI.escape (removido
+          # en Ruby 3.0). El único consumer (wispro_cloud) corre Ruby 2.7.6.
+          # Subir a 3.x al actualizar el stack de savon.
+          - '2.7'
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run specs
+        run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Publish to RubyGems
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        persist-credentials: false
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        # Igual que el target de CI: savon ~> 2.12.1 (httpi 2.x) no corre en
+        # Ruby 3.0+, y `gem build` evalúa el gemspec con el Ruby del runner.
+        ruby-version: '2.7'
+
+    - name: Build and publish to RubyGems
+      # gem push toma la credencial de GEM_HOST_API_KEY (nativo): no se escribe
+      # el secreto a disco ni queda expuesto en el process list.
+      run: |
+        gem build cobro_digital.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md — cobro_digital
+
+Fuente de verdad para estructura, convenciones, entorno y arquitectura de esta gema. Leer antes de hacer cambios.
+
+## 1. Identidad
+
+`cobro_digital` es una gema Ruby: adaptador para comunicarse con el Web Service de [CobroDigital](http://cobrodigital.com) (versión 3.0 del WS), una pasarela de pago.
+
+- `summary`: "Adaptador CobroDigital" (`cobro_digital.gemspec`).
+- `description`: "Adaptador para el Web Service de CobroDigital".
+- La gema modela las operaciones del webservice (crear/editar pagadores, generar/inhabilitar boletas, consultar transacciones y actividad de micrositios) y resuelve el transporte hacia el endpoint de CobroDigital.
+- Requiere credenciales del comercio (`id_comercio` y `sid`) entregadas por CobroDigital para autenticarse contra el webservice (ver `README.md`).
+- El endpoint default es `https://cobro.digital:14365/ws3/`, configurable vía la variable de entorno `ENDPOINT_COBRODIGITAL` (`lib/cobro_digital.rb`).
+
+## 2. Convenciones del framework
+
+Este repo consume skills del framework de agentes, declaradas en el manifiesto raíz `skills.yml`.
+
+- Las skills vendoreadas en `.agents/skills/` traen conocimiento de las dependencias del repo.
+- Leer la skill de una dependencia antes de responder o decidir sobre ella.
+
+## 3. Entorno
+
+- Ruby: `required_ruby_version = '>= 2.7', '< 3.0'` (el stack `savon ~> 2.12.1` / httpi 2.x no corre en Ruby 3.0+). El único consumer (wispro_cloud) usa Ruby 2.7.6. La CI corre sobre Ruby 2.7.
+- Gestor de versiones: chruby (no rvm/rbenv).
+- Dependencias: gestionadas con Bundler. El `Gemfile` toma las dependencias del gemspec (`gemspec`). No hay `Gemfile.lock` versionado (la CI resuelve con `bundler-cache`).
+- Dependencia de runtime: `savon ~> 2.12.1` (cliente SOAP). **No depende de ActiveSupport** (solo stdlib: `net/http`, `uri`, `digest`, `json`).
+- Dependencias de desarrollo: `rake >= 13.2.1`, `rspec ~> 3.13` (`cobro_digital.gemspec`).
+
+## 4. YARD
+
+Documentación incremental con la skill `yard`.
+
+- Verificar cobertura de documentación: `bundle exec yard stats --list-undoc`.
+
+## 5. Testing
+
+- Framework: RSpec (`.rspec`, carpeta `spec/`, `Rakefile` registra `RSpec::Core::RakeTask`).
+- Correr la suite: `bundle exec rspec` (o `bundle exec rake`, cuya tarea default es `:spec`).
+- Código nuevo debe venir acompañado de tests.
+
+## 6. Releases
+
+- Publicar con la skill `/gem-release`.
+- CI/release: GitHub Actions — `.github/workflows/main.yml` (rspec en PRs/push a master) y `.github/workflows/release.yml` (build + push a RubyGems al pushear un tag `v*`, vía `GEM_HOST_API_KEY`).
+
+## 7. Arquitectura
+
+El código vive en `lib/` bajo el módulo `CobroDigital` (`lib/cobro_digital.rb` es el require raíz).
+
+- `CobroDigital::Client` (`lib/cobro_digital.rb`): transporte hacia el webservice. Mantiene credenciales (`id_comercio`, `sid`) y elige el cliente a usar: `soap` (vía Savon, default) o `https` (vía `Net::HTTP`, métodos `Post`/`Get`). Arma el bloque de identificación del comercio (incluye un `handshake` MD5) y ejecuta la llamada.
+- `CobroDigital::Operador` (`lib/cobro_digital/operador.rb`): clase base de las operaciones. Define `request`, `call(id_comercio, sid, opt)` —que instancia un `Client` y ejecuta— y `parse_response`, que decodifica el JSON de salida del webservice en `{ resultado:, log:, datos: }`.
+- `CobroDigital::Pagador` (`lib/cobro_digital/pagador.rb`): operaciones sobre pagadores (clientes a facturar): `crear`, `editar`, `verificar`, `codigo_electronico`, `estructura_de_datos`.
+- `CobroDigital::Boleta` (`lib/cobro_digital/boleta.rb`): operaciones sobre boletas: `generar`, `inhabilitar`, `obtener_codigo_de_barras`.
+- `CobroDigital::Transaccion` (`lib/cobro_digital/transaccion.rb`): consulta de transacciones (`consultar`) con filtros por tipo (ingresos, egresos, tarjeta de crédito, débito automático), nombre, concepto, nro de boleta e identificador.
+- `CobroDigital::Micrositio` (`lib/cobro_digital/micrositio.rb`): consulta de actividad de micrositio (`consultar_actividad`).
+- `CobroDigital::Meta` (`lib/cobro_digital/meta.rb`): agrupa varias operaciones en una sola llamada al webservice `meta` (batch), y expone helpers (`transaction`, `render`, `meta`).
+- `CobroDigital::VERSION` (`lib/cobro_digital/version.rb`): versión actual de la gema.
+
+Cada operación es una subclase de `Operador` que se construye con métodos de clase (constructores) y luego se ejecuta con `#call`.
+
+## 8. Mapa de conocimiento (cómo leer la doc de este repo)
+
+- **Tu conocimiento = la UNIÓN de este repo + sus asociados.** No termina en el `docs/<capa>/` local: incluye la doc de los servicios/gemas de `skills.yml`. Un flujo o pregunta que cruza repos (e2e) **no vive como doc estática** en ningún repo — se **compone on-demand recorriendo el grafo** (RFC-021): seguí las anclas (`docs/consumed/`, `**Canónico:**`) hasta los repos asociados y **unificá**.
+- **Entrá por** [`skill/SKILL.md`](skill/SKILL.md) — índice de agente; resume el contrato y linkea el detalle.
+- **Navegar una ancla cross-repo:** tomá la **key de servicio en `skills.yml`** (`services.<dep>.repo`) → ese repo es un **checkout hermano local** o alcanzable por **GitHub MCP**. No asumas que el hermano es inalcanzable. La dependencia externa de este repo (el WS de CobroDigital) es de proveedor, no del fleet: su contrato vive en `docs/consumed/` + el manual de CobroDigital.
+
+### Cobertura de capas
+
+| capa | doc | estado |
+|---|---|---|
+| interfaz (RFC-004) | [`docs/interface/interface.md`](docs/interface/interface.md) | **presente** |
+| consumidas (RFC-018) | [`docs/consumed/cobrodigital.md`](docs/consumed/cobrodigital.md) | **presente** (estructural + §c/§e enriquecidos) |
+| configuración (RFC-012) | [`docs/config/configuracion.md`](docs/config/configuracion.md) | **presente** (inventario base + §f) |
+| topología (RFC-006) | [`docs/topology/topology.md`](docs/topology/topology.md) | **presente** |
+| test (RFC-013) | [`docs/test/testing.md`](docs/test/testing.md) | **presente** (estructural + §e-§h) |
+| comportamiento (RFC-007) | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | **presente** (operación simple · batch meta) |
+| glosario (RFC-009) | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | **presente** (parcial, acreta por PR) |
+| datos (RFC-002) | — | **n/a** — gema sin DB |
+| api / operaciones (RFC-003) | — | **n/a** — consumer-only, sin superficie HTTP/CLI/eventos propia |
+| errores (RFC-020) | — | **n/a** — no define excepciones propias; propaga `Savon::*`/`JSON` (ver `consumed §d`) |
+| eventos (RFC-005) | — | **n/a** — no produce eventos |
+| seguridad (RFC-017) | — | **n/a** — sin Pundit/Current; auth es la credencial de comercio (ver `consumed §a`) |
+| multi-tenancy (RFC-023) | — | **n/a** — el tenant es el `id_comercio` por llamada, no hay scoping server-side |
+| data-lifecycle (RFC-026) | — | **n/a** — sin persistencia propia |
+| release (RFC-014) | [`.github/workflows/release.yml`](.github/workflows/release.yml) | **presente** — publicación tag-driven a RubyGems vía `/gem-release` |

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [1.9.0] — 2026-06-29
+
+### Correcciones
+- Reparar la rama HTTPS GET del cliente: variable `data` indefinida y colisión de la constante `CobroDigital::URI` con el módulo `::URI` de la stdlib (#9) — @gedera
+- Agregar `require` explícitos de `net/http`, `uri`, `digest` y `json` (antes dependían de carga transitiva) (#10) — @gedera
+- Enmascarar el `sid` y la PII del pagador en el log SOAP (`filters: [:parametros_de_entrada]`); `log_level` configurable vía `COBRODIGITAL_LOG_LEVEL` con default seguro `:error` (#12) — @gedera
+- Validar `client_to_use` contra `CLIENTS` en `Client#initialize` → `ArgumentError` ante valor inválido (#13) — @gedera
+
+### Mejoras internas
+- Eliminar la dependencia de ActiveSupport: `present?` → `to_s.empty?` y `constantize` → `Net::HTTP::Post`/`Net::HTTP::Get` directos. La gema corre standalone sin Rails (#11) — @gedera
+
+### Tests
+- Reemplazar el spec placeholder (que fallaba a propósito) por tests reales de los constructores de operaciones y de `Operador#parse_response` (#14) — @gedera
+
+### Otros
+- CI/CD: GitHub Actions — `main.yml` (rspec sobre Ruby 2.7 en PRs y push a master) y `release.yml` (build + push a RubyGems tag-driven, vía `GEM_HOST_API_KEY`) — @gedera
+- Eliminar `.travis.yml` legacy (Ruby 1.8.7) — @gedera
+- gemspec: declarar `rspec ~> 3.13`, quitar el pin de `bundler`, `required_ruby_version = ['>= 2.7', '< 3.0']`, `documentation_uri` — @gedera
+- Documentación: refrescar artefactos arch-* (`docs/`, `README.md`, `skill/SKILL.md`) al estado post-fix — @gedera

data/CLAUDE.md

@@ -0,0 +1,15 @@
+# Claude Code Notes
+
+## Fuente de verdad del repositorio
+
+Las reglas, convenciones, estructura y contexto del proyecto viven en `AGENTS.md`.
+
+- Leer `AGENTS.md` antes de hacer cambios.
+- Tratar `AGENTS.md` como fuente de verdad para identidad, estructura, documentación, convenciones del framework, entorno, y arquitectura.
+
+## Propósito de este archivo
+
+`CLAUDE.md` queda reservado para instrucciones o notas específicas de Claude Code.
+
+- No duplicar aquí reglas generales del repositorio.
+- Si una regla aplica a cualquier agente, moverla a `AGENTS.md`.

data/README.md

@@ -1,245 +1,163 @@
-# CobroDigital
+# cobro_digital
 
-Adaptador para comunicarse con el servicio WS de [CobroDigital](http://cobrodigital.com) (Version 3.0).
+Adaptador Ruby para el Web Service v3 de [CobroDigital](http://cobrodigital.com), una pasarela de pago. La gema modela las operaciones del WS (crear/editar pagadores, generar/inhabilitar boletas, consultar transacciones y actividad de micrositios) y resuelve el transporte hacia el endpoint, vía SOAP (default) o HTTPS.
 
-Para poder hacer uso de la gema. Requiere previamente comunicarse con [CobroDigital](http://cobrodigital.com) para dar de alta el comercio que hará uso del servicio (Es posible solicitar datos de prueba). Ellos harán entrega de:
-
-* **id del comercio** (requerido para cualquier comunicación con el webservice, es la manera de identificarse con el webservice)
-* **sid del comercio** (requerido para cualquier comunicación con el webservice, es la manera de identificarse con el webservice)
-* **Estructura de pagador** (Esta estructura debe ser informada por cada comercio. esta estructura es del cliente a facturar)
-* **Plantilla**, modelo de boleta para los clientes.
-* **Manual de implementación**.
+Requiere dar de alta el comercio con CobroDigital, que entrega: **id del comercio**, **sid del comercio**, estructura de pagador, plantilla de boleta y manual de implementación. Es posible solicitar datos de prueba.
 
 ## Instalación
 
-Añadir esta linea en el Gemfile:
+En el `Gemfile`:
 
 ```ruby
 gem 'cobro_digital'
 ```
 
-Luego ejecuta:
-
-    $ bundle
-
-O instala la gema a mano:
-
-    $ gem install cobro_digital
-
-## Uso
-
-### Pagadores
-
-Los Pagadores son los clientes a los que se les facturará, las acciones posibles son las de `crear un pagador`, `editar un pagador`, `verificar un pagador`, `obtener codigo electronico`.
-
-#### Crear Pagador
-
-Consiste en crear un pagador en el webservice de CobroDigital, para ello es necesario:
+Luego `bundle`, o instalar a mano con `gem install cobro_digital`.
 
-* Comunicarse con CobroDigital para definir la estructura de pagador que se quiera notificar.
-* Es importante determinar un identificador único por pagador.
-* El webservice de CobroDigital solo verifica que la estructura sea correcta, pero no realiza ninguna tipo de validación, por lo tanto es importante llevar el control de si un pagador ya fue dado de alta o no. Ya que es posible dar de alta eternamente el mismo pagador.
+> **Ruby:** requiere `>= 2.7, < 3.0` (el stack `savon ~> 2.12.1` no corre en Ruby 3.0+). Desde v1.9.0 la gema usa solo stdlib — **no depende de ActiveSupport**. Los ejemplos con `Date#+`/`.days` son ilustrativos del host. Ver [`docs/topology/topology.md`](docs/topology/topology.md).
 
-Para la creación de un pagador simplemente es necesario comunicar:
-* Estructura de un pagador.
+## Configuración
 
-```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-estructura_pagador = { 'Apellido y nombres' => "Santos Torrealba", 'Id' => 1234, 'Documento' => 33123456, 'Direccion del cliente' => "Falsa 1234", 'Telefono' => "222314", 'E-mail' => "santos.torrealba@who.com" } # Estructura brindada por cobrodigital para realizar pruebas
-pagador = CobroDigital.Pagador.crear(estructura_pagador)
-pagador.call(comercio_id, comercio_sid)
-pagador.response # Obtengo el resultado.
-```
+| variable | default | propósito |
+|---|---|---|
+| `ENDPOINT_COBRODIGITAL` | `https://cobro.digital:14365` | endpoint base del WS (override sandbox/prod) |
+| `COBRODIGITAL_LOG_LEVEL` | `error` | nivel de log del cliente SOAP. **No usar `debug` en producción**: el XML formateado expone el `sid` + PII del pagador |
 
-#### Editar un Pagador
+Detalle: [`docs/config/configuracion.md`](docs/config/configuracion.md).
 
-Consiste en editar algún dato dentro de la estructura de pagador de uno especifico.
+## Índice de artefactos
 
-Para la edición de un pagador simplemente es necesario comunicar:
-* Nombre del identificador.
-* Valor del identificador.
-* Nueva configuración de la estructura pagador.
+| capa | doc | contenido |
+|---|---|---|
+| interfaz | [`docs/interface/interface.md`](docs/interface/interface.md) | API Ruby pública (`CobroDigital::*`) |
+| consumidas | [`docs/consumed/cobrodigital.md`](docs/consumed/cobrodigital.md) | el WS de CobroDigital: operaciones, payloads, mapeo de error |
+| configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | inventario de configuración runtime |
+| topología | [`docs/topology/topology.md`](docs/topology/topology.md) | dependencias y modos de transporte |
+| test | [`docs/test/testing.md`](docs/test/testing.md) | suite RSpec |
+| comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | flujos: operación simple · batch meta |
+| glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | términos del dominio (pagador, boleta, transacción…) |
+| datos · api · errores · eventos · seguridad · multi-tenancy · data-lifecycle | n/a | ver Mapa de conocimiento en [`AGENTS.md`](AGENTS.md) |
+| release | [`.github/workflows/release.yml`](.github/workflows/release.yml) | publicación a RubyGems tag-driven (`v*`) vía `/gem-release` |
 
-```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-estructura_pagador = { 'Apellido y nombres' => "Probando Probando", 'Id' => 1234, 'Documento' => 33123456, 'Direccion del cliente' => "Falsa 1234", 'Telefono' => "222314", 'E-mail' => "santos.torrealba@who.com" } # Estructura brindada por cobrodigital para realizar pruebas
-pagador = CobroDigital.Pagador.editar('id', 1234, estructura_pagador)
-pagador.call(comercio_id, comercio_sid)
-pagador.response # Obtengo el resultado.
-```
-
-#### Verificar Pagador
+## Uso
 
-Permite verificar la existencia o no de un pagador en el webservice.
+Toda operación es una subclase de `CobroDigital::Operador`: se construye con un método de clase y se ejecuta con `#call(comercio_id, comercio_sid)`. La respuesta cruda queda en `#response`; `#parse_response` la decodifica a `{ resultado:, log:, datos: }`.
 
-Para la verificación de un pagador simplemente es necesario comunicar:
-* Nombre del identificador.
-* Valor del identificador.
+> En los ejemplos, `comercio_id` y `comercio_sid` son las credenciales entregadas por CobroDigital. **No las hardcodees** — leelas de configuración/entorno (`ENV`, credentials de Rails, etc.).
 
 ```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-pagador = CobroDigital.Pagador.verificar('id', 1234)
-pagador.call(comercio_id, comercio_sid)
-pagador.response # Obtengo el resultado.
+comercio_id  = ENV.fetch('COBRODIGITAL_ID')
+comercio_sid = ENV.fetch('COBRODIGITAL_SID') # secreto
 ```
 
-#### Codigo Electronico
-
-Para obtener el código electrónico con el cual le posibilitara a las personas realizar pagos por medio de pagosmiscuentas y linkpagos. Cabe que aclarar que este codigo solo sera posible obtener una vez generada la primer boleta.
-
-Para la verificación de un pagador simplemente es necesario comunicar:
-* Nombre del identificador.
-* Valor del identificador.
+### Pagadores
 
-Retorno el numero de código electrónico.
+Los pagadores son los clientes a facturar.
 
 ```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-pagador = CobroDigital.Pagador.codigo_electronico('id', 1234)
+# Crear
+estructura = { 'Apellido y nombres' => 'Santos Torrealba', 'Id' => 1234, 'Documento' => 33123456 }
+pagador = CobroDigital::Pagador.crear(estructura)
 pagador.call(comercio_id, comercio_sid)
-pagador.response # Obtengo el resultado.
-```
-
-### Boleta
+pagador.response
 
-Las boletas es la manera de informar la factura a CobroDigital para poder realizar el cobro por algunos de los medios proporcionados por ellos, las acciones posibles son las de `generar boleta`, `inhabilitar boleta`, `obtener codigo de barras`.
+# Editar
+CobroDigital::Pagador.editar('id', 1234, estructura).call(comercio_id, comercio_sid)
 
-#### Generar Boleta
+# Verificar existencia
+CobroDigital::Pagador.verificar('id', 1234).call(comercio_id, comercio_sid)
 
-Es la manera de informar una factura a cobrar.
+# Código electrónico (solo tras generar la primera boleta)
+CobroDigital::Pagador.codigo_electronico('id', 1234).call(comercio_id, comercio_sid)
 
-Para la generación de una boleta es necesario comunicar:
-* nombre del identificador.
-* el valor del identificador.
-* Array de vencimientos como máximo 4. Siempre la primera fecha deberá ser la fecha de emisión. ejemplo: [Date.today, Date.today+10.days, Date.today+20.days]
-* Array de importes como máximo 4. Siempre el primer monto es el valor de la factura, los siguientes son con los recargos. [100, 110, 120]
-* concepto, una simple leyenda.
-* plantilla, es la plantilla de estilo de la boleta (Cada comercio debe proporcionar esta plantilla, comunicarse con CobroDigital para mas detalle)
-
-Retorna un numero de boleta.
-
-```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-nombre_identificador = 'id'
-valor_identificador = 1234
-vencimientos = [Date.today, Date.today+10.days, Date.today+20.days]
-importes = [100,110,120]
-concepto = "Factura A 10"
-plantilla = 'init_273' #Proporcionado por CobroDigital para realizar pruebas.
-boleta = CobroDigital.Boleta.generar(nombre_identificador, valor_identificador, vencimientos, importes, concepto, plantilla)
-boleta.call(comercio_id, comercio_sid)
-boleta.response # Obtengo el resultado.
+# Estructura de pagadores del comercio
+CobroDigital::Pagador.estructura_de_datos.call(comercio_id, comercio_sid)
 ```
 
-#### Inhabilitar Boleta
-
-Dar de baja una boleta ya generada en el webservice.
+> El WS no controla duplicados: es posible dar de alta el mismo pagador repetidas veces. El control de unicidad es responsabilidad del consumidor.
 
-Para la inhabilitación de una boleta es necesario comunicar:
-* numero de boleta (obtenida en la generación)
+### Boletas
 
 ```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-numero_boleta = 123
-boleta = CobroDigital.Boleta.inhabilitar(numero_boleta)
+# Generar — fechas (máx 4, la 1ª es la de emisión) e importes (máx 4, el 1º es el valor; el resto, recargos)
+vencimientos = [Date.today, Date.today + 10, Date.today + 20]
+importes     = [100, 110, 120]
+boleta = CobroDigital::Boleta.generar('id', 1234, vencimientos, importes, 'Factura A 10', 'init_273')
 boleta.call(comercio_id, comercio_sid)
-boleta.response # Obtengo el resultado.
-```
-
-#### Obtener codigo de barras
-
-Obtener el string de los códigos de barras. Serán tantos como vencimientos e importes informados. En caso de querer renderizarlo a imagen deberá de hacer uso del código 128b, para ello se puede hacer uso de la gema [barby](http://toreto.re/barby/).
+boleta.response # => numero de boleta
 
-Para la obtención de los códigos de barra es necesario comunicar:
-* numero de boleta (obtenida en la generación)
+# Inhabilitar
+CobroDigital::Boleta.inhabilitar(123).call(comercio_id, comercio_sid)
 
-```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-numero_boleta = 123
-boleta = CobroDigital.Boleta.obtener_codigo_de_barras(numero_boleta)
-boleta.call(comercio_id, comercio_sid)
-boleta.response # Obtengo el resultado.
+# Código de barras (uno por vencimiento/importe; render a imagen con la gema barby, código 128b)
+CobroDigital::Boleta.obtener_codigo_de_barras(123).call(comercio_id, comercio_sid)
 ```
 
 ### Transacciones
 
-Es posible realizar todas los movimientos ya sea de ingreso y egreso en la cuenta proporcionada a cobrodigital.
-
-Para poder realizar las consulta de las transacciones es necesario comunicar:
-* fecha_desde: Comienzo desde donde se quiere obtener las transacciones.
-* fecha_hasta: Fin desde donde se quiere obtener las transacciones.
-* filtros: Los filtros nos permiten obtener transacciones mas especificas:
+Movimientos de ingreso/egreso de la cuenta. Filtros disponibles (constantes de `CobroDigital::Transaccion`):
 
-Para consultar los tipos de filtros, se puede consultar las siguientes constantes:
+| constante | valor |
+|---|---|
+| `FILTRO_TIPO` | `tipo` |
+| `FILTRO_NOMBRE` | `nombre` |
+| `FILTRO_CONCEPTO` | `concepto` |
+| `FILTRO_NRO_BOLETA` | `nro_boleta` |
+| `FILTRO_IDENTIFICADOR` | `identificador` |
+| `FILTRO_TIPO_EGRESO` | `egresos` (retiros del dinero depositado) |
+| `FILTRO_TIPO_INGRESO` | `ingresos` (cobranzas) |
+| `FILTRO_TIPO_TARJETA_CREDITO` | `tarjeta_credito` |
+| `FILTRO_TIPO_DEBITO_AUTOMATICO` | `debito_automatico` (CBU) |
 
 ```ruby
-CobroDigital.Transaccion::FILTRO_TIPO          => 'tipo'
-CobroDigital.Transaccion::FILTRO_NOMBRE        => 'nombre'
-CobroDigital.Transaccion::FILTRO_CONCEPTO      => 'concepto'
-CobroDigital.Transaccion::FILTRO_NRO_BOLETA    => 'nro_boleta'
-CobroDigital.Transaccion::FILTRO_IDENTIFICADOR => 'identificador'
-
-CobroDigital.Transaccion::FILTRO_TIPO_EGRESO            => 'egresos'           # Transacciones de retiro del dinero depositado por los pagadores.
-CobroDigital.Transaccion::FILTRO_TIPO_INGRESO           => 'ingresos'          # Todo lo que incremente el saldo de la cuenta CobroDigital. Generalmente son sólo las cobranzas.
-CobroDigital.Transaccion::FILTRO_TIPO_TARJETA_CREDITO   => 'tarjeta_credito'   # Solo aquellas cobranzas abonadas con tarjeta de crédito.
-CobroDigital.Transaccion::FILTRO_TIPO_DEBITO_AUTOMATICO => 'debito_automatico' # Está relacionado a los débitos realizados por CBU.
-
-filtro = { CobroDigital.Transaccion::FILTRO_TIPO          => CobroDigital.Transaccion::FILTRO_TIPO_INGRESO,
-           CobroDigital.Transaccion::FILTRO_NOMBRE        => "Algun nombre",
-           CobroDigital.Transaccion::FILTRO_CONCEPTO      => "Algun concepto"
-           CobroDigital.Transaccion::FILTRO_NRO_BOLETA    => "Algun numero de boleta",
-           CobroDigital.Transaccion::FILTRO_IDENTIFICADOR => "Algun identificar" }
+filtro = { CobroDigital::Transaccion::FILTRO_TIPO => CobroDigital::Transaccion::FILTRO_TIPO_INGRESO }
+tx = CobroDigital::Transaccion.consultar(Date.today - 365, Date.today, filtro)
+tx.call(comercio_id, comercio_sid)
+tx.response
 ```
 
-En el siguiente ejemplo se consultan todas las transacciones de ingreso.
+### Micrositios
 
 ```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-numero_boleta = 123
-filtro = { CobroDigital.Transaccion::FILTRO_TIPO => CobroDigital.Transaccion::FILTRO_TIPO_INGRESO} # Solo consulta por transacciones de ingreso
-transacciones = CobroDigital.Transaccion.consultar(Date.today - 1.year, Date.today)
-transacciones.call(comercio_id, comercio_sid)
-transacciones.response # Obtengo el resultado.
+CobroDigital::Micrositio
+  .consultar_actividad('id', 1234, Date.today - 30, Date.today)
+  .call(comercio_id, comercio_sid)
 ```
 
-## Respuesta y Parser de Respuesta
-La response proveniente del WS de CobroDigital siempre consiste en un JSON, donde los datos relevantes son: 
-* resultado: Si fue correcta la consulta realizada.
-* log: En caso de no ser exitosa la consulta, mostrara los errores de la misma.
-* datos: Resultado obtenido de la consulta (Es opcional, depende de la consulta)
+### Respuesta y parser
 
-El metodo _call_ guarda el resultado de la comunicación en el atributo **response** del objeto, por lo que siempres sera posible consultar la **Response**.
-
-A traves del metodo **parse_response** es posible obenter la respuesta parseada en formato hash. Este metodo debe llamarse luego de haberse ejecutado el _call_, 
+El WS responde un JSON. `#parse_response` (tras `#call`) lo decodifica:
 
 ```ruby
-comercio_id = 'HA765587' #Brindado por cobrodigital para realizar pruebas
-comercio_sid = 'wsZ0ya68K791phuu76gQ5L662J6F2Y4j7zqE2Jxa3Mvd22TWNn4iip6L9yq' #Brindado por cobrodigital para realizar pruebas
-numero_boleta = 123
-boleta = CobroDigital.Boleta.obtener_codigo_de_barras(numero_boleta)
+boleta = CobroDigital::Boleta.obtener_codigo_de_barras(123)
 boleta.call(comercio_id, comercio_sid)
 boleta.parse_response
-
-{ :resultado => true, :log => ["Codigos de barra de la boleta encontrados correctamente."], :datos => ["73852040502403101111600000002"] }
+# => { resultado: true,
+#      log: ["Codigos de barra de la boleta encontrados correctamente."],
+#      datos: ["73852040502403101111600000002"] }
 ```
 
+| clave | significado |
+|---|---|
+| `resultado` | `true` si la consulta fue correcta (`ejecucion_correcta == '1'`) |
+| `log` | mensajes / errores del WS |
+| `datos` | resultado de la consulta (opcional, según la operación) |
+
 ## SOAP vs HTTPS
 
-En construcción.
+El transporte default es SOAP (vía `savon`). El cliente HTTPS (`Net::HTTP`) es alternativo: `Cliente.new(con_client: CobroDigital::HTTPS)`. Detalle de ambos modos en [`docs/topology/topology.md`](docs/topology/topology.md).
 
-## Contributing
+## Desarrollo
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cobro_digital. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+```sh
+bundle exec rspec   # suite (ver docs/test/test.md)
+bundle exec rake    # task default :spec
+```
+
+## Contributing
 
+Bug reports y pull requests en GitHub: <https://github.com/gedera/cobrodigital>.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Open source bajo los términos de la [MIT License](http://opensource.org/licenses/MIT).

data/cobro_digital.gemspec

@@ -13,6 +13,12 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/gedera/cobrodigital"
   spec.license       = "MIT"
 
+  spec.metadata["documentation_uri"] = "https://github.com/gedera/cobrodigital/blob/v#{spec.version}/skill"
+
+  # savon ~> 2.12.1 (httpi 2.x) no corre en Ruby 3.0+. El único consumer
+  # (wispro_cloud) usa Ruby 2.7.6. Tope < 3.0 hasta actualizar el stack savon.
+  spec.required_ruby_version = ['>= 2.7', '< 3.0']
+
   # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
   # delete this section to allow pushing this gem to any host.
   # if spec.respond_to?(:metadata)
@@ -26,8 +32,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.6.6"
   spec.add_development_dependency "rake", ">= 13.2.1"
+  spec.add_development_dependency "rspec", "~> 3.13"
 
   spec.add_dependency 'savon', '~> 2.12.1'
 end