cobro_digital
Adaptador Ruby para el Web Service v3 de CobroDigital, 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.
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
En el Gemfile:
gem 'cobro_digital'Luego bundle, o instalar a mano con gem install cobro_digital.
Ruby: requiere
>= 2.7, < 3.0(el stacksavon ~> 2.12.1no corre en Ruby 3.0+). Desde v1.9.0 la gema usa solo stdlib — no depende de ActiveSupport. Los ejemplos conDate#+/.daysson ilustrativos del host. Verdocs/topology/topology.md.
Configuración
| 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 |
Detalle: docs/config/configuracion.md.
Índice de artefactos
| capa | doc | contenido |
|---|---|---|
| interfaz | docs/interface/interface.md |
API Ruby pública (CobroDigital::*) |
| consumidas | docs/consumed/cobrodigital.md |
el WS de CobroDigital: operaciones, payloads, mapeo de error |
| configuración | docs/config/configuracion.md |
inventario de configuración runtime |
| topología | docs/topology/topology.md |
dependencias y modos de transporte |
| test | docs/test/testing.md |
suite RSpec |
| comportamiento | docs/behavior/behavior.md |
flujos: operación simple · batch meta |
| glosario | docs/glossary/glossary.md |
términos del dominio (pagador, boleta, transacción…) |
| seguridad | docs/security/security.md |
secrets-semántica: sanitización de logs (sid + PII) y auth saliente al WS |
| datos · api · errores · eventos · multi-tenancy · data-lifecycle | n/a | ver Mapa de conocimiento en AGENTS.md
|
| release | docs/release/release.md |
publicación a RubyGems tag-driven (v*) vía /gem-release
|
Uso
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: }.
En los ejemplos,
comercio_idycomercio_sidson las credenciales entregadas por CobroDigital. No las hardcodees — leelas de configuración/entorno (ENV, credentials de Rails, etc.).
comercio_id = ENV.fetch('COBRODIGITAL_ID')
comercio_sid = ENV.fetch('COBRODIGITAL_SID') # secretoPagadores
Los pagadores son los clientes a facturar.
# Crear
estructura = { 'Apellido y nombres' => 'Santos Torrealba', 'Id' => 1234, 'Documento' => 33123456 }
pagador = CobroDigital::Pagador.crear(estructura)
pagador.call(comercio_id, comercio_sid)
pagador.response
# Editar
CobroDigital::Pagador.editar('id', 1234, estructura).call(comercio_id, comercio_sid)
# Verificar existencia
CobroDigital::Pagador.verificar('id', 1234).call(comercio_id, comercio_sid)
# Código electrónico (solo tras generar la primera boleta)
CobroDigital::Pagador.codigo_electronico('id', 1234).call(comercio_id, comercio_sid)
# Estructura de pagadores del comercio
CobroDigital::Pagador.estructura_de_datos.call(comercio_id, comercio_sid)El WS no controla duplicados: es posible dar de alta el mismo pagador repetidas veces. El control de unicidad es responsabilidad del consumidor.
Boletas
# 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 # => numero de boleta
# Inhabilitar
CobroDigital::Boleta.inhabilitar(123).call(comercio_id, comercio_sid)
# 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
Movimientos de ingreso/egreso de la cuenta. Filtros disponibles (constantes de CobroDigital::Transaccion):
| 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) |
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.responseMicrositios
CobroDigital::Micrositio
.consultar_actividad('id', 1234, Date.today - 30, Date.today)
.call(comercio_id, comercio_sid)Respuesta y parser
El WS responde un JSON. #parse_response (tras #call) lo decodifica:
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"] }| 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
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.
Desarrollo
bundle exec rspec # suite (ver docs/test/testing.md)
bundle exec rake # task default :specContributing
Bug reports y pull requests en GitHub: https://github.com/gedera/cobrodigital.
License
Open source bajo los términos de la MIT License.