Versionado y guía de actualización

Resumen — novedades de qa-20260907c

• nuevoBarrido de numeración. Job que recupera (nunca emite NC) los CAE/NC que ARCA autorizó pero cuya respuesta se perdió (resultado=null local), cuando el POS no reintentó ni facturó por CAEA. Cierra el hueco que ni rama-3 ni CRÍTICO-4 cubrían (sub/sobre-reporte fiscal). Guarda contra el número reusado y el doble-huérfano. Dos fases gateadas OFF (detectar / recuperar); corre antes del job de NC. KPI y alerta Telegram. (Plan 027)
• nuevoKPI RG 5.616 — Condición IVA del receptor. Panel read-only del cockpit que mide los comprobantes autorizados emitidos sin CondicionIVAReceptorId (que ARCA rechaza desde el 01/12/2026), con desglose por comercio/POS. Solo mide; no frena la emisión.
• Dedup del template PDF. El fondo del comprobante se embebía por página y copia (mails de varios MB → error SMTP 552). Ahora se importa una sola vez como form XObject. Sin pérdida de definición; medido: layout=2 ×3 páginas 6.6 MB → 0.55 MB (−92 %); el tamaño ya no crece con copias/páginas.
• Guarda SMTP 5xx. Un 552/550 (permanente) marca ERROR de inmediato, sin gastar los 3 reintentos; un 4xx/transitorio sigue el ciclo normal.
• Corrección de comentario en rama-4. Ajustado a “flush AUTO” (decía “MANUAL”); la fila queda resultado=null a propósito, condición necesaria para la detección de huérfanos.
• Cobertura money-path. 20 tests del barrido y de la guarda 552 (suite total 650/0/24); revisión adversarial de contexto fresco incorporada.

Historial de releases

APIs de integración

Todas read-only, no tocan el money-path de emisión. Fechas en YYYYMMDD. Reemplazá HOST y <api-key> por los de tu entorno.

curl -H "X-Api-Key: <api-key>" \
  "https://HOST/api/ajustes-contingencia?desde=20260901&hasta=20260930&cuit=30712434763"

[
  {
    "ticket": { "suc": 1, "pos": 2, "nroTicket": "T-0001" },
    "caeOriginal": {
      "ptoVta": 559, "nro": 301882, "fecha": "20260901",
      "cae": "75130212345601", "tipoComprobante": 6, "importeTotal": 1234.56,
      "docTipo": 99, "docNro": 0, "condicionIvaReceptorId": 5,
      "impuestos": {
        "netoGravado": 1020.30, "noGravado": 0.0, "exento": 0.0,
        "iva": 214.26, "tributos": 0.0, "total": 1234.56,
        "ivaAlicuotas": [ { "id": 5, "baseImponible": 1020.30, "importe": 214.26 } ],
        "tributosDetalle": []
      }
    },
    "ncAnulacion": { "ptoVta": 559, "nro": 45, "fecha": "20260902", "cae": "75130298765401",
                     "tipoComprobante": 8, "importeTotal": 1234.56, "docTipo": 99, "docNro": 0,
                     "condicionIvaReceptorId": 5, "impuestos": { "…": "idem estructura" } },
    "caeaImpreso": { "ptoVta": 560, "nro": 12000, "caea": "26123456789012",
                     "fchTope": "20260910", "estadoInforme": "INFORMADO",
                     "impuestos": { "…": "idem estructura" } },
    "motivo": "doble facturación CAE+CAEA de contingencia",
    "crossPeriodo": false,
    "estado": "CERRADO"
  }
]

curl -H "X-Api-Key: <api-key>" \
  "https://HOST/api/ajustes-contingencia?desde=20260901&hasta=20260930&formato=libro-iva"

→ { "ventasCbte":      [ "…registro de 266 caracteres por comprobante…" ],
    "ventasAlicuotas": [ "…registro de 62 caracteres por alícuota…" ] }

curl -H "X-Api-Key: <api-key>" \
  "https://HOST/api/libro-iva?desde=20260901&hasta=20260930&formato=json"

→ [
    {
      "fecha": "20260901", "tipoComprobante": 6, "ptoVta": 559, "nroComprobante": 301882,
      "tipofacturacion": "CAE", "cae": "75130212345601", "caea": null,
      "docTipo": 99, "docNro": 0, "razonSocial": "Consumidor Final",
      "importeNeto": 1020.30, "importeNoGravado": 0.0, "importeExento": 0.0,
      "importeIva": 214.26, "importeTributos": 0.0, "importeTotal": 1234.56,
      "iva": [ { "id": 5, "baseImponible": 1020.30, "importe": 214.26 } ]
    }
  ]

curl -H "X-Api-Key: <api-key>" -OJ \
  "https://HOST/api/libro-iva?desde=20260901&hasta=20260930&formato=csv"
# → libro-iva-20260901-20260930.zip  (ventas_cbte.csv + ventas_alicuotas.csv)

Anexo — Pasos de actualización desde qa-20260825

Actualización acumulada qa-20260825 → qa-20260907c. Todas las releases intermedias son swap de jar: no hay ninguna migración de DDL ni cambio de WSDL. La única base de datos que se toca es un INSERT de datos (fila en Tareas), y solo si se activa el barrido.

1. Swap del jar

   Descargar el asset tifactura-spring-20260907c.jar de la release y renombrarlo a tifactura-spring.jar.

   nssm stop TipreTiFactura
   copy /y D:\...\tifactura-spring.jar D:\...\backup\tifactura-spring.PREV-<fecha>.jar
   :: reemplazar el jar por el nuevo
   nssm start TipreTiFactura

2. Configuración (application.yml / variables de entorno)

   Para actualizar no hace falta cambiar nada si usás el deploy/application.yml de esta versión: ya trae todo. Si mantenés tu YAML externo anterior (de qa-20260825), agregá estas dos claves que entraron con BootUI 1.16 (qa-20260907):

   management:
     tracing:
       enabled: false          # BootUI 1.16 trae OpenTelemetry; lo dejamos inerte
   logging:
     pattern:
       correlation: ""         # evita el bloque [ ] vacío en cada línea de log

   El bloque numeracion.barrido.* solo hace falta si vas a activar el barrido (paso 4). Si no está, aplican los valores por default (todo OFF).

3. SQL a correr

   Ninguno es obligatorio — esta actualización no tiene DDL. El único script existe para el barrido (paso 4) y es un INSERT de datos, no un cambio de esquema.

4. Activar el barrido de numeración (opcional, cuando se decida)

   Si no se hace nada de esto, el barrido queda inerte. Para activarlo, en orden:

   a. Correr el INSERT en Tareas (una vez). El script está en el repo o dentro del jar:

   jar xf tifactura-spring.jar BOOT-INF/classes/db/migration/schedule-barrido-numeracion-job.sql

   b. La sección de config es numeracion.barrido en application.yml — así viene por default (cada clave enlazada a una variable de entorno con su valor por default):

   numeracion:
     barrido:
       detectar-enabled:  ${BARRIDO_NUM_DETECTAR:false}     # Fase A: detecta + alerta (solo lectura)
       recuperar-enabled: ${BARRIDO_NUM_RECUPERAR:false}    # Fase B: recupera (escribe) — requiere Fase A
       ventana-dias:      ${BARRIDO_NUM_VENTANA_DIAS:35}    # días hacia atrás por comprobanteFecha
       max-por-corrida:   ${BARRIDO_NUM_MAX:200}            # tope de consultas a ARCA por corrida

   Cada clave se puede prender de dos formas equivalentes (elegí una):

   • Por variable de entorno (recomendado, sin editar el yml): BARRIDO_NUM_DETECTAR=true, luego BARRIDO_NUM_RECUPERAR=true.
   • Editando el yml: poné detectar-enabled: true y luego recuperar-enabled: true en ese bloque.

   c. Secuencia: primero Fase A (detectar-enabled=true, recuperar en false) → reiniciar → mirar la tarjeta “Barrido de numeración” del cockpit y las alertas unos días. Después Fase B (recuperar-enabled=true) → reiniciar.

5. Verificación

   • La app levanta sin errores de configuración.
   • En el cockpit aparecen las tarjetas “Barrido de numeración” y “Condición IVA del receptor (RG 5.616)”.
   • GET /api/cockpit/barrido-numeracion y GET /api/cockpit/condicion-iva-receptor devuelven JSON.
   • Los mails de facturas ahora pesan poco (probar reenviar uno que antes rebotaba con 552).

6. Rollback

   Restaurar el jar de backup y reiniciar. Si se activó el barrido y se quiere revertir, apagar los flags o quitar la fila de Tareas; los comprobantes ya recuperados quedan (son válidos).

Anexo — Respuestas de error al cliente

Catálogo de las respuestas con error que recibe el cliente (SOAP faults + Response con resultado=R), el faultstring de cada caso (CAE/AFIP + mail, con el fix de claridad aplicado) y el diagrama del flujo de envío de email. Documento self-contained; también suelto en docs/errores-respuesta-cliente.html.