Cliente AFIP (ARCA)¶

Referencia técnica del cliente que TiFacturaOnlineNext usa para hablar con AFIP/ARCA: el login en WSAA, las operaciones de WSFEv1 (CAE, CAEA, consultas) y el transporte TLS. Para el porqué del flujo de negocio (cuándo se pide CAE vs CAEA), mirá El ciclo de facturación. Para los endpoints SOAP que este backend expone (no los que consume), mirá API SOAP.

Todo el cliente vive bajo com.tipre.tifacturaonlinemanager.action.ws.client (SPEC-010). Está escrito en raw-SOAP (armado de sobres a mano + parseo DOM por local-name), no con stubs generados: así cada pieza es testeable offline inyectando un transporte fake, y solo el transporte real toca la red.

Stack y origen¶

Los valores productivos los sobrescribe application-prod.yml; los de homologación son el default seguro en application.yml.

Layout de paquetes¶

action.ws.client
├── AfipCaeService            orquesta emisión/consulta de CAE de una Trx
├── wsaa/                     login WSAA (TRA → CMS → TA cacheado)
├── wsfe/                     clientes WSFEv1 (CAE, CAEA, consultas, dummy)
├── common/                   transporte SOAP + SSLContext + captura de tráfico
└── exceptions/              excepciones de dominio AFIP

Flujo WSAA → WSFE¶

Antes de cualquier operación WSFE hay que tener un Ticket de Acceso (TA = token + sign) vigente. El TA se reutiliza en 3 niveles (memoria → DB → LoginCms) para no chocar con el "El CEE ya posee un TA válido" de AFIP, y se emite con el .p12 del comercio (multi-ente: un TA por CUIT). El orquestador de esa estrategia es EnteFacturadorTokenProvider; WSFE adjunta el TA en el header Auth de cada llamada.

sequenceDiagram
    participant S as AfipCaeService
    participant P as EnteFacturadorTokenProvider
    participant C as WsaaTokenCache (L1)
    participant DB as EnteFacturador (L2)
    participant CL as AfipCertLoader
    participant W as WsaaClient
    participant SG as WsaaCmsSigner
    participant WS as WSAA (AFIP)
    participant FE as WsfeCaeClient
    participant AR as WSFEv1 (AFIP)

    S->>P: get(ente)
    P->>C: get(cuit, issuer)
    alt L1 hit (TA en memoria, vigente)
        C-->>P: WsaaCredentials
    else L1 miss
        C->>DB: TA persistido en EnteFacturador
        alt L2 hit (token/sign/exp en DB, vigentes)
            DB-->>P: WsaaCredentials (reutilizado)
        else L3 — LoginCms
            P->>CL: loadAndLogin(ente, ...)
            CL->>CL: resuelve .p12 del ente (path/alias→CUIT/pass)
            CL->>W: login(privateKey, cert, params)
            W->>W: LoginTicketRequest.build (TRA)
            W->>SG: sign(TRA) → CMS Base64 (SHA1withRSA)
            W->>WS: POST loginCms (SOAPAction urn:LoginCms)
            WS-->>W: loginTicketResponse (token+sign+expirationTime)
            W-->>CL: WsaaCredentials
            CL-->>P: WsaaCredentials
            P->>DB: persiste TA en EnteFacturador (REQUIRES_NEW)
        end
    end
    P-->>S: WsaaCredentials (token+sign)
    S->>FE: solicitarCae(WsfeAuth, FecaeInput)
    FE->>AR: POST FECAESolicitar (Auth=token+sign+cuit)
    AR-->>FE: CAE + CAEFchVto + Resultado
    FE-->>S: FecaeResult

WSAA — login (paquete wsaa)¶

El login es una sola operación SOAP (loginCms), pero el cliente la parte en piezas chicas y testeables. El orquestador es WsaaClient.

El orquestador del TA por ente (cache L1 + persistencia L2 + login L3) es EnteFacturadorTokenProvider (vive en action.ws.client, no en wsaa): ver más abajo El cache del TA en 3 niveles.

El TRA (LoginTicketRequest)¶

El TRA es por naturaleza variable en el tiempo (uniqueId y fechas cambian cada llamada): no hay "TRA golden" byte-exacto, el requisito es que AFIP lo acepte. Reglas de tiempo (preservadas del legacy AfipWSDictionary.create_LoginTicketRequest):

• uniqueId = epoch en segundos de "ahora".
• generationTime = ahora menos 10 min (evita el fault por desincronización de reloj).
• expirationTime = ahora + ticketTimeMs (default 12 h vía afip.ticket-time-ms=43200000).
• source = subjectDN del certificado firmante; destination = afip.dstdn.

<loginTicketRequest version="1.0">
  <header>
    <source>...subjectDN del .p12...</source>
    <destination>cn=wsaahomo,o=afip,c=ar,serialNumber=CUIT 33693450239</destination>
    <uniqueId>1719400000</uniqueId>
    <generationTime>2026-06-26T11:50:00.000-03:00</generationTime>
    <expirationTime>2026-06-26T23:50:00.000-03:00</expirationTime>
  </header>
  <service>wsfe</service>
</loginTicketRequest>

La firma CMS (WsaaCmsSigner)¶

WsaaCmsSigner firma el TRA con BouncyCastle y lo devuelve en Base64. Dos invariantes (REFERENCE.md §5), preservados respecto del legacy 1.46:

• SHA1withRSA (digest SHA-1) — constante SIGNER_ALGORITHM. No cambiar sin decisión explícita.
• CMS encapsulado (generate(content, true)): el TRA viaja dentro del CMS firmado.

El provider BouncyCastleProvider se registra una sola vez (idempotente). Tiene dos entradas: sign(tra, privateKey, certificate) y signWithP12(tra, p12Path, password, alias), que carga la clave/cert de un keystore PKCS12.

La resolución del cert (AfipCertLoader)¶

Resolver el .p12 del ente y emitir el login se extrajo a una clase dedicada AfipCertLoader (commit refactor(wsaa) b3db829), separada del @Bean de wiring para poder testear la lógica pura sin un .p12 real. Reglas (idénticas al legacy, byte-equivalentes):

• validateCertConfig(ente) — falla con IllegalStateException si el ente es null o certP12Path está vacío. Es el check fail-closed por ente: con multi-comercio, un cert mal configurado en UN comercio rompe solo sus emisiones, no las de los demás.
• resolveAlias(ente) — usa certP12Alias si está seteado; si está vacío, cae al CUIT por convención (como el legacy).
• loadAndLogin(ente, wsaa, metrics) — carga el keystore PKCS12 (password null → ""), saca la clave/cert por alias, llama a WsaaClient.login(...) con WsaaLoginParams(wsaaUrl, dstdn, service, ticketTimeMs) y registra la métrica TOKEN (recordOk / recordError).

AfipClientConfig arma el @Bean("rawWsaaLogin") (Function<EnteFacturador, WsaaCredentials>) delegando en AfipCertLoader.loadAndLogin(...). Ese login es crudo: emite un TA nuevo cada vez, sin cache ni persistencia. La reutilización la pone arriba EnteFacturadorTokenProvider. El .p12 se carga lazy (recién en el login), así el contexto Spring levanta sin cert presente (necesario para los tests).

El parseo (WsaaLoginResponseParser)¶

La respuesta de loginCms trae <loginCmsReturn> con el loginTicketResponse como XML escapado: el parser lo desescapa (getTextContent) y lo vuelve a parsear para sacar token / sign / expirationTime (búsqueda por local-name, ignora prefijos de namespace). Si hay <faultstring>, lanza IllegalStateException.

El cache del TA en 3 niveles (EnteFacturadorTokenProvider)¶

AFIP rechaza un loginCms si ya hay un TA vigente ("El CEE ya posee un TA válido"), así que el TA se reusa lo más posible. El provider lo busca en 3 niveles, por CUIT, fiel al legacy:

EnteFacturadorTokenProvider.get(ente) re-lee el ente managed por id (puede venir detached desde la tx externa), pide a WsaaTokenCache.get(cuit, issuer), y el issuer mira primero el TA persistido en la fila (L2): si sigue válido lo reutiliza, si no hace LoginCms (L3) y persiste el TA nuevo en EnteFacturador. Toda la operación corre en su propia transacción @Transactional(REQUIRES_NEW): el TA vale en AFIP independientemente de que la operación de negocio commitee o no, así que se persiste por separado (como el job legacy).

El margen de seguridad para considerar un TA "vigente" es 10 min antes de expirationTime (WsaaTokenCache.isStillValid); si el expirationTime no se puede parsear, se considera inválido (renueva).

Evict del TA en 2 niveles (cambio de cert sin reiniciar)¶

Cuando se rota el .p12 de un comercio, el TA viejo hay que invalidarlo o la próxima emisión seguiría usando el cert anterior cacheado. EnteFacturadorTokenProvider.evict(ente) lo hace en 2 niveles, también en REQUIRES_NEW:

• L1 (memoria): WsaaTokenCache.evict(cuit) remueve la entrada del CUIT (idempotente; no toca otros CUITs).
• L2 (DB): re-lee la fila managed por id y nula token / sign / expirationTime + flush (sobre detached el flush no persistiría — invariante flush-sin-merge, ver Invariantes).

No se fuerza un re-login inmediato (chocaría con el "TA ya válido" de AFIP): el siguiente get(ente) ve L1 miss + L2 vacío ⇒ LoginCms con el cert nuevo. El disparador es la acción "recargar cert" del ABM: POST /api/cockpit/comercios/{id}/cert/reload → EnteFacturadorAdminService.recargarCert(id) (valida que el cert esté configurado, si no responde 422) → evict(ente).

WSFEv1 — operaciones (paquete wsfe)¶

Todos los clientes WSFE comparten el patrón: sobre SOAP 1.1 con xmlns:ar="http://ar.gov.afip.dif.FEV1/", header Auth (WsfeAuth.toXml() = Token + Sign + Cuit), transporte SoapTransport inyectable, y parseo que primero busca <faultstring>, luego <Err>, y recién después el dato.

CAE — WsfeCaeClient (FECAESolicitar)¶

Emite un comprobante por request (como el legacy). El orden de los elementos de FECAEDetRequest respeta el XSD (lo construye FeDetRequestXml): si se altera, AFIP rechaza. El parse exige Resultado=A y un CAE no vacío; ante Err o Resultado=R lanza IllegalStateException con las observaciones (<Obs>). El resultado es FecaeResult (cae, caeFchVto, fchProceso, resultado).

El detalle completo: FeDetRequestXml¶

FeDetRequestXml.build(FecaeInput) arma los campos de FEDetRequest en el orden exacto del XSD (propOrder), compartido entre FECAESolicitar (CAE) y FECAEARegInformativo (CAEA), que llevan el mismo detalle base. Además de los escalares (concepto, docs, importes, moneda, CondicionIVAReceptorId, fechas de servicio) y el bloque Iva, emite tres sub-arrays opcionales que el legacy sí mandaba y que la reescritura SPEC-010 había perdido (restaurados en el commit 74f1a71):

El orden importa: CbtesAsoc y Tributos van antes del bloque Iva, Opcionales después. El texto libre (Desc de tributo, Valor/Id de opcional) se escapa a mano con paridad JAXB —incluye \r → 
— para no romper el XML ni el byte-a-byte del legacy.

TrxToFecaeMapper.map(Trx, cuit) es el puente dominio → FecaeInput: recorre trx.getComprobantesAsociados(), trx.getTributos() y trx.getOpcionales() además de las alícuotas de IVA. El Cuit del comprobante asociado sale del ente emisor (el cuit que recibe el mapper), no de la entidad ComprobanteAsociado —por eso la firma es map(Trx, cuit) y no map(Trx).

CAEA — WsfeCaeaClient¶

Cubre el ciclo CAEA completo. Detalles fidelity-critical detectados con el smoke de homologación, documentados en el propio código:

• FECAEASolicitar / FECAEAConsultar: AFIP espera <Periodo> y <Orden> directos bajo la operación, no envueltos en <FeCAEAReq> (envolverlos daba [15004] / [15005]).
• La operación de "sin movimiento" es FECAEASinMovimientoInformar, no FECAEASinMovimiento (AFIP no reconoce ese SOAPAction).
• FEParamGetPtosVenta filtra los PV con Bloqueado != "N" y los que no sean EmisionTipo CAEA.
• Los <Err> se exponen vía WsfeFault con su código (p.ej. 602 = CAEA inexistente → solicitar uno nuevo).

CaeaResult trae caea, periodo, orden, fchVigDesde, fchVigHasta, fchTopeInf, fchProceso.

Consultas de solo lectura¶

• WsfeUltimoComprobanteClient (FECompUltimoAutorizado) — la operación más usada en prod; estableció el patrón WSFE. Devuelve el long del último comprobante autorizado.
• WsfeConsultaClient (FECompConsultar) — consulta un comprobante ya autorizado por (PtoVta, CbteTipo, CbteNro) y devuelve su CAE (campo AFIP CodAutorizacion), vencimiento (FchVto), proceso y resultado.

El orquestador AfipCaeService¶

AfipCaeService arma el flujo end-to-end para una Trx: pide el TA al Supplier<WsaaCredentials> (cacheado), mapea Trx → FecaeInput (TrxToFecaeMapper), llama a WSFE y actualiza la Trx in-place (cae, caeFchVto, fchProceso, resultado, caeBarCode). Registra métricas de cockpit (recordOk / recordError). Ante rechazo setea resultado="R" y re-lanza.

public FecaeResult emitirCae(Trx trx, EnteFacturador ente) {
    WsaaCredentials creds = tokenForEnte.apply(ente);   // TA POR ENTE (no un Supplier sin parámetro)
    WsfeAuth auth = new WsfeAuth(creds.getToken(), creds.getSign(), ente.getCuit());
    FecaeInput input = TrxToFecaeMapper.map(trx, ente.getCuit());   // el CUIT alimenta los CbtesAsoc
    FecaeResult cae = caeClient.solicitarCae(auth, input);
    applyTo(trx, ente, cae);          // cae, caeFchVto, fchProceso, resultado, caeBarCode
    metrics.recordOk(Op.CAE);
    return cae;
}

Transporte SOAP (paquete common)¶

La red está aislada detrás de dos interfaces gemelas: SoapTransport (genérica, para WSFE) y WsaaSoapTransport (para WSAA). Ambas exponen post(url, soapAction, soapBody) y devuelven el body de respuesta crudo.

Cada POST loguea el sobre completo al logger TRAFFIC ([ARCA-OUT] / [ARCA-IN] / [WSAA-OUT] / [WSAA-IN]) y registra en TrafficCapture. Si el HTTP status es ≥ 400 lee del errorStream igual, para devolver el fault de AFIP.

TLS trust-all (ArcaTlsContextFactory)¶

ArcaTlsContextFactory.build(...) arma el SSLContext TLS 1.2 directo (en JDK 17+ el TLS 1.2/1.3 es nativo, no hace falta nginx). Acepta keystore cliente (mutual-TLS opcional), truststore (o el default del JDK) y un flag insecureTrustAll.

Excepciones AFIP (paquete exceptions)¶

Estas excepciones son de dominio (las usa la capa de servicio / endpoints SOAP), distintas de las excepciones que lanzan los clientes raw-SOAP (IllegalStateException / WsfeFault).

WsfeFault (paquete wsfe) es aparte: un RuntimeException con el code del primer <Err> de AFIP, para que el llamador reaccione por código (p.ej. 602).

Por dónde seguir¶

• API SOAP — los 3 endpoints SOAP que este backend expone.
• El ciclo de facturación — cuándo se usa CAE vs CAEA.
• Invariantes — reglas que no se pueden romper (firma SHA-1, TLS, orden XSD).