Seis facturadores, un solo servicio.

01 — De dónde partió

Seis proyectos casi gemelos, cada uno con su propio jar

Cada cliente (DINO, ALMACOR, BECERRA, TIZIANO, CARACOL, CYRE) era un proyecto Maven separado. El ~90 % del código era idéntico entre los seis; la variación real vivía en apenas 5 archivos. El problema no era el tamaño: era que cada cambio había que hacerlo seis veces. Un ajuste regulatorio de AFIP (como la RG 5782) significaba tocar, compilar y desplegar seis repos a mano — y con eso, seis oportunidades de que uno quedara distinto.

02 — Cómo se unificó

Un núcleo compartido + un borde chico por cliente

El servicio unificado tiene un núcleo que se escribe una sola vez (el armado del comprobante, el scheduler que notifica a AFIP, el cliente HTTP al Manager) y que no sabe nada de clientes: trabaja contra un contrato neutral, ComprobanteRecord. Cada cliente aporta solo dos piezas chicas —cómo lee su tabla y qué impuestos emite— que se enchufan según la variable TIFACTURA_CLIENT. El mismo jar arranca como DINO, como CARACOL o como cualquiera de los seis.

El recorrido de un comprobante

Puesto en fila, se ve qué es compartido (una vez para todos) y qué es por cliente:

03 — Arquitectura técnica

Cómo está armado el servicio, por dentro

Stack: Spring Boot 2.4.1 sobre Java 8, contra SQL Server (driver mssql-jdbc), empaquetado como jar ejecutable con Maven (com.tipre:tifactura-sql-rest, versión CalVer — hoy 20260804, la misma que se ve en el cockpit y en /status). Un solo Application.java con @SpringBootApplication + @EnableScheduling; nada de perfiles Spring por cliente — la selección es por property, ver más abajo.

Estructura de paquetes

com.tipre.tifactura.sql.rest
Application.java                    # @SpringBootApplication, @EnableScheduling
contract/
  ComprobanteRecord                 # read-model normalizado (interface)
  TributoStrategy                   # qué tributos emite el cliente (interface)
core/
  convert/
    TrxAssembler                    # arma el Trx — compartido, sin lógica de cliente
    ComprobanteConverter            # elige la TributoStrategy según tifactura.client
  read/
    ComprobanteReader               # puerto de lectura, esquema-agnóstico
  schedule/
    ComprobanteNotifier             # scheduler único (reemplaza los 6 TresuNotifier)
  status/   StatusHolder            # estado en memoria para /status y el cockpit
  startup/  StartupConfigLogger     # vuelca la config al log, secretos redactados
client/
  dino/ almacor/ becerra/ tiziano/ caracol/ cyre/  # 1 ComprobanteReader por cliente
  g1/ g2/ g3/                       # las 3 TributoStrategy reales
schema/retail/
  Almacor|Becerra|Tiziano|Caracol|CyreTresu # @Entity + su *Repository
model/
  sql/  Tresu                     # entidad original de DINO, implementa ComprobanteRecord
  trx/  Trx, Tributo, AlicuotaIva, ...  # DTO que viaja al Manager
web/
  StatusController                  # GET /status
  CockpitController                 # GET /cockpit, /, /doc
  client/ TiFacturaOnlineManagerClient  # cliente HTTP hacia el Manager

Las tres costuras

El núcleo compartido no tiene ni un if (cliente == "dino"). Toda la variación entra por tres puntos de extensión, cada uno resuelto por Spring según tifactura.client:

El contrato ComprobanteRecord

Es la interfaz que hace posible que TrxAssembler no sepa nada de clientes. Expone getters neutrales — identidad del comprobante (id, ptoVta, tipoFactura, nroComprobante, cuit, fechaComprobante, caea, clientType), reconciliación RG 5782/CAE-CAEA (nroSuc, nroPos, nroTicket), comprobante asociado para NC/ND, importes, tributos (IIBB, Com.Ind., Percepción IVA, Impuesto Interno) y el desglose de IVA (21/10,5/exento). Cada entidad @Entity por cliente implementa la interfaz delegando a sus propios getters existentes — un getter que no aplica a esa familia de esquema devuelve null/0, nunca lanza.

Selección por tifactura.client

La property tifactura.client (env TIFACTURA_CLIENT) decide dos cosas a la vez, en dos lugares distintos del código:

• Qué ComprobanteReader se registra — cada uno de los 6 (client/<cliente>/<Cliente>ComprobanteReader.java) lleva @ConditionalOnProperty(name = "tifactura.client", havingValue = "<cliente>"): en cualquier instancia dada, Spring solo registra uno de los seis beans.
• Qué TributoStrategy se inyecta — un switch en el constructor de ComprobanteConverter mapea el nombre del cliente a G1/G2/G3: dino→G1, almacor/becerra/tiziano/cyre→G2, caracol→G3. Un valor no reconocido lanza IllegalStateException al arrancar — el jar no levanta con un cliente mal escrito.

Cómo agregar un cliente nuevo

El patrón ya se repitió cinco veces (ALMACOR, BECERRA, TIZIANO, CARACOL, CYRE detrás de DINO); agregar un séptimo cliente es mecánico:

1. Entidad @Entity que mapee la tabla real del cliente e implemente ComprobanteRecord (schema/retail/<Cliente>Tresu.java) — copiar el patrón de AlmacorTresu si el esquema es de_tresu (prefijo húngaro) o de CaracolTresu si es detresu (columnas planas), con sus @Formula donde haga falta.
2. Su *Repository (Spring Data JPA) con findPV(), findInvoicesToNotify(), updateFechaAfip().
3. Su ComprobanteReader (client/<cliente>/<Cliente>ComprobanteReader.java) implementando el puerto, con @ConditionalOnProperty(name = "tifactura.client", havingValue = "<cliente>").
4. Mapear cliente→estrategia en el switch de ComprobanteConverter — reusar G1/G2/G3 si el impuesto que emite ya existe, o sumar una G4 si aparece una combinación nueva.
5. Golden de caracterización en src/test/resources/golden/<cliente>/: casos representativos (factura A/B, NC/ND, con/sin percepción, CUIT/DNI/sin documento) capturados contra el comportamiento del converter original de ese cliente, para congelar el "antes" antes de tocar nada.

04 — Los seis clientes, con nombre y apellido

Qué hace distinto cada uno

Esta es la tabla maestra. El color del borde indica la base: TipreRetail · de_tresu o TipreSucursales · detresu.

Lo mismo, agrupado por nombre real

Donde varios clientes comparten una característica, acá están juntos — sin códigos, con nombre:

Nota técnica (para el equipo de desarrollo): internamente la estrategia de tributos se llama G1 (Percepción IVA = DINO), G2 (Impuesto Interno = ALMACOR, BECERRA, TIZIANO, CYRE) y G3 (ambos = CARACOL). Para configurar un cliente no necesitás saber esto — solo el nombre del cliente. Los G1/G2/G3 son detalle de implementación.

05 — Ajustes y correcciones

Qué cambió a propósito al unificar

Unificar preservó el comportamiento de cada cliente byte por byte, salvo estos cambios deliberados — decididos, no accidentales. Cada uno quedó auditado contra un test que congela el "antes" y el "esperado con el cambio".

06 — Instalación

Poner una instancia en pie, por cliente

Cada cliente es una carpeta con el mismo jar adentro y su propio config al lado. El jar nunca lleva credenciales ni datos de un cliente en particular — todo lo que lo distingue vive fuera, en config\application-prod.yml.

Layout de instalación

C:\TiFactura\<cliente>\
  tifactura-sql-rest-20260804.jar   # el mismo binario para los 6 clientes
  config\
    application-prod.yml            # copiado de config-template\ y editado para ESTE cliente
  run.bat                            # opcional — ver Sección 07
  log\                                 # se crea solo al primer arranque

De dónde sale el jar

• GitHub Release — la etiqueta v20260804 (u otra posterior) trae el jar ya compilado, listo para copiar.
• Compilado local — parado en la raíz del repo: mvn -DskipTests package genera target\tifactura-sql-rest-20260804.jar. La versión sale de pom.xml (<version>20260804</version>) y se filtra dentro del jar como tifactura.version — es la misma que después se ve en /status y en el cockpit.

Requisitos

• Java 8 o superior instalado en la máquina donde corre (el jar es Spring Boot 2.4.1 / Java 8, corre igual en un JRE más nuevo).
• Acceso de red a la base del cliente (SQL Server, el host/puerto/base que se configuran en spring.datasource.url).
• Acceso de red al TiFacturaOnline Manager (la URL de tifacturaonlinemanager.service.url) — es quien finalmente habla con AFIP.

07 — Ejecución / operación

Arrancarlo y saber que está vivo

Con run.bat

Pensado para no tener que acordarse de nada. Parado en la carpeta que tiene el jar al lado:

• Primer arranque — no encuentra config\application-prod.yml, lo crea copiando config-template\application-prod.yml, y se frena pidiendo editarlo (cliente, password de la base, IDs fiscales). No levanta el servicio todavía — a propósito, para no arrancar con datos de plantilla.
• Segundo arranque (con el YML ya editado) — encuentra el jar en target\, y lo levanta: java -jar tifactura-sql-rest-20260804.jar.

Con java -jar directo

Sirve para el layout de instalación de la Sección 06 (jar + config\ al lado, sin target\). Hay que estar parado en esa carpeta al ejecutar:

cd C:\TiFactura\almacor
java -jar tifactura-sql-rest-20260804.jar

java -jar tifactura-sql-rest-20260804.jar --spring.config.additional-location=file:C:/TiFactura/almacor/config/

El log de arranque

Al levantar, StartupConfigLogger vuelca en el log toda la configuración efectiva (perfil activo + cada property de la app), una sola vez, apenas el contexto de Spring está listo. Cualquier clave cuyo nombre contenga password, secret, token, credential u otro marcador equivalente se imprime como **** — nunca en texto plano. Es la forma más rápida de confirmar, con solo mirar el log, qué cliente es esta instancia y contra qué está apuntando.

Dónde quedan los logs

Consola (STDOUT) y archivo, según logback.xml: rotación diaria o cada 50 MB, con 30 días de historial. La ruta del archivo la fija logging.file.name — en la plantilla de prod es ./log/tifactura.log, relativa a la carpeta desde donde se ejecuta el jar (por eso importa el directorio de trabajo, igual que con el config externo).

08 — Configuración por cliente

Cómo levantar cada uno (sin dudas)

Toda la config entra por variables de entorno — no hay nada hardcodeado. Para que una instancia sea un cliente u otro, cambian solo tres cosas: qué cliente es, a qué base pega, y qué IDs de tributo usa. El resto es común.

Lo que cambia por cliente

Los IDs marcados "no usa" pueden quedar sin definir (toman 0 por defecto): esa estrategia no se ejecuta para ese cliente. Definir el que corresponde con el valor real de ese cliente en su base.

Lo que es común a todos

# Base de datos (host/puerto propios de cada cliente)
DATABASE_HOST=...   DATABASE_PORT=1433
DATABASE_USER=...   DATABASE_PASSWORD=...
# Operación
NOTIFY_TO_AFIP_CRON_SCHEDULER=0 0/5 * * * ?
TIFACTURAONLINEMANAGER_SERVICE_URL=http://.../manager
PROCESS_MAX_RESULTS=50   LOGGING_FILE_NAME=/var/log/tifactura.log
# Tributos/IVA comunes (IDs reales de AFIP en Manager)
ID_ENTE_FACTURADOR=…   ID_TRIBUTO_ING_BRUTO=…   ID_TRIBUTO_COMIND=…
ID_IVA_0=…   ID_IVA_105=…   ID_IVA_21=…

Dos formas de fijar estas mismas claves, según cómo se instale (ver Sección 06): variables de entorno (arriba, las consume application-prod.properties empaquetado en el jar) o directamente en config\application-prod.yml externo, con notación anidada YAML. Son la misma configuración — el YML externo, cuando existe, tiene prioridad y no necesita ninguna variable de entorno.

Referencia completa — cada clave del YAML

Las únicas claves que de verdad distinguen a un cliente de otro son las cuatro primeras filas (marcadas "sí") más id.tributo.perciva / id.tributo.impinterno según qué tributo emita — coincide exactamente con la tabla de la subsección siguiente.

Bloque específico, cliente por cliente

Cada tarjeta muestra solo lo que distingue a ese cliente. Combinalo con el bloque común de arriba.

TIFACTURA_CLIENT=dino
DATABASE_NAME=TipreRetail
ID_TRIBUTO_PERCIVA=<real>
# ID_TRIBUTO_IMPINTERNO no aplica

TIFACTURA_CLIENT=almacor
DATABASE_NAME=TipreRetail
ID_TRIBUTO_IMPINTERNO=<real>
# ID_TRIBUTO_PERCIVA no aplica

TIFACTURA_CLIENT=becerra
DATABASE_NAME=TipreRetail
ID_TRIBUTO_IMPINTERNO=<real>
# ID_TRIBUTO_PERCIVA no aplica

TIFACTURA_CLIENT=tiziano
DATABASE_NAME=TipreRetail
ID_TRIBUTO_IMPINTERNO=<real>
# ID_TRIBUTO_PERCIVA no aplica

TIFACTURA_CLIENT=caracol
DATABASE_NAME=TipreSucursales
ID_TRIBUTO_PERCIVA=<real>
ID_TRIBUTO_IMPINTERNO=<real>

TIFACTURA_CLIENT=cyre
DATABASE_NAME=TipreSucursales
ID_TRIBUTO_IMPINTERNO=<real>
# ID_TRIBUTO_PERCIVA no aplica

09 — El cockpit

Ver el estado en vivo, sin entrar a la base

Cada instancia expone un tablero liviano en /cockpit (y el dato crudo en /status). Muestra de un vistazo qué cliente es, qué impuestos emite, contra qué base pega, y cómo salió la última corrida. Se autorefresca solo cada 60 s. Así se ve corriendo como ALMACOR:

Es parte del propio jar — no depende de nada externo (la librería del tablero, ArrowJS, también viaja adentro). Cambiás TIFACTURA_CLIENT y el mismo cockpit muestra otro cliente. Link en vivo: /cockpit.

Endpoints

Ninguna de las cuatro rutas ejecuta una consulta SQL: /status y /cockpit leen únicamente StatusHolder (en memoria, lo actualiza el scheduler) y properties ya resueltas al arrancar — cero carga y cero bloqueos sobre la base del cliente, la tengan del tamaño que la tengan. /status también expone tifactura.version (la misma versión del pom.xml que se ve como pill en el cockpit), así que un vistazo alcanza para saber qué build está corriendo cada instancia.

10 — Troubleshooting

Cuando algo no arranca o no cierra

11 — Estado

Dónde está parado hoy

• 6/6 clientes migrados a un solo servicio, cada uno probado byte-a-byte contra su comportamiento original (golden tests de caracterización, ver Sección 03).
• 5/6 verificados contra base de datos real: DINO, ALMACOR, BECERRA, TIZIANO (TipreRetail) y CYRE (TipreSucursales) arrancan y leen correctamente.
• CARACOL a un paso: su mapeo es correcto y comparte estructura con CYRE (verificado); falta una base de un cliente CARACOL real —con columnas de percepción IVA— para confirmar el arranque.
• Columnas de reconciliación (inropos/inroticket en TipreRetail, nropos/nroticket en TipreSucursales) — el mapeo está hecho, pero solo cubierto por los integration tests manuales (-Dit.db=true); falta confirmarlas contra las 4 bases de producción antes de habilitar el envío en cada una.
• Dos pendientes de datos de producción, con el comportamiento actual preservado mientras tanto: la fecha de comprobante asociado en CARACOL/CYRE (hoy no se envía en NC/ND — falta confirmar si AFIP la exige) y el importeTotal de TIZIANO desde fprecioTotal (falta confirmar que coincide con la suma de líneas).
• Integración con el Manager validada (revisión adversarial, 2026-08-13): el notificador se conecta y notifica CAEA correctamente contra TiFacturaOnlineManager, y los tres campos de la unificación (cbteFchHsGen, nroSuc/nroPos/nroTicketPos) llegan y se usan en la reconciliación. Limitación preexistente conocida: con 2+ comercios en un mismo Manager, el ente facturador anidado se descarta (hoy no aplica — la topología real es 1 comercio por Manager).