Glosario del dominio
Los términos que aparecen una y otra vez en el código, en los SPECs y en esta documentación. Si entrás nuevo, leé esto antes de la referencia técnica: muchas confusiones son sólo vocabulario. La facturación electrónica argentina tiene su jerga, y encima este proyecto arrastra términos del legacy Seam. Acá están separados los dos mundos.
Facturación electrónica AFIP
| Término |
Qué es |
| AFIP |
La (ex) administración tributaria argentina. Es quien autoriza cada comprobante. En el código aparece como destino de los web services WSAA/WSFEv1. |
| ARCA |
Nombre actual del organismo que sucedió a AFIP. En el código y la doc los términos se usan casi indistintamente: "hablar con ARCA/AFIP" es lo mismo. |
| CAE |
Código de Autorización Electrónico. El código que AFIP otorga por comprobante, online, por SOAP (WSFEv1). Sin CAE, la factura no es válida. Se persiste en Trx.cae. |
| CAEA |
CAE Anticipado. AFIP lo otorga por adelantado para una quincena (un período + quincena). Permite seguir facturando con AFIP caído; lo emitido se informa a AFIP en diferido. Es la red de seguridad del negocio. Entidad Caea (tabla Caeas). |
| WSAA |
Web Service de Autenticación y Autorización de AFIP. Le das un ticket firmado (CMS) y te devuelve un token + sign con los que después llamás a WSFEv1. Endpoint LoginCms. |
| WSFEv1 |
Web Service de Facturación Electrónica v1. El servicio SOAP donde realmente pedís el CAE (FECAESolicitar), consultás el último comprobante (FECompUltimoAutorizado), informás CAEA, etc. |
| TRA / LoginTicketRequest |
El XML que se firma para pedirle credenciales a WSAA. Lleva el servicio destino (wsfe) y una ventana de validez (12 h en este sistema). |
| Token / Sign |
Las credenciales que devuelve WSAA tras el LoginCMS. Viajan en el header de auth de cada llamada WSFE. Se cachean y persisten en EnteFacturador (token, sign, expirationTime). |
| Firma CMS |
El sobre criptográfico (PKCS#7/CMS) con el que se firma el TRA. En este sistema: SHA1, contenido encapsulado, provider BouncyCastle ("BC"). Es invariante: la salida debe ser válida para AFIP. |
Certificado .p12 |
El keystore PKCS#12 (certificado + clave privada) emitido por AFIP, con el que se firma. La ruta/clave/alias se guardan por comercio en EnteFacturador (certP12Path, certP12Password, certP12Alias). |
| Homologación |
El entorno de pruebas de AFIP (wsaahomo/wswhomo). El default del sistema (afip.mode=HOMOLOGACION). |
| Producción |
El entorno real de AFIP (wsaa/servicios1). Se activa con afip.mode=PRODUCCION (perfil prod). |
Comprobantes y partes del comprobante
| Término |
Qué es |
| Comprobante |
El documento fiscal: Factura A/B/C, nota de crédito/débito. Cada uno tiene un tipo (entidad TipoComprobante) con su letra, descripción y reglas (discrimina IVA, discrimina tributos). |
| Punto de venta (PV) |
El número de punto de venta del comercio ante AFIP. Un mismo POS físico puede tener un PV para CAE (pvcae) y otro para CAEA (pvcaea). Mapeado en SucPosPV. |
| Ente facturador |
El emisor del comprobante: la razón social + CUIT + condición IVA + certificado AFIP. Entidad EnteFacturador (tabla EntesFacturadores). Es quien factura. |
| CUIT |
Clave Única de Identificación Tributaria. Identifica al emisor (y a veces al receptor). En EnteFacturador.cuit. |
| Condición IVA |
La categoría fiscal (Responsable Inscripto, Consumidor Final, Monotributo…). Influye en la letra del comprobante. |
| Tributo |
Un impuesto que no es IVA (ej. percepciones, internos). Entidad Tributo, asociada a la Trx. Catálogo: TipoTributo. |
| Alícuota IVA |
El desglose del IVA por alícuota (21%, 10.5%…). Entidad AlicuotaIva, asociada a la Trx. Catálogo: TipoIva. |
| Opcional |
Un campo opcional adicional que AFIP permite en el comprobante. Entidad Opcional. |
| Comprobante asociado |
Referencia a otro comprobante (típico en notas de crédito/débito). Entidad ComprobanteAsociado. |
| Dígito verificador / código de barras |
El código de barras AFIP del comprobante, calculado a partir de CUIT + tipo + PV + CAE + vencimiento (Trx.calculoDigitoVerificador, seteado en @PreUpdate). Se guarda en caeBarCode. |
Los \"enums AFIP\" no son enums de Java
TipoComprobante, TipoDocumento, TipoConcepto, TipoIva, TipoMoneda, TipoTributo suenan a enumeraciones, pero en el código son entidades JPA que mapean tablas de catálogo en SQL Server (ej. @Table(name = "TiposComprobante")). Son lookups de la base, no constantes en código. Tenelo presente cuando los busques.
Entidades de dominio (el modelo)
| Entidad |
Tabla |
Qué representa |
Trx |
Trx |
La transacción de facturación: un comprobante con sus importes, datos del receptor, y el resultado de AFIP (CAE o CAEA). Es el agregado central. |
TrxDetalle |
— |
El detalle/línea del comprobante (ítems). Hijo de Trx. |
Caea |
Caeas |
Un CAEA otorgado: código, período, orden (quincena), fechas de vigencia y un contador de movimientos. |
CaeaSinMovimiento |
— |
El registro de un PV sin movimientos en un CAEA (lo que hay que informar a AFIP al cierre). |
EnteFacturador |
EntesFacturadores |
El emisor: razón social, CUIT, condición IVA, certificado .p12 y el token WSAA cacheado. |
SucPosPV |
SucPosPV |
Relaciona sucursal + POS físico con los números de PV AFIP (pvcae, pvcaea). UQ (suc, pos). |
AlicuotaIva |
— |
Desglose de IVA por alícuota dentro de una Trx. |
Tributo |
— |
Un tributo (no-IVA) dentro de una Trx. |
Opcional |
— |
Campo opcional AFIP dentro de una Trx. |
Tarea |
Tareas |
Una tarea programada: descripción, expresión cron y la clase del job. La fuente del scheduling Quartz. |
JobEjecucion |
JobEjecucion |
La bitácora de cada ejecución de job: inicio, fin, resultado (OK/ERROR) y mensaje de error. |
TrxErrorLog |
TrxErrorLog |
Registro de errores (origen POS/AFIP, tipo, mensaje, referencia). |
CockpitStat |
— |
Estadísticas que alimentan el panel de operación. |
Los catálogos: TipoComprobante, TipoDocumento, TipoConcepto, TipoIva, TipoMoneda, TipoTributo (todos entidades JPA, ver nota arriba). El detalle de campos en Modelo de dominio.
El ciclo de facturación
| Término |
Qué es |
| Emisión online |
El camino feliz: se pide el CAE a AFIP en el momento, por SOAP. |
| Emisión offline (CAEA) |
El fallback: AFIP no responde, se factura con el CAEA ya otorgado y se informa después. |
| Idempotencia |
La garantía de no facturar dos veces lo mismo. El sistema detecta una Trx ya facturada y devuelve su resultado sin volver a ir a AFIP (short-circuit). Invariante sagrada. |
| Reconciliación |
El proceso (job NotaCreditoReconciliacionJob) que detecta un mismo ticket facturado por CAE y por CAEA, y emite una nota de crédito para anular el duplicado. |
| Incrementar movimientos |
Tras guardar una Trx con CAEA, se incrementa el contador Caea.movimientos (CaeaHome.incrementarMovimientos). Invariante: se llama tras cada save. |
getCaea (handoff al POS) |
El paso 1 del flujo del POS por REST: pide los CAEA vigentes y la config de su punto de venta. |
La migración y la capa de compatibilidad
| Término |
Qué es |
| Legacy |
El sistema original: JBoss EAP 7 / Seam 2.3.1 / JAX-WS, Java 8, namespace javax.*. La fuente de la verdad funcional. |
| Shim |
Una capa de compatibilidad que imita una API vieja sobre tecnología nueva. Acá: seam-compat. |
seam-compat |
El shim de este proyecto: clases en el paquete org.jboss.seam.* que reimplementan el subconjunto de Seam que la app usa, respaldadas por Spring. Permite no tocar imports. |
| Lift & shift |
Mover código tal cual, sin reescribir lógica (sólo lo mínimo: javax→jakarta). La mayoría del código de negocio. |
| Verde / Amarillo / Rojo |
La clasificación de riesgo de cada clase legacy. Verde: lift & shift, 0 cambios. Amarillo: corre vía seam-compat, 0 cambios de fuente. Rojo: hay que reescribir funcionalmente (email, un path de PDF, UI admin, seguridad). |
| Seam |
El framework de aplicación (JBoss Seam 2.3) sobre el que corría el legacy. Aportaba inyección, scopes, EntityHome/EntityQuery, transacciones. |
@Name / @Scope |
Anotaciones Seam que registraban un componente y su scope. En seam-compat, se escanean y se convierten en beans Spring con el scope mapeado. |
Component.getInstance(name) |
El accesor estático de Seam para obtener un componente. En seam-compat, traduce a applicationContext.getBean(name). |
| Scope EVENT |
El scope Seam "una instancia por invocación" (request/SOAP/job). Mapeado al scope Spring custom "seamEvent". |
EntityHome / EntityQuery |
Clases base de Seam para CRUD y queries. Reimplementadas en org.jboss.seam.framework.* con la semántica exacta del legacy (ver invariantes). |
| Invariante |
Un comportamiento del legacy que no se puede cambiar (flush MANUAL, update() que sólo flushea, firma SHA1…). Ver Invariantes sagradas. |
| SPEC |
Cada una de las 16 especificaciones de migración (SPEC-001…SPEC-016) en specs/. Se ejecutan en orden de dependencias. |
| HITO (A–E) |
Los milestones del ROADMAP.md: A (core arranca), B (WSDL congelado), C (jobs corriendo), D (PDF/email paridad), E (listo prod). |
| Paridad |
La propiedad de que la salida nueva sea idéntica a la del legacy (mismo CAE, mismo PDF, mismo email). La verifica la suite de SPEC-016. |
Infraestructura y técnico
| Término |
Qué es |
| Spring Boot 4 |
El framework destino (4.0.7, sobre Spring Framework 7). Reemplaza a JBoss EAP. |
| Apache CXF |
El stack SOAP (4.2.2) que publica los endpoints TrxWS/CaeaWS/TiFacturaOnlineManagerWS. Reemplaza al CXF del contenedor JBoss. |
| Contract-first |
Generar el código SOAP desde el WSDL (con wsdl2java), no al revés. Garantiza que el contrato no cambie. |
| Quartz |
El scheduler de jobs. Lee las tareas de la tabla Tareas. |
| BouncyCastle |
La librería criptográfica (1.78.1) para la firma CMS del WSAA. |
| Hibernate / JPA |
El ORM (Hibernate 7.2.x, Jakarta Persistence 3.2). Mapea las entidades a SQL Server. |
hbm2ddl=none |
La config que dice "no toques el esquema": la app nunca genera ni altera DDL; lo administra el cliente. |
| Flush MANUAL |
El modo en que el EntityManager no auto-flushea a mitad de transacción. Los flush ocurren sólo en EntityHome.persist/update/remove. Invariante. |
| Cockpit |
El panel de operación (/api/cockpit): métricas, estado AFIP, jobs, últimas transacciones, ABM de SucPosPV. |
tls-insecure |
La opción (afip.tls-insecure, default true) que hace trust-all del certificado AFIP, reproduciendo el legacy detrás de nginx. |
| Cron en DB |
El patrón de tener la expresión cron de cada job en la base (Tarea.programacion), no en código. |
Por dónde seguir