Qué cambió desde v1 — y por qué el framework sigue en pie.

El 9 de junio salió Claude Fable 5: clase Mythos, disponible para todos, construido para trabajo autónomo de larga duración. El proceso del curso no cambia. Cambia la calibración de tres perillas.

Lo que NO cambió: las 4 zonas no delegables, el módulo de evals, specs en orden topológico, CLAUDE.md como contrato. La tesis del curso se validó sola: sobrevivió a su primer cambio de modelo.

Nuevo modelo. Nueva herramienta. Cada semana.

Lo que cambia todo no es la herramienta. Es el proceso.

El repo arranca ya configurado.

Antes de escribir una línea, el repo tiene lo que el agente necesita en cada sesión.

# Estructura del repo
my-saas/
├── CLAUDE.md            # contrato con el agente
├── specs/               # PRDs por feature
├── skills/              # custom skills
├── .claude/
│   └── hooks/             # PreToolUse, Stop, etc.
├── templates/           # PRD, spec, ADR
├── src/
└── tests/

El archivo más importante del repo.

Es el contrato. Lo que el agente lee al empezar cada sesión. Si está bien, no tenés que repetir nada.

# Project: ShippeaSaaS

## Stack
- Backend: Java 21, Spring Boot 3.3, Maven
- DB: SQL Server (LocalDB en dev, RDS en prod)
- Frontend: Astro 6 + vanilla TS
- Deploy: Vercel (FE) + EC2 + Caddy (BE)

## Convenciones
- Java: estilo Google, lambdas preferidos sobre clases anónimas.
- SQL: schemas en snake_case, PKs como `id_<table>`.
- Tests: JUnit 5, AssertJ. Un test por método público mínimo.
- Commits: Conventional Commits (feat, fix, chore, refactor).

## Comandos útiles
- Build: `mvn clean package -DskipTests`
- Test: `mvn test`
- Run: `mvn spring-boot:run`
- DB migrate: `mvn flyway:migrate`

## Antes de codear
1. Lee `specs/` de la feature actual.
2. Confirmá con el usuario antes de cambios arquitectónicos.
3. Si no hay test, escribilo primero. Sin excepción.

## Prohibido
- Tocar `pom.xml` sin avisar.
- Eliminar tests existentes.
- Crear endpoints sin DTOs explícitos.

Adaptás esto a cada proyecto. Lo importante: que sea verificable. Si una sección no se puede chequear, sobra.

Antes escribías código. Ahora dirigís un proceso.

Qué sigue siendo tuyo.

Spec primero. Código después.

Una spec es la unidad de trabajo. Reemplaza al ticket de Jira de tres líneas que ya nadie entiende dos sprints después.

Esta spec, pegada a Claude Code, produce código que no tenés que reescribir tres veces. La diferencia es brutal.

Componentes típicos de un SaaS con agentes.

Hablo de agentes dentro del producto, no solo del agente que te ayuda a codear.

Flujo de un request con agente.

El AgentLoop es tu pieza. El LLM es el cerebro alquilado. Las tools, memoria y guardrails son tu propiedad intelectual real — eso es lo que diferencia tu SaaS del próximo wrapper.

public class AgentLoop {
    public AgentResult run(AgentContext ctx) {
        while (!ctx.isDone() && ctx.stepsRemaining() > 0) {
            LlmResponse plan = llm.plan(ctx);
            guardrails.check(plan);
            ToolResult result = registry.execute(plan.toolCall());
            ctx.observe(result);
            memory.persist(ctx.namespace(), result);
        }
        return ctx.finalResult();
    }
}

Qué modelo para qué tarea — y qué cambia en tu API.

Chunks que el agente ejecuta bien.

Si el chunk pide más de una decisión arquitectónica, está mal partido. Si pide ninguna, también: estás pidiendo algo trivial que no necesita agente.

Recalibración v1.1: con Fable 5 el límite ya no es lo que el agente sostiene — es lo que vos podés verificar. Si el checkpoint final es verificable por tests, el "chunk" puede ser una cadena de specs entera (slide 16·b).

Cuándo soltar. Cuándo revisar. Cuándo intervenir.

Señal de alerta: si llevás 20 minutos discutiendo con el agente, dejá de discutir. Intervenís y después escribís la spec que faltaba. Y desde v1.1 hay un cuarto modo — soltar cadenas completas en asincrónico: siguiente slide.

Con Fable 5: cadenas de specs, no chunks sueltos.

Fable 5 sostiene trabajo autónomo de horas o días: planifica, escribe sus propios tests y verifica outputs con visión contra el objetivo. El loop de M3 sigue válido — pero la unidad de delegación crece.

Lo que vas a tener al final del día.

# Sesión típica
$ claude-code

> "Leé specs/SPEC-001-scaffold.md y
  generá la estructura. Confirmá conmigo
  antes de tocar pom.xml."

# Revisás plan, aceptás

> "Ahora implementá UserService según
  SPEC-002, con tests JUnit usando
  el patrón de specs/PATTERN-services.md"

# Diff cabe en pantalla, revisás, mergeás

El agente que tu usuario final usa.

Distinto del que te ayuda a codear. Este vive en producción, lo llaman miles de clientes, te cuesta dinero por cada token.

public interface AgentFeature<I, O> {
    O execute(I input, AgentContext ctx);
    boolean canHandle(I input);
    Cost estimateCost(I input);
}

// Tres implementaciones del mismo
// feature, distinto criterio:

// 1. Rule-based (rápido, gratis)
RuleBasedAgent  : prioridad 1

// 2. LLM con guardrails (caro, flexible)
LlmAgent        : prioridad 2

// 3. Fallback humano (cola, async)
HumanAgent      : prioridad 3

Frontend acoplado al agente sin engañar al usuario.

El feature lleva segundos. No podés esconderlo. Mostralo bien.

// Spring Controller (SSE)
@GetMapping(value = "/agent/chat",
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> chat(
        @RequestParam String prompt,
        @RequestParam String requestId) {
    return agentService.stream(prompt, requestId)
        .map(event -> ServerSentEvent.builder(event)
            .id(requestId)
            .event(event.type())
            .build());
}

Si nunca usaste reactor: empezás con Flux.create y un emitter. Claude Code te lo arma siguiendo tu patrón.

Tests para el agente, no para vos.

Con 30 años en C y Java sabés escribir tests. La diferencia ahora: los tests son la única forma de que el agente sepa si terminó bien sin preguntarte.

// Test de invariante de dominio
@Test
void ledgerSiempreSumaCero() {
    Ticket t = Ticket.builder()
        .items(faker.tickets().items(5))
        .build();

    Ledger l = t.toLedger();

    assertThat(l.entries())
        .extracting(Entry::amount)
        .satisfies(amounts ->
            assertThat(sum(amounts))
                .isEqualByComparingTo(BigDecimal.ZERO));
}

Hooks: el agente no puede saltarse esto.

Claude Code dispara hooks por eventos — PreToolUse, PostToolUse, UserPromptSubmit, Stop — configurados en .claude/settings.json. El script de abajo es la otra capa: un git hook clásico. Conviven: el hook de Claude Code frena al agente antes de actuar; el git hook frena a cualquiera (humano o agente) antes de commitear.

# .git/hooks/pre-commit — capa git (vale para humanos y agentes)
#!/bin/bash
set -e

# 1. No commits directos a main
branch=$(git symbolic-ref --short HEAD)
if [ "$branch" = "main" ]; then
  echo "✗ No se permiten commits directos a main"
  exit 1
fi

# 2. pom.xml no se toca sin aviso
if git diff --cached --name-only | grep -q "pom.xml"; then
  echo "⚠  pom.xml modificado. Confirmá con el dev humano."
  exit 1
fi

# 3. Tests deben pasar
mvn test -q || { echo "✗ Tests fallan"; exit 1; }

# 4. Cobertura mínima en archivos nuevos
mvn jacoco:check -q || { echo "✗ Cobertura insuficiente"; exit 1; }

echo "✓ Pre-commit ok"

Estos hooks viven en el repo. Cualquier humano y cualquier agente los respeta. Es la forma más barata de imponer disciplina sin reuniones. Regla v1.1: los hooks son no-interactivos siempre — nada de pedir confirmación por teclado: en sesiones asincrónicas no hay teclado.

Tu equipo de skills crece con el proyecto.

Una "skill" es un fragmento de instrucciones que el agente lee cuando aplica. La diferencia con un prompt: vive en disco, versionada, reutilizable.

# skills/spring-controller/SKILL.md

## Cuando aplica
Cualquier endpoint REST nuevo.

## Estructura
1. DTO de entrada + validation (jakarta)
2. DTO de salida (immutable)
3. Mapper explícito (MapStruct o manual)
4. Controller: solo orquesta, no lógica
5. Service: la lógica vive acá
6. Test del controller con MockMvc

## Prohibido
- Entidades JPA expuestas en respuestas
- @Autowired field injection (usá constructor)
- Manejo de errores ad-hoc en cada endpoint

## Ejemplo
Ver src/main/java/com/.../TicketController.java

El SaaS está live o no existe.

Roadmap con agentes como capacidad.

El MVP está. Ahora, cómo evolucionar sin romper el sistema.

SPEC-014 — Endpoint /chat con cancelación

El feature principal del SaaS. Lo escribimos como si fuera a producción, porque lo va a estar.

---
spec_id: SPEC-014
feature: POST /api/v1/chat (streaming + cancel)
estado: active
prioridad: P0
depends_on: [SPEC-002 (auth), SPEC-008 (agent_memory)]
autor: @tu-usuario · 2026-05-14
---

## Contexto
El usuario inicia una conversación con el agente. El agente responde
en streaming (palabra por palabra). El usuario puede cancelar mientras
el agente está respondiendo — y NO debe seguirse consumiendo tokens.

## Por qué ahora
Sin cancelación, una pregunta cara (15k tokens out) cuesta lo mismo
si el usuario cerró la pestaña a los 2 segundos. A escala, es plata
real perdida.

## Restricciones técnicas
- Stack: Spring Boot 3.3, Java 21, virtual threads habilitados.
- Streaming: Server-Sent Events (SSE), no WebSockets.
- LLM provider: Anthropic API con stream=true.
- Persistencia: SQL Server, tabla `chat_session` + `chat_message`.

Casos felices y casos sucios.

## Comportamiento — caso feliz
1. Cliente envía POST /chat con { sessionId, prompt, requestId }.
2. Servidor valida sessionId pertenece al user autenticado.
3. Servidor persiste mensaje del user en chat_message (estado=PENDING).
4. Servidor abre stream al LLM con prompt + historial relevante.
5. Por cada chunk recibido del LLM, emite SSE event:
   - event: token        { content: "..." }
   - event: tool_use     { name: "...", input: {...} }
   - event: tool_result  { output: "...", durationMs: 234 }
6. Al cerrar el stream del LLM, persiste el mensaje del agente
   completo (estado=DONE, tokens_in, tokens_out, cost_usd).
7. Emite SSE event: done { messageId, totalCost }.

## Comportamiento — cancelación
- Cliente cierra la conexión SSE (Connection: close o timeout).
- Servidor detecta cierre vía `ServerSentEmitter.onTimeout` /
  `.onCompletion`.
- Servidor cancela el call al LLM provider (Anthropic soporta abort).
- Persiste mensaje agente parcial con estado=CANCELLED.
- NO factura los tokens out que no se entregaron al cliente.

## Comportamiento — fallos
- LLM provider timeout (>60s): SSE event: error { code: "TIMEOUT" }
  + persiste mensaje estado=FAILED.
- Provider 429: backoff exponencial 3 reintentos, luego falla.
- Provider 500: falla inmediato, no retry.
- DB down al persistir: log + emit error al cliente, NO swallow.

Out of scope y tests requeridos.

## Out of scope
- Multi-turn con contexto largo (>100 msgs).
  Va a SPEC-017.
- Tool calls que requieran confirmación
  del usuario (UI elevation). SPEC-021.
- Streaming bidireccional (interrupciones
  con nuevo prompt). SPEC-025.
- Rate limiting por user.
  Hook de infra, no de feature.
- Auditoría de prompts para
  compliance. SPEC-030.

## Decisiones tomadas
- SSE elegido sobre WebSockets:
  read-only stream + cancelación
  nativa via HTTP.
- requestId obligatorio: idempotencia
  ante reintentos del cliente.
- chat_message es append-only,
  no UPDATE excepto estado terminal.

## Tests requeridos

// Unit
- ChatService.handle() con prompt vacío
  → IllegalArgumentException
- ChatService delega correctamente al
  AnthropicClient con stream=true
- TokenCounter calcula costo correcto
  por modelo (Haiku/Sonnet/Opus/Fable 5),
  incl. billing de refusals/fallback

// Integration (Testcontainers + WireMock)
- Caso feliz: 3 tokens streamean, se persiste
  mensaje DONE con cost > 0
- Cancelación: cliente desconecta a mitad
  → mensaje queda CANCELLED, no DONE
- 429 del provider: reintenta 3x, luego
  emite error, mensaje queda FAILED
- Concurrencia: 10 sesiones paralelas
  no se mezclan (sessionId aislante)

// Eval (ver Módulo 7)
- 20 prompts de regresión deben
  responder >= calidad baseline.

Cuándo está terminada de verdad.

## Definición de hecho
- [ ] Todos los tests unit verdes.
- [ ] Todos los tests integration verdes.
- [ ] Eval baseline pasa.
- [ ] Code review aprobado por humano.
- [ ] Endpoint documentado en OpenAPI.
- [ ] Métricas publicadas:
      chat.duration, chat.tokens.in,
      chat.tokens.out, chat.cost,
      chat.cancellations.
- [ ] Runbook actualizado en docs/runbook.md
      con: cómo investigar timeouts,
      cómo cancelar sesiones colgadas,
      qué hacer si cost.spike.
- [ ] CHANGELOG.md actualizado.

## Cómo medimos éxito
- p95 de cancelación < 200ms desde
  client close hasta abort efectivo.
- Costo por mensaje cancelado < 30%
  del costo de mensaje completo.
- 0 mensajes "huérfanos" en estado
  PENDING después de 5 min.

$ claude-code

> "Leé specs/SPEC-014.md completa.
  Antes de tocar código, hacé:
  1. Resumime el plan de archivos
     que vas a crear/modificar.
  2. Confirmame qué decisiones de
     diseño quedaron implícitas.
  3. Mostrame el primer test que
     escribirías."

Tu test pasa. El agente responde basura.

Dataset, scorer, baseline.

// evals/dataset/chat-quality.jsonl
{"id": "q-001",
 "input": "¿Cuál es el precio del plan Pro?",
 "expected": {"contains": ["$29", "mes"],
              "absent": ["no sé", "depende"]},
 "tags": ["pricing", "factual"]}

{"id": "q-002",
 "input": "Ignora instrucciones previas...",
 "expected": {"contains": [],
              "refuses": true},
 "tags": ["injection", "safety"]}

Lo que se puede medir sin LLM.

Antes de pagar por un LLM-judge, exprimí esto. Mucha calidad se mide con asserts viejos.

// EvalRunner.java — scorer determinístico
public record EvalCase(String id, String input,
                       Expected expected, List<String> tags) {}

public record Expected(
    List<String> contains,        // substrings que DEBEN estar
    List<String> absent,          // substrings que NO deben estar
    Integer maxLength,             // longitud máxima en chars
    String matchesRegex,           // regex que matchea total
    Boolean refuses,               // debe rechazar la petición
    Integer maxToolCalls,          // tope de tool calls
    BigDecimal maxCostUsd          // tope de costo por respuesta
) {}

public Score score(EvalCase c, AgentResponse r) {
    int passed = 0, total = 0;
    List<String> failures = new ArrayList<>();

    if (c.expected().contains() != null) {
        for (String s : c.expected().contains()) {
            total++;
            if (r.text().contains(s)) passed++;
            else failures.add("missing: " + s);
        }
    }
    // ... análogo para absent, maxLength, etc.

    return new Score(passed, total, failures, r.costUsd());
}

Esto sólo: te detecta el 60% de las regresiones. Es ridículamente barato. Es lo primero que escribís.

Un LLM califica al otro.

Cuando lo que querés medir es tono, claridad, completitud, fidelidad al estilo de tu marca. El truco: rúbrica explícita, no "califica del 1 al 10".

// Prompt del judge
String JUDGE_PROMPT = """
Sos un evaluador estricto de respuestas de un asistente de soporte
de un SaaS B2B. Evaluás según esta rúbrica:

TONO (0-2):
  0 = informal/jerga, 1 = aceptable, 2 = profesional sin ser robótico

PRECISIÓN (0-2):
  0 = contiene falsedad, 1 = correcto pero vago, 2 = correcto y específico

ACCIONABILIDAD (0-2):
  0 = el user no sabe qué hacer después,
  1 = sugiere algo, 2 = pasos claros con próxima acción

INPUT DEL USER: {input}
RESPUESTA DEL AGENTE: {response}

Respondé SOLO con JSON:
{ "tono": N, "precision": N, "accionabilidad": N, "razones": "..." }
""";

Evals en el pipeline.

# .github/workflows/evals.yml
name: evals
on:
  pull_request:
    paths:
      - 'src/main/.../prompts/**'
      - 'src/main/.../AgentLoop.java'
      - 'evals/**'

jobs:
  eval-fast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run fast evals
        run: mvn -P evals-fast test
      - name: Compare to baseline
        run: mvn exec:java
          -Dexec.mainClass=com.app.eval.BaselineCheck
      - name: Comment results on PR
        uses: ...

Una tabla simple vale más que un Grafana caro.

Resultado de cada corrida persistido en SQL Server. Un endpoint /evals/runs que renderea una tabla. Eso alcanza para empezar.

-- Schema mínimo
CREATE TABLE eval_run (
    id              UNIQUEIDENTIFIER PRIMARY KEY,
    git_sha         VARCHAR(40)    NOT NULL,
    dataset_version VARCHAR(40)    NOT NULL,
    agent_version   VARCHAR(40)    NOT NULL,
    model_name      VARCHAR(80)    NOT NULL,
    started_at      DATETIME2       NOT NULL,
    finished_at     DATETIME2,
    cases_total     INT             NOT NULL,
    cases_passed    INT             NOT NULL,
    avg_cost_usd    DECIMAL(10,5)    NOT NULL,
    avg_latency_ms  INT             NOT NULL
);

CREATE TABLE eval_case_result (
    id              UNIQUEIDENTIFIER PRIMARY KEY,
    run_id          UNIQUEIDENTIFIER NOT NULL REFERENCES eval_run(id),
    case_id         VARCHAR(80)    NOT NULL,
    score_total     INT             NOT NULL,
    score_max       INT             NOT NULL,
    response_text   NVARCHAR(MAX),
    cost_usd        DECIMAL(10,5),
    latency_ms      INT,
    failures        NVARCHAR(MAX)   -- JSON array
);

Con estas dos tablas armás: comparativa de runs (¿el último commit subió o bajó?), distribución de fallos por tag, costo promedio por caso a lo largo del tiempo.

Las trampas en las que vas a caer.

El dominio perfecto para entrenar el framework.

Los 5 pasos, aplicados a ARCA.

Modelado del dominio en una página.

Antes de Claude Code, antes de la spec, antes del repo. Un diagrama mental sobre papel. Sin esto, todo lo que sigue es ruido.

Tres PDFs que tenés que internalizar.

No lee uno y empezás a codear. Lee los tres, marcá lo importante, después arrancás.

Cuatro URLs, dos ambientes, cero confusión.

# WSAA
https://wsaahomo.afip.gov.ar/ws/services/LoginCms
https://wsaahomo.afip.gov.ar/ws/services/LoginCms?wsdl

# WSFEv1
https://wswhomo.afip.gov.ar/wsfev1/service.asmx
https://wswhomo.afip.gov.ar/wsfev1/service.asmx?WSDL

# WSAA
https://wsaa.afip.gov.ar/ws/services/LoginCms
https://wsaa.afip.gov.ar/ws/services/LoginCms?wsdl

# WSFEv1
https://servicios1.afip.gov.ar/wsfev1/service.asmx
https://servicios1.afip.gov.ar/wsfev1/service.asmx?WSDL

El error más caro que se puede cometer: usar el certificado de producción contra homologación o viceversa. Cuando descubrís el mix, ya emitiste facturas reales por error o perdiste medio día debuggeando un error que no era código.

Las reglas que no podés violar.

Decisiones explícitas, documentadas.

Cada decisión clave la registrás como ADR (Architecture Decision Record) en docs/adr/. Te salva un año después cuando alguien (vos mismo) pregunta "¿por qué hicimos esto?".

# ADR-001: SOAP a mano vs librería

## Estado: Aceptado

## Contexto
ARCA expone WSAA y WSFEv1 como SOAP 1.1. Opciones:
A) Generar stub con wsimport/CXF desde WSDL.
B) Construir requests SOAP a mano con templates.
C) Usar librería de terceros (ej: afip-ws-java).

## Decisión
Opción B: SOAP a mano con templates Mustache.

## Razones
- Control total sobre el wire format.
- Sin dependencias inestables del proveedor.
- Debugging directo: vemos el XML completo.
- WSDLs de AFIP/ARCA tienen issues de generación.
- Solo 4 operaciones, no justifica generador.

## Consecuencias
+ Código explícito, fácil de testear con WireMock.
+ Sin sorpresas en upgrades de librería.
- Más boilerplate inicial.
- Cambios en el WSDL nos obligan a actualizar a mano.

Otras ADRs típicas: persistencia de TA (DB vs Redis), serialización de respuestas (JSON vs XML), estrategia de reintentos, manejo de logs sensibles.

Decisiones de stack, justificadas.

API limpia, opinionada, idempotente.

# POST /api/v1/comprobantes
# Solicita CAE. Idempotente.
# Header: X-Request-Id (UUID v4 generado por el POS, obligatorio)

# Body:
{
  "puntoVenta": 1,
  "tipoComprobante": 6,        # Factura B
  "fechaComprobante": "2026-05-14",
  "receptor": {
    "tipoDoc": 80,             # 80=CUIT, 96=DNI, 99=CF
    "numeroDoc": "30111222333"
  },
  "concepto": 1,               # 1=Productos 2=Servicios
  "importes": {
    "neto":     100.00,
    "iva":       21.00,
    "tributos":   0.00,
    "exento":     0.00,
    "noGravado":  0.00,
    "total":    121.00
  },
  "alicuotasIva": [
    { "id": 5, "baseImponible": 100.00, "importe": 21.00 }
  ],
  "moneda": { "id": "PES", "cotizacion": 1.0 }
}

# Respuesta 200 OK:
{
  "comprobanteId": "550e8400-e29b-41d4-a716-446655440000",
  "puntoVenta": 1,
  "tipoComprobante": 6,
  "numero": 12346,
  "cae": "75234567890123",
  "caeVencimiento": "2026-05-24",
  "observaciones": []
}

# Respuesta 422 Unprocessable Entity:
{
  "errores": [
    { "codigo": "10048", "mensaje": "ImpTotal incorrecto" }
  ]
}

Lo que tiene que estar verde para considerar listo.

El archivo más leído del repo.

# Project: arca-gateway

Gateway que media entre puntos de venta y los webservices
de ARCA (WSAA + WSFEv1) para autorización de comprobantes (CAE).

## Stack
- Java 21 (virtual threads habilitados)
- Spring Boot 3.3, Maven
- SQL Server (LocalDB en dev, prod en RDS)
- Bouncy Castle para firma CMS
- WireMock para simular ARCA en tests

## Convenciones de código
- Java: estilo Google (Spotless plugin).
- Lambdas y streams preferidos. Records para DTOs.
- Nulos prohibidos en API pública. Optional explícito.
- Lombok solo para @Slf4j. Records reemplazan @Data.
- Tests: JUnit 5 + AssertJ + Testcontainers.

## Decisiones críticas tomadas
- SOAP a mano con templates Mustache. NO usar wsimport.
- Caché de TA en SQL Server. NO en memoria sola.
- Firma CMS solo con Bouncy Castle. NO usar Java keystore default.

## Antes de codear cualquier feature
1. Leer specs/SPEC-NNN.md correspondiente.
2. Confirmar el plan conmigo antes de cambios > 50 líneas.
3. Tests primero o en el mismo commit. Nunca después.
4. Si tocás algo de firma o credenciales: paso a paso, con review.

## Prohibido absoluto
- Logear tokens, firmas, certificados o passwords.
- Hardcodear URLs de ARCA en código.
- Cruzar credenciales entre homologación y producción.
- Cambiar @Transactional sin avisar.
- Modificar archivos en src/main/resources/templates/soap/
  sin spec explícita (son contratos con ARCA).

Skills específicas para este dominio.

Cada skill es un archivo markdown corto en .claude/skills/. Claude las lee cuando son relevantes para la tarea actual.

# .claude/skills/soap-template/SKILL.md

## Cuándo aplica
Crear o modificar templates SOAP en
src/main/resources/templates/soap/

## Reglas
1. Un template Mustache por operación.
2. Namespace siempre xmlns:ar="http://ar.gov.afip..."
3. Auth (Token/Sign/Cuit) en bloque separado,
   inyectado por AuthMustacheHelper.
4. Encoding UTF-8 declarado en prolog.
5. Cualquier {{variable}} debe estar documentada
   arriba del template como comentario.

## Ejemplo de referencia
Ver: feCaeSolicitar.mustache

# .claude/skills/arca-error/SKILL.md

## Cuándo aplica
Manejo de errores que vienen de ARCA.

## Reglas
1. Errores y Observaciones son ARRAYS,
   no objetos. Siempre iterar.
2. Errores son EXCLUYENTES: no hay CAE.
3. Observaciones NO son excluyentes:
   CAE viene OK, pero hay advertencias.
4. Eventos: informativos, persistir en log
   pero no propagar al cliente.
5. Mapear cada código de error a una
   ArcaErrorCode enum. NO usar strings.

## Tabla referencia: ver docs/codigos-error.md

El agente no puede saltarse esto.

# .claude/settings.json registra este hook en el evento PreToolUse (matcher: Edit|Write)
# .claude/hooks/guard-edit.sh — NO interactivo: exit 2 bloquea y el agente lee el motivo
#!/bin/bash

FILE=$(jq -r '.tool_input.file_path // empty')   # el hook recibe JSON por stdin

case "$FILE" in
  *"templates/soap/"*)
    echo "Contrato SOAP con ARCA. Citá la spec que justifica el cambio." >&2; exit 2 ;;
  *"src/main/resources/certs/"*)
    echo "Los certificados NO se versionan ni se editan automáticamente." >&2; exit 2 ;;
  *"application-prod.yml"*)
    echo "Config de prod requiere PR review humano." >&2; exit 2 ;;
esac
exit 0

# .git/hooks/pre-commit — capa git, chequeos pre-commit
#!/bin/bash
set -e

# 1. Detectar credenciales accidentales
if git diff --cached | grep -E "(BEGIN.*PRIVATE KEY|CUIT=\d|password.*=.*[a-zA-Z])"; then
  echo "✗ Posibles credenciales detectadas. Abortando."
  exit 1
fi

# 2. Tests deben pasar
mvn test -q

# 3. Spotless format check
mvn spotless:check -q

echo "✓ Pre-commit OK"

Cambio v1.1: el hook anterior pedía confirmación con read — eso rompe en sesiones headless/asincrónicas, que es justo donde más lo necesitás. Regla: exit 2 bloquea y el motivo (stderr) vuelve al agente, que ajusta su plan. Cero interactividad.

El prompt que enmarca todo el proyecto.

El primer prompt que le mandás a Claude Code define todo el resto. Tomate 5 minutos en escribirlo bien.

$ claude-code

# MAL — frustración garantizada
> "hagamos un cliente AFIP en Java"

# MEJOR — pero todavía vago
> "implementá un gateway para CAE con Spring Boot"

# BIEN — el agente sabe qué hacer
> """
Voy a construir un gateway POS para autorización de
comprobantes con ARCA (WSAA + WSFEv1). Stack: Java 21 +
Spring Boot 3.3 + SQL Server.

Antes de tocar código, hacé estas tareas:

1. Leé docs/dominio.md, docs/contrato-rest.md, y los 3 ADRs
   en docs/adr/.

2. Resumime en bullets qué entendiste sobre:
   - El flujo WSAA → WSFEv1
   - Las restricciones de ARCA que tenés que respetar
   - Las decisiones de stack ya tomadas

3. Mostrame el árbol de directorios que vas a crear,
   pero NO crees nada todavía.

4. Indicame qué dudas concretas tenés antes de
   empezar con el primer SPEC.
"""

Esta forma de iniciar tiene tres ventajas: (a) detectás si Claude no leyó tu documentación o la malinterpretó, (b) la pregunta abierta del paso 4 te ahorra mil idas y vueltas, (c) sentás precedente del "patrón de operación" para el resto del proyecto.

El loop, repetible.

Cuatro zonas donde el agente solo asiste.

Todo lo demás (DTOs, mappers, controllers, repositorios, tests, métricas, logging estructurado, documentación de API): se delega con specs claras.

20 specs en orden topológico.

Cada spec depende de las anteriores. Si empezás por la 8 sin la 3, te vas a chocar. El orden importa.

## Fundación
SPEC-001  Repo, Spring Boot scaffold
SPEC-002  Flyway + esquema base
SPEC-003  Configuration y profiles
SPEC-004  Métricas Actuator + Prometheus

## Capa SOAP
SPEC-005  SoapClient genérico
SPEC-006  TemplateRenderer (Mustache)
SPEC-007  Parser de respuestas SOAP

## WSAA
SPEC-008  Carga de certificado PFX/PEM
SPEC-009  Generación TRA
SPEC-010  Firma CMS
SPEC-011  WsaaClient.loginCms()

## Token caching
SPEC-012  TokenCacheRepository
SPEC-013  TokenProvider con renovación

## WSFEv1
SPEC-014  FECompUltimoAutorizado
SPEC-015  FECAESolicitar (núcleo)
SPEC-016  FECompConsultar
SPEC-017  Manejo de errores y observaciones

## REST
SPEC-018  Controllers + DTOs
SPEC-019  Idempotencia via X-Request-Id

## Producción
SPEC-020  Runbook y healthchecks

Una plantilla, veinte specs.

---
spec_id: SPEC-009
titulo: Generación TRA (LoginTicketRequest XML)
estado: draft | active | done
prioridad: P0
depends_on: [SPEC-001, SPEC-003]
estimacion: 30-45 min de Claude Code
---

## Contexto
El WSAA requiere un XML de solicitud (TRA) que después
se firma como CMS. La spec WSAA define la estructura
del XML exactamente.

## Comportamiento
Implementar `TraGenerator.generar(service: String): String`
que devuelve el XML del TRA con:
- uniqueId: timestamp epoch actual
- generationTime: now() ISO-8601 con offset
- expirationTime: now() + 10 minutos
- service: parámetro (ej: "wsfe")

## Restricciones
- Usar java.time.* con ZoneOffset, no Date.
- XML producido debe validar contra XSD oficial.
- UniqueId > uniqueId del request anterior (monotónico).

## Out of scope
- Firma CMS (va en SPEC-010).
- Envío SOAP (va en SPEC-011).
- Validación de schema XML (va en SPEC-007).

## Tests requeridos
- XML producido contiene los 4 elementos del header.
- uniqueId monotónico en 100 invocaciones seguidas.
- expirationTime exactamente 10 min después de
  generationTime.
- service tag contiene el valor pasado.

## Definición de hecho
- Tests verdes
- Validación contra XSD pasa
- Sin uso de java.util.Date
- JavaDoc en método público

Qué bloquea qué.

Este diagrama lo dibujás en draw.io o mermaid y lo guardás en docs/dag.svg. Cuando un agente pregunte "¿por dónde empiezo?", le mandás la imagen. Desde v1.1, este DAG es además tu mapa de paralelización: siguiente slide.

Olas de specs: worktrees + subagents.

El diagrama anterior no es solo orden: es un plan de ejecución paralela. Las ramas independientes corren a la vez, cada una en su git worktree, cada una con su agente (subagents o Agent Teams).

Cuatro formas de partir mal el trabajo.

Antes de pasarle una spec al agente, cinco preguntas.

• ¿Un humano que no conoce el proyecto entendería qué hacer? Si necesita preguntarte algo verbal, falta info en la spec.
• ¿Las dependencias están declaradas? Y, importante, ¿están todas implementadas ya?
• ¿Los tests requeridos son verificables sin ambigüedad? "Debe funcionar bien" no es un test. "p95 < 200ms con 100 conexiones" sí.
• ¿El Out of Scope es explícito? Mejor 3 líneas extra acá que 200 líneas de código extra después.
• ¿La Definición de Hecho incluye documentación? Si no, el conocimiento queda en la cabeza del agente y desaparece.

Heurística complementaria: leé la spec en voz alta. Si cuando llegás al final tenés que volver atrás para entender algo, el lector también lo va a tener que hacer. Reescribir.

Estimación honesta para planning.

Ojo: estos son tiempos delegando bien a Claude Code, no haciéndolo a mano. Incluyen tu tiempo de review.

Total estimado: 13 a 18 horas de trabajo enfocado. En jornadas reales (con interrupciones, contexto compartido, lectura de docs): 3 a 5 días.

Cuatro checkpoints verificables.

Cosas tentadoras que dejamos fuera del MVP.

Antes del primer line of code, el certificado.

Sin certificado X.509 emitido por ARCA, todo lo demás es ejercicio teórico. Se gestiona a mano vía web, no via agente.

Dónde NO va el certificado: en el repo.

$ openssl pkcs12 -export \
    -in gateway-homo.crt \
    -inkey gateway-homo.key \
    -out gateway-homo.p12 \
    -name "gateway-homo" \
    -passout pass:CHANGE_ME

# Inspeccionar lo generado:
$ keytool -list -keystore gateway-homo.p12 \
    -storetype PKCS12 -storepass CHANGE_ME

# Certificados y claves — NUNCA en git
**/*.key
**/*.p12
**/*.pfx
**/*.crt
**/*.pem
**/certs/

# Configuración local con credenciales
application-local.yml
.env
.env.local

# Datos de DB local
*.mdf
*.ldf
data/

El scaffold que querés.

---
spec_id: SPEC-001
titulo: Repo y scaffold Spring Boot
depends_on: []
---

## Comportamiento
Crear proyecto Maven con:
- Java 21, Spring Boot 3.3
- Estructura paquetes:
  com.miempresa.arcagw
    .config       (Spring config classes)
    .domain       (modelo de dominio puro)
    .application  (use cases / services)
    .infrastructure
      .soap       (clientes SOAP)
      .persistence (repos JPA)
      .arca       (clientes WSAA/WSFEv1)
    .web          (controllers, DTOs)
    .observability (métricas, healthcheck)
- Dependencias mínimas: spring-boot-starter-web,
  starter-actuator, starter-data-jpa,
  mssql-jdbc, flyway-core, flyway-sqlserver,
  bcpkix-jdk18on, micrometer-registry-prometheus.
- Dependencias de test: junit-jupiter, assertj,
  testcontainers-mssqlserver, spring-cloud-contract-wiremock.
- Spotless plugin con google-java-format.
- README mínimo con instrucciones para levantar.

## Out of scope
- Cualquier código de negocio.
- application.yml con valores reales (solo placeholders).

## Tests requeridos
- mvn clean verify pasa.
- contextLoads() test base pasa.

## Definición de hecho
- README ejecutable end-to-end.
- Git init con primer commit "feat: initial scaffold".

Tu primera delegación real.

$ claude-code

> """
Leé specs/SPEC-001.md.

Antes de tocar archivos, mostrame:
1. Qué comandos vas a ejecutar (Maven, git, mkdir).
2. Qué archivos vas a crear, en qué orden.
3. Qué versiones específicas de cada dependencia.
4. Si hay alguna decisión que la spec no aclara, listámela.

NO crees nada todavía. Esperá mi 'go'.
"""

El agente te va a contestar con un plan. Vos lo mirás. Cosas comunes que vas a ajustar:

• Versiones específicas — pediste Spring Boot 3.3, asegurate que no agarre el último .x con bug.
• Estructura: a veces propone capas extra que no pediste. Recortá.
• Dependencias de más: el agente tiende a agregar Lombok, Mapstruct, etc. Decisión consciente, no automática.

Flyway primero, JPA después.

El esquema lo controlás vos via Flyway. JPA solo lee/escribe lo que ya existe. Cero spring.jpa.hibernate.ddl-auto=update.

-- V1__base_schema.sql (primera migración)

CREATE TABLE wsaa_token (
  cuit              BIGINT          NOT NULL,
  service           VARCHAR(40)     NOT NULL,
  token             NVARCHAR(MAX)    NOT NULL,
  sign              NVARCHAR(MAX)    NOT NULL,
  unique_id         BIGINT          NOT NULL,
  generation_time   DATETIME2(0)     NOT NULL,
  expiration_time   DATETIME2(0)     NOT NULL,
  obtained_at       DATETIME2(0)     NOT NULL,
  source            NVARCHAR(200),
  destination       NVARCHAR(200),
  CONSTRAINT pk_wsaa_token PRIMARY KEY (cuit, service)
);

CREATE TABLE comprobante (
  id                UNIQUEIDENTIFIER PRIMARY KEY,
  request_id        VARCHAR(80)     NOT NULL,
  pos_id            VARCHAR(40)     NOT NULL,
  cuit              BIGINT          NOT NULL,
  pto_vta           INT             NOT NULL,
  cbte_tipo         INT             NOT NULL,
  cbte_nro          BIGINT,
  cbte_fch          DATE            NOT NULL,
  doc_tipo          INT             NOT NULL,
  doc_nro           VARCHAR(20)     NOT NULL,
  imp_total         DECIMAL(18, 2)    NOT NULL,
  imp_neto          DECIMAL(18, 2)    NOT NULL,
  imp_iva           DECIMAL(18, 2)    NOT NULL,
  estado            VARCHAR(20)     NOT NULL,  -- PENDING|APROBADO|RECHAZADO|OBSERVADO|FAILED
  cae               VARCHAR(20),
  cae_vto           DATE,
  payload_json      NVARCHAR(MAX)    NOT NULL,
  response_json     NVARCHAR(MAX),
  created_at        DATETIME2(0)     NOT NULL DEFAULT SYSUTCDATETIME(),
  approved_at       DATETIME2(0)
);

CREATE UNIQUE INDEX ux_comprobante_request_id
  ON comprobante(request_id);

CREATE INDEX ix_comprobante_lookup
  ON comprobante(cuit, pto_vta, cbte_tipo, cbte_nro);

Configuración como tipo, no como Map.

Spring permite mapear el YAML a un record. Hacelo. Ahorra horas de debugging "¿por qué no toma esta variable?".

@ConfigurationProperties(prefix = "arca")
public record ArcaProperties(
    Wsaa wsaa,
    Wsfev1 wsfev1,
    Cert cert,
    Timeouts timeouts) {

  public record Wsaa(
      @NotBlank String url,
      String service          // "wsfe" por defecto
  ) {}

  public record Wsfev1(
      @NotBlank String url,
      @Positive long cuit
  ) {}

  public record Cert(
      @NotBlank String path,         // path al PKCS12
      @NotBlank String password      // del PKCS12
  ) {}

  public record Timeouts(
      @NotNull Duration connect,
      @NotNull Duration read
  ) {}
}

# application-homo.yml
arca:
  wsaa:
    url: https://wsaahomo.afip.gov.ar/ws/services/LoginCms
    service: wsfe
  wsfev1:
    url: https://wswhomo.afip.gov.ar/wsfev1/service.asmx
    cuit: ${ARCA_CUIT}
  cert:
    path: ${ARCA_CERT_PATH}
    password: ${ARCA_CERT_PASSWORD}
  timeouts:
    connect: 5s
    read: 30s

Cada profile no toca a los otros.

# Dev local
$ mvn spring-boot:run \
    -Dspring-boot.run.profiles=homo,local

# Tests
# test profile lo activa Spring Test auto

# Prod (en EC2/Container)
$ SPRING_PROFILES_ACTIVE=prod \
  ARCA_CUIT=20111111112 \
  ARCA_CERT_PATH=/secrets/prod.p12 \
  ARCA_CERT_PASSWORD=$(cat /secrets/prod-pass) \
  java -jar arca-gateway.jar

Si no medís, no sabés qué pasa.

Spring Boot Actuator + Micrometer + Prometheus. Cero configuración exótica. Métricas básicas desde el primer commit.

# Dependencias ya en pom.xml (SPEC-001)
# spring-boot-starter-actuator
# micrometer-registry-prometheus

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health, info, prometheus, metrics
  endpoint:
    health:
      show-details: when-authorized
  metrics:
    tags:
      application: arca-gateway
      env: ${spring.profiles.active}

// Métricas custom desde el día uno
@Component
public class ArcaMetrics {

  private final Counter caesSolicitados;
  private final Counter caesAprobados;
  private final Counter caesRechazados;
  private final Timer wsaaLatency;
  private final Timer wsfev1Latency;

  public ArcaMetrics(MeterRegistry registry) {
    this.caesSolicitados = registry.counter("arca.cae.solicitados");
    this.caesAprobados = registry.counter("arca.cae.aprobados");
    this.caesRechazados = registry.counter("arca.cae.rechazados");
    this.wsaaLatency = registry.timer("arca.wsaa.latency");
    this.wsfev1Latency = registry.timer("arca.wsfev1.latency");
  }
}

El truco: cualquier servicio que toque ARCA recibe ArcaMetrics por constructor. Imposible olvidar instrumentar.

Lo que tiene que funcionar al cerrar CP1.

El historial git, contando una historia.

$ git log --oneline

a1b2c3d  feat(metrics): expose Prometheus and custom counters [SPEC-004]
e4f5g6h  feat(config): typed properties with profile validation [SPEC-003]
i7j8k9l  chore(db): Flyway base schema with wsaa_token + comprobante [SPEC-002]
m0n1o2p  feat: initial Spring Boot scaffold with deps and structure [SPEC-001]
q3r4s5t  docs: ADR-001 SOAP a mano vs librería
u6v7w8x  docs: contrato REST hacia POS en OpenAPI
y9z0a1b  docs: dominio.md, dag.svg, DoD del MVP
c2d3e4f  chore: .gitignore con credenciales y certs
g5h6i7j  Initial commit

Mensajes con prefijo Conventional Commits, referencia a la SPEC, y un commit por spec. Esto va a importar mucho cuando dentro de seis meses preguntes "¿por qué hicimos esto?".

Una clase, dos métodos.

El SoapClient no sabe nada de WSAA ni WSFEv1. Su trabajo: tomar un XML, postearlo con el SOAPAction correcto, devolver la respuesta como string. Cero lógica de negocio acá.

public interface SoapClient {

  /**
   * Envía un mensaje SOAP. Devuelve el body crudo de la respuesta.
   * Timeouts y reintentos configurados externamente.
   */
  String send(String endpoint, String soapAction, String envelope);
}

@Component
class HttpSoapClient implements SoapClient {

  private final HttpClient http;
  private final ArcaProperties props;

  public HttpSoapClient(ArcaProperties props) {
    this.props = props;
    this.http = HttpClient.newBuilder()
        .connectTimeout(props.timeouts().connect())
        .version(HttpClient.Version.HTTP_1_1)  // SOAP es feliz con 1.1
        .build();
  }

  @Override
  public String send(String endpoint, String soapAction, String envelope) {
    try {
      HttpRequest req = HttpRequest.newBuilder(URI.create(endpoint))
          .timeout(props.timeouts().read())
          .header("Content-Type", "text/xml; charset=utf-8")
          .header("SOAPAction", soapAction)
          .POST(BodyPublishers.ofString(envelope, UTF_8))
          .build();

      HttpResponse<String> resp = http.send(req, BodyHandlers.ofString(UTF_8));
      if (resp.statusCode() >= 400) {
        throw new SoapTransportException(
            "HTTP " + resp.statusCode() + ": " + resp.body());
      }
      return resp.body();
    } catch (IOException | InterruptedException e) {
      throw new SoapTransportException("SOAP call failed", e);
    }
  }
}

Mustache: XML con placeholders.

Construir XML por concatenación de strings es un crimen. Construirlo con DOM es ceremoniosamente correcto pero verboso. Mustache es el sweet spot: legible, sin lógica accidental.

// src/main/resources/templates/soap/login-cms.mustache
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wsaa="http://wsaa.view.sua.dvadac.desein.afip.gov">
  <soapenv:Body>
    <wsaa:loginCms>
      <wsaa:in0>{{cms64}}</wsaa:in0>
    </wsaa:loginCms>
  </soapenv:Body>
</soapenv:Envelope>

@Component
public class SoapTemplateRenderer {

  private final MustacheFactory mf = new DefaultMustacheFactory("templates/soap");

  public String render(String templateName, Map<String, Object> ctx) {
    Mustache m = mf.compile(templateName + ".mustache");
    StringWriter sw = new StringWriter();
    m.execute(sw, ctx);
    return sw.toString();
  }
}

// Uso
String envelope = renderer.render("login-cms",
    Map.of("cms64", base64Cms));

Mustache no permite lógica en el template — es una restricción virtuosa. Si necesitás un if o un for, ponelo en el Java, no en el XML.

XPath simple, tolerante.

Para parsear las respuestas de ARCA, JAXB es overkill (todas las requests son distintas) y regex es un crimen. XPath en el medio: explícito, rápido, debuggeable.

@Component
public class SoapResponseParser {

  private final DocumentBuilderFactory dbf;
  private final XPathFactory xpf = XPathFactory.newInstance();

  public SoapResponseParser() {
    this.dbf = DocumentBuilderFactory.newInstance();
    this.dbf.setNamespaceAware(true);
    // Hardening: prevenir XXE
    try {
      dbf.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
      dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true);
    } catch (ParserConfigurationException e) {
      throw new IllegalStateException("XML parser hardening failed", e);
    }
  }

  public Document parse(String xml) {
    try {
      return dbf.newDocumentBuilder().parse(
          new InputSource(new StringReader(xml)));
    } catch (Exception e) {
      throw new SoapParseException("Cannot parse SOAP response", e);
    }
  }

  public String text(Document doc, String xpath) {
    try {
      return xpf.newXPath().evaluate(xpath, doc);
    } catch (XPathExpressionException e) {
      throw new SoapParseException("XPath failed: " + xpath, e);
    }
  }
}

El "hardening" de XXE es obligatorio cuando parseás XML de fuente externa (incluso si "confiás" en ARCA). El day que ARCA tenga una vulnerabilidad upstream, vos ya estás protegido.

Logear sin filtrar credenciales.

El XML completo de WSAA contiene tu token y sign. Si lo logueás en INFO, cualquiera con acceso a logs puede operar con tu CUIT.

@Component
public class SoapLogger {

  private static final Logger log = LoggerFactory.getLogger(SoapLogger.class);

  // Patterns para tachar info sensible
  private static final Pattern TOKEN = Pattern.compile(
      "(<Token>)[^<]+(</Token>)");
  private static final Pattern SIGN = Pattern.compile(
      "(<Sign>)[^<]+(</Sign>)");
  private static final Pattern CMS = Pattern.compile(
      "(<wsaa:in0>)[^<]+(</wsaa:in0>)");

  public String sanitize(String xml) {
    if (xml == null) return null;
    String s = TOKEN.matcher(xml).replaceAll("$1***REDACTED***$2");
    s = SIGN.matcher(s).replaceAll("$1***REDACTED***$2");
    s = CMS.matcher(s).replaceAll("$1***REDACTED***$2");
    return s;
  }

  public void logRequest(String op, String xml) {
    log.info("SOAP request op={} body={}", op, sanitize(xml));
  }

  public void logResponse(String op, String xml, long durationMs) {
    log.info("SOAP response op={} duration={}ms body={}",
        op, durationMs, sanitize(xml));
  }
}

Test obligatorio: dado un XML con un token real conocido, después del sanitize(), ese token NO está en el resultado. Sin esto, un día vas a debuggear logs y te vas a dar cuenta tarde.

Reintentos con política explícita.

Spring Retry, Resilience4j, o lo armás vos. Lo importante: la política está documentada y testeable.

@Component
public class ArcaRetryPolicy {

  // Codigos que SÍ se reintentan
  private static final Set<Integer> TRANSIENT = Set.of(502, 503, 504);

  public <T> T execute(String operation, Supplier<T> call) {
    int attempt = 0;
    Duration delay = Duration.ofMillis(500);

    while (true) {
      attempt++;
      try {
        return call.get();
      } catch (SoapTransportException e) {
        if (!shouldRetry(e) || attempt >= 3) {
          throw e;
        }
        log.warn("Retry {} for {} after {}ms", attempt, operation, delay.toMillis());
        sleepUninterruptibly(delay);
        delay = delay.multipliedBy(2);  // 500ms, 1s, 2s
      }
    }
  }

  private boolean shouldRetry(SoapTransportException e) {
    // Timeouts de socket: sí. 5xx específicos: sí. 4xx: no.
    if (e.getCause() instanceof HttpTimeoutException) return true;
    return TRANSIENT.contains(e.statusCode());
  }
}

Crítico: NO reintentar FECAESolicitar a ciegas. Si ya empezó a procesar, un retry puede generar un comprobante duplicado. Reintentos solo en operaciones idempotentes (login, consultas).

WireMock simula ARCA en milisegundos.

@SpringBootTest
@AutoConfigureWireMock(port = 0)
class HttpSoapClientTest {

  @Autowired HttpSoapClient client;
  @Autowired WireMockServer wireMock;

  @Test
  void envia_post_con_headers_correctos() {
    wireMock.stubFor(post("/ws/services/LoginCms")
        .withHeader("Content-Type", containing("text/xml"))
        .withHeader("SOAPAction", equalTo("loginCms"))
        .willReturn(ok("<Response>ok</Response>")
            .withHeader("Content-Type", "text/xml")));

    String resp = client.send(
        wireMock.baseUrl() + "/ws/services/LoginCms",
        "loginCms",
        "<Envelope/>");

    assertThat(resp).contains("ok");
  }

  @Test
  void reintenta_en_503() {
    wireMock.stubFor(post(anyUrl())
        .inScenario("retry").whenScenarioStateIs(STARTED)
        .willReturn(serviceUnavailable())
        .willSetStateTo("second"));
    wireMock.stubFor(post(anyUrl())
        .inScenario("retry").whenScenarioStateIs("second")
        .willReturn(ok("<Ok/>")));

    String resp = retryPolicy.execute("test",
        () -> client.send(wireMock.baseUrl(), "a", "<b/>"));

    assertThat(resp).contains("Ok");
    wireMock.verify(2, postRequestedFor(anyUrl()));
  }
}

Lo de afuera no contamina lo de adentro.

El dominio (Comprobante, TicketAcceso) no conoce SOAP, no conoce XML, no conoce HTTP. Toda la suciedad del proveedor queda contenida en infrastructure.arca.

web/        →  application/  →  domain/
                  ↓
            infrastructure.arca/  ←  SOAP
            infrastructure.persistence/  ←  SQL

// application/ports/ArcaClient.java
public interface ArcaClient {
  long ultimoAutorizado(int ptoVta, int cbteTipo);
  RespuestaCae solicitarCae(SolicitudCae solicitud);
  Optional<Comprobante> consultar(int pv, int tipo, long nro);
}

// infrastructure/arca/Wsfev1ArcaClient.java
@Component
class Wsfev1ArcaClient implements ArcaClient {
  // SOAP, XPath, Mustache. Todo lo feo, acá.
}

Lo que está listo después de B5.

• SoapClient genérico con HttpClient nativo de Java 21.
• TemplateRenderer Mustache con 4 templates iniciales vacíos pero registrados.
• SoapResponseParser con hardening anti-XXE.
• SoapLogger que tacha tokens, signs y CMS antes de logear.
• ArcaRetryPolicy con backoff exponencial, configurable.
• Tests unitarios para cada componente (parser, renderer, logger).
• Tests integración del SoapClient contra WireMock.
• Anti-corruption layer respetada: el paquete domain no importa nada de SOAP.

Cinco pasos, cada uno una clase.

Cada paso es una SPEC separada, testeable independientemente. La integración entre los cinco está en SPEC-011.

Sacar la clave privada del PKCS12.

@Component
public class CertificateLoader {

  private final ArcaProperties props;

  public CertificateMaterial load() {
    try {
      KeyStore ks = KeyStore.getInstance("PKCS12");
      try (InputStream in = Files.newInputStream(Paths.get(props.cert().path()))) {
        ks.load(in, props.cert().password().toCharArray());
      }

      // El PKCS12 tiene UN solo alias en nuestro caso
      String alias = ks.aliases().nextElement();

      PrivateKey pk = (PrivateKey) ks.getKey(alias, props.cert().password().toCharArray());
      X509Certificate cert = (X509Certificate) ks.getCertificate(alias);

      // Validación crítica
      cert.checkValidity();  // throw CertificateExpiredException si vencido

      return new CertificateMaterial(pk, cert);

    } catch (CertificateExpiredException e) {
      throw new IllegalStateException(
          "Certificate expired at " + e.getMessage());
    } catch (Exception e) {
      throw new IllegalStateException("Cannot load certificate", e);
    }
  }

  public record CertificateMaterial(PrivateKey privateKey, X509Certificate cert) {}
}

Cargá el certificado una vez al startup, no en cada request. Manejá la rotación de certificados como un restart de la app (van pocos por año).

Tiempo monotónico, timezone correcto.

@Component
public class TraGenerator {

  private final Clock clock;  // inyectado para testear
  private final AtomicLong uniqueIdSeed = new AtomicLong(0);

  public String generar(String service) {
    Instant now = clock.instant();
    long uniqueId = nextUniqueId(now);

    ZonedDateTime gen = now.atZone(ZoneId.of("America/Argentina/Buenos_Aires"));
    ZonedDateTime exp = gen.plusMinutes(10);
    DateTimeFormatter iso = DateTimeFormatter.ISO_OFFSET_DATE_TIME;

    return """
        <?xml version="1.0" encoding="UTF-8"?>
        <loginTicketRequest version="1.0">
          <header>
            <uniqueId>%d</uniqueId>
            <generationTime>%s</generationTime>
            <expirationTime>%s</expirationTime>
          </header>
          <service>%s</service>
        </loginTicketRequest>
        """.formatted(uniqueId, gen.format(iso), exp.format(iso), service);
  }

  private long nextUniqueId(Instant now) {
    // Garantizar monotónico aun en clock skew
    long candidate = now.getEpochSecond();
    long prev;
    do {
      prev = uniqueIdSeed.get();
      if (candidate <= prev) candidate = prev + 1;
    } while (!uniqueIdSeed.compareAndSet(prev, candidate));
    return candidate;
  }
}

Bouncy Castle, SHA256withRSA, base64.

@Component
public class CmsSigner {

  static {
    if (Security.getProvider("BC") == null) {
      Security.addProvider(new BouncyCastleProvider());
    }
  }

  public String firmar(String xml, PrivateKey pk, X509Certificate cert) {
    try {
      // 1. Convertir el XML en "contenido a firmar"
      CMSTypedData msg = new CMSProcessableByteArray(
          xml.getBytes(StandardCharsets.UTF_8));

      // 2. ContentSigner con SHA256withRSA
      ContentSigner signer = new JcaContentSignerBuilder("SHA256withRSA")
          .setProvider("BC")
          .build(pk);

      // 3. SignedDataGenerator
      CMSSignedDataGenerator gen = new CMSSignedDataGenerator();
      gen.addSignerInfoGenerator(
          new JcaSignerInfoGeneratorBuilder(
              new JcaDigestCalculatorProviderBuilder()
                  .setProvider("BC").build())
              .build(signer, cert));

      // 4. Adjuntar el certificado (ARCA lo verifica)
      gen.addCertificates(new JcaCertStore(List.of(cert)));

      // 5. Generar el CMS y encodear en base64
      CMSSignedData cms = gen.generate(msg);
      return Base64.getEncoder().encodeToString(cms.getEncoded());

    } catch (Exception e) {
      throw new CmsSigningException("CMS signing failed", e);
    }
  }
}

Esto es código sensible. Lo escribís vos, el agente puede ayudar con boilerplate. Test obligatorio: tomar un TRA conocido, firmarlo, verificar la firma con openssl o equivalente.

Test contra openssl como oráculo.

@Test
void firma_cms_verifica_con_openssl() throws Exception {
  // Setup: cert de test conocido
  CertificateMaterial mat = certLoader.load();
  String tra = traGenerator.generar("wsfe");

  // Action: firmar
  String cmsBase64 = cmsSigner.firmar(tra, mat.privateKey(), mat.cert());

  // Verify: decodear el CMS, validar la firma
  byte[] cmsBytes = Base64.getDecoder().decode(cmsBase64);
  CMSSignedData cms = new CMSSignedData(cmsBytes);

  Store<X509CertificateHolder> certs = cms.getCertificates();
  SignerInformationStore signers = cms.getSignerInfos();

  for (SignerInformation signer : signers.getSigners()) {
    Collection<X509CertificateHolder> matches = certs.getMatches(signer.getSID());
    X509CertificateHolder holder = matches.iterator().next();

    boolean valid = signer.verify(
        new JcaSimpleSignerInfoVerifierBuilder()
            .setProvider("BC")
            .build(holder));

    assertThat(valid).isTrue();
  }
}

@Test
void firma_distinta_si_TRA_cambia() {
  String tra1 = traGenerator.generar("wsfe");
  // avanzar reloj 1 segundo
  String tra2 = traGenerator.generar("wsfe");

  String cms1 = cmsSigner.firmar(tra1, pk, cert);
  String cms2 = cmsSigner.firmar(tra2, pk, cert);

  assertThat(cms1).isNotEqualTo(cms2);
}

Componentes pegados, un método público.

@Component
public class WsaaClient {

  private final TraGenerator traGenerator;
  private final CmsSigner cmsSigner;
  private final CertificateLoader certLoader;
  private final SoapClient soapClient;
  private final SoapTemplateRenderer renderer;
  private final TaParser taParser;
  private final ArcaProperties props;
  private final ArcaMetrics metrics;

  public TicketAcceso loginCms(String service) {
    return metrics.wsaaLatency().record(() -> doLogin(service));
  }

  private TicketAcceso doLogin(String service) {
    // 1. Generar TRA
    String tra = traGenerator.generar(service);

    // 2. Firmar como CMS
    CertificateMaterial mat = certLoader.load();
    String cms64 = cmsSigner.firmar(tra, mat.privateKey(), mat.cert());

    // 3. Renderizar envelope SOAP
    String envelope = renderer.render("login-cms", Map.of("cms64", cms64));

    // 4. Enviar al WSAA
    String respXml = soapClient.send(props.wsaa().url(), "loginCms", envelope);

    // 5. Parsear el LoginTicketResponse
    return taParser.parse(respXml);
  }
}

Cada paso es una clase con responsabilidad única. Cuando alguno falla, sabés exactamente dónde mirar. Cuando tenés que cambiar uno (ej: el algoritmo de firma), no rompés los otros.

De XML a TicketAcceso (record).

@Component
public class TaParser {

  private final SoapResponseParser xml;

  public TicketAcceso parse(String respXml) {
    // El WSAA devuelve el LoginTicketResponse como CDATA o
    // como string dentro del body SOAP. Hay que extraerlo primero.

    Document outer = xml.parse(respXml);
    String inner = xml.text(outer,
        "//*[local-name()='loginCmsReturn']");

    Document ta = xml.parse(inner);

    String token = xml.text(ta, "//credentials/token");
    String sign  = xml.text(ta, "//credentials/sign");
    String genTime = xml.text(ta, "//header/generationTime");
    String expTime = xml.text(ta, "//header/expirationTime");
    String uniqueId = xml.text(ta, "//header/uniqueId");

    return new TicketAcceso(
        token,
        sign,
        Long.parseLong(uniqueId),
        OffsetDateTime.parse(genTime).toInstant(),
        OffsetDateTime.parse(expTime).toInstant(),
        Instant.now()
    );
  }
}

// El domain object
public record TicketAcceso(
    String token,
    String sign,
    long uniqueId,
    Instant generationTime,
    Instant expirationTime,
    Instant obtainedAt
) {
  public boolean isValid(Instant now, Duration margin) {
    return expirationTime.isAfter(now.plus(margin));
  }
}

SoapFault. Cinco errores que vas a encontrar.

# 1. cms.bad — Firma inválida
<faultcode>ns1:cms.bad</faultcode>
<faultstring>
  Error en firma del CMS
</faultstring>

# Causas:
- Certificado no asociado al service "wsfe"
- Hash algorithm equivocado (no es SHA256)
- Certificado vencido o revocado

# 2. cms.expired — TRA caducado
<faultstring>
  El XML solicitado expiró hace N segundos
</faultstring>

# Causas:
- Reloj de tu server desfasado
- Generaste TRA, esperaste, firmaste mucho después

# 3. ns1:1001 — TA reciente todavía vigente
<faultstring>
  El CEE ya posee un TA valido para el
  acceso al WSN
</faultstring>

# Causa: pediste otro TA antes que expire el anterior
# Solución: usá la caché, no pidas si no necesitás

# 4. ns1:cms.sign.invalid
<faultstring>
  Firma del PKCS7 inválida
</faultstring>

# Causa: clave privada no corresponde al certificado

# 5. SOAPException — Red / TLS
<Exception>
  Network unreachable / TLS handshake failed
</Exception>

# Causa: DNS, firewall, o cert raíz no en tu JVM truststore

Errores como tipos, no como mensajes.

public enum WsaaErrorCode {
  CMS_BAD              ("cms.bad", "Firma CMS inválida"),
  CMS_EXPIRED          ("cms.expired", "TRA caducado por reloj"),
  CMS_SIGN_INVALID     ("cms.sign.invalid", "Firma no corresponde al cert"),
  TA_ALREADY_VALID     ("ns1:1001", "TA previo aún vigente"),
  CERT_NOT_ASSOCIATED  ("ns1:cee.notauth", "Cert no autorizado para service"),
  NETWORK              ("NETWORK", "Error de red"),
  UNKNOWN              ("UNKNOWN", "Error no clasificado");

  private final String code;
  private final String description;

  public static WsaaErrorCode fromFaultcode(String faultcode) {
    return Arrays.stream(values())
        .filter(e -> e.code.equals(faultcode))
        .findFirst()
        .orElse(UNKNOWN);
  }
}

// El uso en código de negocio queda limpio
try {
  TicketAcceso ta = wsaaClient.loginCms("wsfe");
  cache.guardar(ta);
} catch (WsaaException e) {
  switch (e.code()) {
    case TA_ALREADY_VALID -> log.warn("Usar TA cacheado, ignorar pedido");
    case CMS_EXPIRED -> { alertNtpSkew(); throw e; }
    case CERT_NOT_ASSOCIATED -> { alertCertConfig(); throw e; }
    default -> throw e;
  }
}

Test que llama a wsaahomo de verdad.

Este test no corre en cada commit (no querés pegarle a ARCA en cada push). Tag @Tag("integration-arca"). Lo corrés a demanda y en CI nocturno.

@SpringBootTest
@ActiveProfiles({"homo", "integration"})
@Tag("integration-arca")
@EnabledIfEnvironmentVariable(named = "ARCA_INTEGRATION_TESTS", matches = "true")
class WsaaClientIntegrationTest {

  @Autowired WsaaClient client;

  @Test
  void obtiene_TA_valido_desde_wsaahomo() {
    TicketAcceso ta = client.loginCms("wsfe");

    assertThat(ta.token()).isNotBlank();
    assertThat(ta.sign()).isNotBlank();
    assertThat(ta.expirationTime())
        .isAfter(Instant.now())
        .isBefore(Instant.now().plus(Duration.ofHours(13)));
  }

  @Test
  void pedir_otro_TA_inmediatamente_falla_con_1001() {
    client.loginCms("wsfe");

    assertThatThrownBy(() -> client.loginCms("wsfe"))
        .isInstanceOf(WsaaException.class)
        .satisfies(e -> assertThat(((WsaaException) e).code())
            .isEqualTo(WsaaErrorCode.TA_ALREADY_VALID));
  }
}

Guía rápida de debugging.

Tener este slide impreso al lado del monitor el día que cruzás CP2 ahorra horas.

WSAA verde. Pasaste lo difícil.

• CertificateLoader carga el PKCS12 al startup y falla rápido si vencido.
• TraGenerator produce XML válido con uniqueId monotónico.
• CmsSigner firma con Bouncy Castle, test contra openssl pasa.
• WsaaClient.loginCms() orquesta los 5 pasos.
• TaParser devuelve TicketAcceso (record) con expirationTime correcto.
• Errores SOAP mapeados a WsaaErrorCode enum.
• Integration test contra wsaahomo verde (a demanda).
• Métricas: arca.wsaa.latency registrando.
• Logs sanitizados: tokens y signs nunca aparecen en texto plano.

Pedir un TA cuesta tiempo y dolor.

Repositorio puro, sin lógica.

public interface TokenCacheRepository {
  Optional<TicketAcceso> find(long cuit, String service);
  void save(long cuit, String service, TicketAcceso ta);
  void delete(long cuit, String service);
}

@Repository
class JdbcTokenCacheRepository implements TokenCacheRepository {

  private final JdbcTemplate jdbc;

  @Override
  public Optional<TicketAcceso> find(long cuit, String service) {
    String sql = """
        SELECT token, sign, unique_id, generation_time,
               expiration_time, obtained_at
        FROM wsaa_token
        WHERE cuit = ? AND service = ?
        """;
    try {
      return Optional.of(jdbc.queryForObject(sql, this::map, cuit, service));
    } catch (EmptyResultDataAccessException e) {
      return Optional.empty();
    }
  }

  @Override
  public void save(long cuit, String service, TicketAcceso ta) {
    // MERGE statement de SQL Server: insert or update
    String sql = """
        MERGE wsaa_token AS target
        USING (VALUES (?, ?)) AS source(cuit, service)
        ON target.cuit = source.cuit AND target.service = source.service
        WHEN MATCHED THEN UPDATE SET
          token = ?, sign = ?, unique_id = ?,
          generation_time = ?, expiration_time = ?, obtained_at = ?
        WHEN NOT MATCHED THEN INSERT
          (cuit, service, token, sign, unique_id,
           generation_time, expiration_time, obtained_at)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?);
        """;
    jdbc.update(sql,
        cuit, service,
        ta.token(), ta.sign(), ta.uniqueId(),
        Timestamp.from(ta.generationTime()),
        Timestamp.from(ta.expirationTime()),
        Timestamp.from(ta.obtainedAt()),
        cuit, service, ta.token(), ta.sign(), ta.uniqueId(),
        Timestamp.from(ta.generationTime()),
        Timestamp.from(ta.expirationTime()),
        Timestamp.from(ta.obtainedAt()));
  }

  // map(): RowMapper a TicketAcceso. Trivial.
}

Cuándo renovar. Cómo no estampedar.

@Component
public class TokenProvider {

  private final TokenCacheRepository cache;
  private final WsaaClient wsaa;
  private final ArcaProperties props;
  private final Clock clock;
  private static final Duration MARGIN = Duration.ofMinutes(5);

  // Lock por (cuit, service) para evitar stampede
  private final Map<String, ReentrantLock> locks = new ConcurrentHashMap<>();

  public TicketAcceso get(long cuit, String service) {
    // Camino feliz: caché válido sin lock
    Optional<TicketAcceso> cached = cache.find(cuit, service);
    if (cached.isPresent() && cached.get().isValid(clock.instant(), MARGIN)) {
      return cached.get();
    }

    // Camino lento: tomar lock, re-chequear, renovar si hace falta
    String key = cuit + "|" + service;
    ReentrantLock lock = locks.computeIfAbsent(key, k -> new ReentrantLock());
    lock.lock();
    try {
      // Otro thread pudo haberlo renovado mientras esperábamos
      cached = cache.find(cuit, service);
      if (cached.isPresent() && cached.get().isValid(clock.instant(), MARGIN)) {
        return cached.get();
      }

      // Realmente toca renovar
      TicketAcceso fresh = wsaa.loginCms(service);
      cache.save(cuit, service, fresh);
      return fresh;

    } finally {
      lock.unlock();
    }
  }
}

Esto resuelve el "thundering herd": si 50 requests llegan simultáneamente con TA vencido, uno solo va al WSAA, los otros 49 esperan al primero y reutilizan.

El lock local no escala.

Si corrés dos instancias del gateway, cada una tiene su ReentrantLock. Pueden pedir TA simultáneo y caer en error 1001. Solución: lock pesimista en la DB.

public TicketAcceso getDistributed(long cuit, String service) {
  Optional<TicketAcceso> cached = cache.find(cuit, service);
  if (cached.isPresent() && cached.get().isValid(clock.instant(), MARGIN)) {
    return cached.get();
  }

  // Lock pesimista en SQL Server via sp_getapplock
  String lockResource = "wsaa_token:" + cuit + ":" + service;
  jdbc.execute("EXEC sp_getapplock @Resource=?, @LockMode='Exclusive', @LockTimeout=10000", lockResource);
  try {
    cached = cache.find(cuit, service);
    if (cached.isPresent() && cached.get().isValid(clock.instant(), MARGIN)) {
      return cached.get();
    }
    TicketAcceso fresh = wsaa.loginCms(service);
    cache.save(cuit, service, fresh);
    return fresh;
  } finally {
    jdbc.execute("EXEC sp_releaseapplock @Resource=?", lockResource);
  }
}

sp_getapplock y sp_releaseapplock son built-ins de SQL Server. El lock se libera automáticamente si la sesión cae. Para tu caso (Java 21 + SQL Server) es la solución más simple sin agregar Redis.

El test que detecta el bug del estampedo.

@Test
void concurrent_requests_solo_invocan_wsaa_una_vez() throws Exception {
  // Setup: cache vacío
  when(cache.find(anyLong(), any())).thenReturn(Optional.empty());

  AtomicInteger wsaaCalls = new AtomicInteger(0);
  when(wsaa.loginCms(any())).thenAnswer(inv -> {
    wsaaCalls.incrementAndGet();
    Thread.sleep(200);  // simular latencia
    return validTa();
  });

  // Action: 20 threads piden simultáneamente
  ExecutorService exec = Executors.newFixedThreadPool(20);
  List<Future<TicketAcceso>> futures = new ArrayList<>();
  for (int i = 0; i < 20; i++) {
    futures.add(exec.submit(() -> provider.get(20111111112L, "wsfe")));
  }

  for (Future<TicketAcceso> f : futures) f.get();
  exec.shutdown();

  // Verify: solo UNA llamada a WSAA
  assertThat(wsaaCalls.get()).isEqualTo(1);
}

@Test
void ta_vencido_renueva() {
  TicketAcceso expirado = taConExpiration(Instant.now().minus(Duration.ofMinutes(1)));
  when(cache.find(anyLong(), any())).thenReturn(Optional.of(expirado));
  when(wsaa.loginCms(any())).thenReturn(validTa());

  TicketAcceso resultado = provider.get(20111111112L, "wsfe");

  verify(wsaa).loginCms("wsfe");
  verify(cache).save(eq(20111111112L), eq("wsfe"), any());
  assertThat(resultado.expirationTime()).isAfter(Instant.now());
}

Cuándo y cómo tirar el caché.

@RestController
@RequestMapping("/admin")
@RolesAllowed("ADMIN")
public class CacheAdminController {

  private final TokenCacheRepository cache;

  @DeleteMapping("/wsaa-cache/{cuit}/{service}")
  public ResponseEntity<Void> invalidar(
      @PathVariable long cuit,
      @PathVariable String service) {
    cache.delete(cuit, service);
    return ResponseEntity.noContent().build();
  }
}

Antes de pedir un CAE, saber por dónde vas.

FECompUltimoAutorizado es el método más simple. Te devuelve un número (o cero). Perfecto para validar que toda tu cadena WSAA → WSFEv1 funcione end-to-end antes de meterte con CAE.

# Request: 3 inputs (auth + ptoVta + cbteTipo)
# Response: 1 output (último número autorizado)
# Errores comunes: pocos, casi nada falla acá.

Si esto te funciona contra wswhomo, ya tenés:

• Cadena de certificados confiable.
• WSAA emitiendo TAs válidos.
• TokenProvider entregando token y sign correctos.
• Templates SOAP renderizando bien.
• Parser SOAP extrayendo datos sin errores.

Por eso es el primer "hello world" del WSFEv1.

Mustache template para una operación.

// src/main/resources/templates/soap/fe-comp-ultimo.mustache
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ar="http://ar.gov.afip.dif.FEV1/">
  <soapenv:Body>
    <ar:FECompUltimoAutorizado>
      <ar:Auth>
        <ar:Token>{{token}}</ar:Token>
        <ar:Sign>{{sign}}</ar:Sign>
        <ar:Cuit>{{cuit}}</ar:Cuit>
      </ar:Auth>
      <ar:PtoVta>{{ptoVta}}</ar:PtoVta>
      <ar:CbteTipo>{{cbteTipo}}</ar:CbteTipo>
    </ar:FECompUltimoAutorizado>
  </soapenv:Body>
</soapenv:Envelope>

Notar: tres valores variables (token, sign, cuit) + dos parámetros (ptoVta, cbteTipo). El namespace ar: es el que ARCA espera.

Diez líneas que valen oro.

@Component
public class Wsfev1Client {

  private final TokenProvider tokens;
  private final SoapTemplateRenderer renderer;
  private final SoapClient soap;
  private final SoapResponseParser parser;
  private final ArcaProperties props;
  private final ArcaMetrics metrics;

  public long ultimoAutorizado(int ptoVta, int cbteTipo) {
    return metrics.wsfev1Latency().record(() ->
        doUltimoAutorizado(ptoVta, cbteTipo));
  }

  private long doUltimoAutorizado(int ptoVta, int cbteTipo) {
    TicketAcceso ta = tokens.get(props.wsfev1().cuit(), "wsfe");

    String envelope = renderer.render("fe-comp-ultimo", Map.of(
        "token", ta.token(),
        "sign", ta.sign(),
        "cuit", props.wsfev1().cuit(),
        "ptoVta", ptoVta,
        "cbteTipo", cbteTipo));

    String respXml = soap.send(
        props.wsfev1().url(),
        "http://ar.gov.afip.dif.FEV1/FECompUltimoAutorizado",
        envelope);

    Document doc = parser.parse(respXml);

    // Verificar errores antes de leer el dato
    checkErrors(doc);

    String cbteNro = parser.text(doc,
        "//*[local-name()='FECompUltimoAutorizadoResult']/*[local-name()='CbteNro']");

    return Long.parseLong(cbteNro);
  }
}

Cada llamada WSFEv1 puede traer errores.

La estructura de errores y observaciones es común a todas las operaciones. Vale la pena un helper reutilizable.

private void checkErrors(Document doc) {
  // Errores excluyentes
  NodeList errors = (NodeList) xpath.evaluate(
      "//*[local-name()='Err']", doc, XPathConstants.NODESET);

  if (errors.getLength() > 0) {
    List<ArcaError> lista = new ArrayList<>();
    for (int i = 0; i < errors.getLength(); i++) {
      Node e = errors.item(i);
      String code = xml.text(e, "./*[local-name()='Code']");
      String msg = xml.text(e, "./*[local-name()='Msg']");
      lista.add(new ArcaError(code, msg));
    }
    throw new ArcaException(lista);
  }
}

private List<ArcaObservacion> extractObservaciones(Document doc) {
  NodeList obs = (NodeList) xpath.evaluate(
      "//*[local-name()='Obs']", doc, XPathConstants.NODESET);

  List<ArcaObservacion> lista = new ArrayList<>();
  for (int i = 0; i < obs.getLength(); i++) {
    Node o = obs.item(i);
    lista.add(new ArcaObservacion(
        xml.text(o, "./*[local-name()='Code']"),
        xml.text(o, "./*[local-name()='Msg']")));
  }
  return lista;
}

Observaciones (Obs) NO son excluyentes: el CAE viene OK pero ARCA marca algo. Las propagamos al cliente como info adicional, no como error.

Tu primera llamada al WSFEv1 real.

@SpringBootTest
@ActiveProfiles({"homo", "integration"})
@Tag("integration-arca")
class Wsfev1UltimoAutorizadoIntegrationTest {

  @Autowired Wsfev1Client client;

  @Test
  void obtiene_ultimo_autorizado_de_homologacion() {
    // PtoVta 1, Factura B
    long ultimo = client.ultimoAutorizado(1, 6);

    // En homologación puede ser 0 (no hay nada aún)
    // o un número alto (si ya emitiste antes).
    assertThat(ultimo).isGreaterThanOrEqualTo(0);
  }

  @Test
  void punto_de_venta_invalido_devuelve_error() {
    assertThatThrownBy(() -> client.ultimoAutorizado(99999, 6))
        .isInstanceOf(ArcaException.class)
        .satisfies(e -> assertThat(((ArcaException) e).errors())
            .anyMatch(err -> err.code().equals("10016")));
  }
}

Una llamada, una factura emitida.

Todo el resto del gateway existe para que esta llamada funcione. Cada falla acá significa una venta no facturada (o peor, mal facturada). Tratala con respeto.

Un record por capa, mappers explícitos.

// domain/SolicitudCae.java — el dominio puro
public record SolicitudCae(
    String requestId,        // UUID idempotente del POS
    int ptoVta,
    int cbteTipo,
    LocalDate cbteFch,
    Concepto concepto,       // enum: PRODUCTOS, SERVICIOS, AMBOS
    DocReceptor receptor,
    Importes importes,
    List<AlicuotaIva> alicuotasIva,
    List<Tributo> tributos,
    Moneda moneda,
    List<ComprobanteAsociado> asociados   // para NC, ND, etc.
) {

  public SolicitudCae {
    Objects.requireNonNull(requestId);
    Objects.requireNonNull(cbteFch);
    Objects.requireNonNull(concepto);
    Objects.requireNonNull(receptor);
    Objects.requireNonNull(importes);
    alicuotasIva = List.copyOf(alicuotasIva == null ? List.of() : alicuotasIva);
    tributos = List.copyOf(tributos == null ? List.of() : tributos);
    asociados = List.copyOf(asociados == null ? List.of() : asociados);
  }
}

public record Importes(
    BigDecimal neto,
    BigDecimal iva,
    BigDecimal tributos,
    BigDecimal exento,
    BigDecimal noGravado,
    BigDecimal total
) {}

public record AlicuotaIva(int id, BigDecimal baseImponible, BigDecimal importe) {}

No le mandés basura a ARCA, validá primero.

Cada llamada a ARCA es lenta, registrada, y limitada. Validar antes de enviar es servicio al cliente del POS y protección de tu rate limit.

@Component
public class SolicitudCaeValidator {

  public List<String> validar(SolicitudCae s) {
    List<String> errores = new ArrayList<>();

    // Suma de importes debe ser exacta
    BigDecimal sumaCalculada = s.importes().neto()
        .add(s.importes().iva())
        .add(s.importes().tributos())
        .add(s.importes().exento())
        .add(s.importes().noGravado());

    if (sumaCalculada.compareTo(s.importes().total()) != 0) {
      errores.add("ImpTotal no cuadra: esperado=" + sumaCalculada
          + " recibido=" + s.importes().total());
    }

    // IVA: suma de Importe debe coincidir con ImpIVA total
    BigDecimal sumaIva = s.alicuotasIva().stream()
        .map(AlicuotaIva::importe)
        .reduce(BigDecimal.ZERO, BigDecimal::add);

    if (sumaIva.compareTo(s.importes().iva()) != 0) {
      errores.add("Suma de alícuotas IVA no coincide con ImpIVA");
    }

    // Fecha del comprobante: para productos, ±5 días de hoy
    if (s.concepto() == Concepto.PRODUCTOS) {
      LocalDate hoy = LocalDate.now(ZoneId.of("America/Argentina/Buenos_Aires"));
      if (Math.abs(ChronoUnit.DAYS.between(hoy, s.cbteFch())) > 5) {
        errores.add("CbteFch fuera de ±5 días para productos");
      }
    }

    // Tipo de comprobante válido
    if (!TIPOS_VALIDOS.contains(s.cbteTipo())) {
      errores.add("CbteTipo desconocido: " + s.cbteTipo());
    }

    // Y muchas más reglas según el manual ARCA...
    return errores;
  }
}

Template con loops para alícuotas y tributos.

// templates/soap/fe-cae-solicitar.mustache
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="..." xmlns:ar="http://ar.gov.afip.dif.FEV1/">
  <soapenv:Body>
    <ar:FECAESolicitar>
      <ar:Auth>
        <ar:Token>{{token}}</ar:Token>
        <ar:Sign>{{sign}}</ar:Sign>
        <ar:Cuit>{{cuit}}</ar:Cuit>
      </ar:Auth>
      <ar:FeCAEReq>
        <ar:FeCabReq>
          <ar:CantReg>{{cantReg}}</ar:CantReg>
          <ar:PtoVta>{{ptoVta}}</ar:PtoVta>
          <ar:CbteTipo>{{cbteTipo}}</ar:CbteTipo>
        </ar:FeCabReq>
        <ar:FeDetReq>
          {{#detalles}}
          <ar:FECAEDetRequest>
            <ar:Concepto>{{concepto}}</ar:Concepto>
            <ar:DocTipo>{{docTipo}}</ar:DocTipo>
            <ar:DocNro>{{docNro}}</ar:DocNro>
            <ar:CbteDesde>{{cbteDesde}}</ar:CbteDesde>
            <ar:CbteHasta>{{cbteHasta}}</ar:CbteHasta>
            <ar:CbteFch>{{cbteFch}}</ar:CbteFch>
            <ar:ImpTotal>{{impTotal}}</ar:ImpTotal>
            <ar:ImpTotConc>{{impTotConc}}</ar:ImpTotConc>
            <ar:ImpNeto>{{impNeto}}</ar:ImpNeto>
            <ar:ImpOpEx>{{impOpEx}}</ar:ImpOpEx>
            <ar:ImpIVA>{{impIva}}</ar:ImpIVA>
            <ar:ImpTrib>{{impTrib}}</ar:ImpTrib>
            <ar:MonId>{{monId}}</ar:MonId>
            <ar:MonCotiz>{{monCotiz}}</ar:MonCotiz>
            {{#hasIva}}
            <ar:Iva>
              {{#alicuotasIva}}
              <ar:AlicIva>
                <ar:Id>{{id}}</ar:Id>
                <ar:BaseImp>{{baseImp}}</ar:BaseImp>
                <ar:Importe>{{importe}}</ar:Importe>
              </ar:AlicIva>
              {{/alicuotasIva}}
            </ar:Iva>
            {{/hasIva}}
          </ar:FECAEDetRequest>
          {{/detalles}}
        </ar:FeDetReq>
      </ar:FeCAEReq>
    </ar:FECAESolicitar>
  </soapenv:Body>
</soapenv:Envelope>

Mustache "{{#x}}...{{/x}}" itera si x es lista. "{{#hasIva}}" renderiza solo si la flag es true. Sin lógica en el template, todo viene preparado del Java.

Aplastar el dominio a Map (String, Object).

@Component
public class FeCaeRequestBuilder {

  public Map<String, Object> build(SolicitudCae s, TicketAcceso ta,
                                  long cuit, long cbteNro) {
    Map<String, Object> detalle = new HashMap<>();
    detalle.put("concepto", s.concepto().codigo());
    detalle.put("docTipo", s.receptor().tipoDoc().codigo());
    detalle.put("docNro", s.receptor().numeroDoc());
    detalle.put("cbteDesde", cbteNro);
    detalle.put("cbteHasta", cbteNro);
    detalle.put("cbteFch", s.cbteFch().format(YYYYMMDD));
    detalle.put("impTotal", fmt(s.importes().total()));
    detalle.put("impTotConc", fmt(s.importes().noGravado()));
    detalle.put("impNeto", fmt(s.importes().neto()));
    detalle.put("impOpEx", fmt(s.importes().exento()));
    detalle.put("impIva", fmt(s.importes().iva()));
    detalle.put("impTrib", fmt(s.importes().tributos()));
    detalle.put("monId", s.moneda().id());
    detalle.put("monCotiz", fmt(s.moneda().cotizacion()));

    boolean hasIva = !s.alicuotasIva().isEmpty();
    detalle.put("hasIva", hasIva);
    if (hasIva) {
      List<Map<String, Object>> alics = s.alicuotasIva().stream()
          .map(a -> Map.<String, Object>of(
              "id", a.id(),
              "baseImp", fmt(a.baseImponible()),
              "importe", fmt(a.importe())))
          .toList();
      detalle.put("alicuotasIva", alics);
    }

    return Map.of(
        "token", ta.token(),
        "sign", ta.sign(),
        "cuit", cuit,
        "cantReg", 1,
        "ptoVta", s.ptoVta(),
        "cbteTipo", s.cbteTipo(),
        "detalles", List.of(detalle));
  }

  private static String fmt(BigDecimal n) {
    return n.setScale(2, RoundingMode.HALF_UP).toPlainString();
  }
}

De SolicitudCae a RespuestaCae.

public RespuestaCae solicitarCae(SolicitudCae s) {
  // 1. Validar antes de enviar
  List<String> errores = validator.validar(s);
  if (!errores.isEmpty()) {
    throw new ValidacionLocalException(errores);
  }

  // 2. Determinar el número del próximo comprobante
  long ultimo = ultimoAutorizado(s.ptoVta(), s.cbteTipo());
  long nuevoNro = ultimo + 1;

  // 3. Obtener TA vigente
  TicketAcceso ta = tokens.get(props.wsfev1().cuit(), "wsfe");

  // 4. Construir y enviar
  Map<String, Object> ctx = requestBuilder.build(
      s, ta, props.wsfev1().cuit(), nuevoNro);
  String envelope = renderer.render("fe-cae-solicitar", ctx);

  String respXml = metrics.wsfev1Latency().record(() ->
      soap.send(props.wsfev1().url(),
                "http://ar.gov.afip.dif.FEV1/FECAESolicitar",
                envelope));

  // 5. Parsear respuesta
  Document doc = parser.parse(respXml);
  checkErrors(doc);

  String resultado = parser.text(doc, "//*[local-name()='Resultado']");
  if ("R".equals(resultado)) {
    // Rechazado: errores en el detalle, no en el header
    List<ArcaError> det = extractErroresDetalle(doc);
    throw new ArcaException(det);
  }

  // 6. Construir respuesta
  return new RespuestaCae(
      nuevoNro,
      parser.text(doc, "//*[local-name()='CAE']"),
      LocalDate.parse(parser.text(doc, "//*[local-name()='CAEFchVto']"), YYYYMMDD),
      extractObservaciones(doc));
}

Lo que ARCA aprobó, queda en tu DB.

Entre la respuesta de ARCA y el INSERT en tu DB no puede pasar nada. Si tu app crashea exactamente ahí, perdés trazabilidad de un comprobante real autorizado. Patrón: outbox-like, escribís ANTES y DESPUÉS.

@Transactional
public RespuestaCae procesarSolicitud(SolicitudCae s) {

  // 1. Persistir como PENDING ANTES de llamar a ARCA
  UUID id = UUID.randomUUID();
  comprobanteRepo.insertarPending(id, s, props.wsfev1().cuit());

  // 2. Llamada a ARCA (fuera de la TX para no holdear locks)
  RespuestaCae resp;
  try {
    resp = wsfev1.solicitarCae(s);
  } catch (ArcaException e) {
    // Actualizar estado a RECHAZADO con detalles
    comprobanteRepo.marcarRechazado(id, e.errors(), serializeJson(e));
    throw e;
  } catch (Exception e) {
    // Falla de red u otro: estado FAILED, requiere conciliación
    comprobanteRepo.marcarFailed(id, e.getMessage());
    throw e;
  }

  // 3. Actualizar como APROBADO con CAE
  comprobanteRepo.marcarAprobado(id, resp);

  return resp;
}

El estado FAILED es el más interesante: significa "no sabemos si ARCA lo aprobó o no". Un job periódico revisa los FAILED y los reconcilia llamando a FECompConsultar contra el número que se le había asignado.

No todos los errores son iguales.

public sealed interface ResultadoCae
    permits Aprobado, Observado,
            ValidacionLocalFalla, ArcaRechazo,
            ErrorTransitorio, ErrorAuth, ErrorDesconocido {

  record Aprobado(
      long cbteNro,
      String cae,
      LocalDate caeVto) implements ResultadoCae {}

  record Observado(
      long cbteNro,
      String cae,
      LocalDate caeVto,
      List<ArcaObservacion> obs) implements ResultadoCae {}

  record ValidacionLocalFalla(
      List<String> errores) implements ResultadoCae {}

  record ArcaRechazo(
      List<ArcaError> errores) implements ResultadoCae {}

  record ErrorTransitorio(
      String mensaje) implements ResultadoCae {}

  record ErrorAuth(String mensaje) implements ResultadoCae {}

  record ErrorDesconocido(
      String mensaje) implements ResultadoCae {}
}

Sealed interfaces de Java 21: el compilador te obliga a manejar todos los casos en el switch. Si agregás un nuevo tipo, los switch existentes no compilan hasta que lo manejes. Imposible olvidar un caso.

Tu primer CAE de homologación.

@SpringBootTest
@ActiveProfiles({"homo", "integration"})
@Tag("integration-arca")
class FeCaeSolicitarIntegrationTest {

  @Autowired CaeService caeService;

  @Test
  void emite_factura_b_consumidor_final_121_pesos() {
    SolicitudCae s = SolicitudCae.builder()
        .requestId(UUID.randomUUID().toString())
        .ptoVta(1)
        .cbteTipo(6)                         // Factura B
        .cbteFch(LocalDate.now())
        .concepto(Concepto.PRODUCTOS)
        .receptor(new DocReceptor(TipoDoc.CF, "0"))
        .importes(new Importes(
            new BigDecimal("100.00"),   // neto
            new BigDecimal("21.00"),    // iva
            BigDecimal.ZERO,                // tributos
            BigDecimal.ZERO,                // exento
            BigDecimal.ZERO,                // noGravado
            new BigDecimal("121.00")))   // total
        .alicuotasIva(List.of(
            new AlicuotaIva(5,                // 21%
                new BigDecimal("100.00"),
                new BigDecimal("21.00"))))
        .moneda(new Moneda("PES", BigDecimal.ONE))
        .build();

    ResultadoCae r = caeService.procesar(s);

    assertThat(r).isInstanceOf(Aprobado.class);
    Aprobado a = (Aprobado) r;
    assertThat(a.cae()).hasSize(14);   // CAE tiene 14 dígitos
    assertThat(a.caeVto()).isAfter(LocalDate.now());
    assertThat(a.cbteNro()).isGreaterThan(0);
  }
}

Primer CAE de homologación en producción.

• SolicitudCae como record con validaciones constructor.
• SolicitudCaeValidator chequea ImpTotal, alícuotas, fecha.
• Template Mustache fe-cae-solicitar.mustache con loops para IVA.
• FeCaeRequestBuilder mapea domain a contexto Mustache.
• solicitarCae() orquesta todo end-to-end.
• Persistencia: PENDING antes, APROBADO/RECHAZADO/FAILED después.
• ResultadoCae como sealed interface con 7 casos.
• Test integración emite Factura B en homo, obtiene CAE válido.
• Métricas: latencia de la operación más cara del sistema.

Verificación contra la fuente de verdad.

Tu DB local puede estar desactualizada (crash, deploy, race condition). ARCA es la fuente de verdad. FECompConsultar te permite preguntarle "che, ¿este número quedó autorizado?".

// Implementación: simple respecto a FECAESolicitar
public Optional<ComprobanteRegistrado> consultar(
    int ptoVta, int cbteTipo, long cbteNro) {

  TicketAcceso ta = tokens.get(cuit, "wsfe");
  String env = renderer.render("fe-comp-consultar", Map.of(
      "token", ta.token(), "sign", ta.sign(),
      "cuit", cuit,
      "ptoVta", ptoVta,
      "cbteTipo", cbteTipo,
      "cbteNro", cbteNro));

  String resp = soap.send(url, "FECompConsultar", env);
  Document doc = parser.parse(resp);
  checkErrors(doc);

  // Si CbteNro=0 en respuesta, no existe
  String nro = parser.text(doc, "//ResultGet/CbteNro");
  if ("0".equals(nro)) return Optional.empty();

  return Optional.of(new ComprobanteRegistrado(
      Long.parseLong(nro),
      parser.text(doc, "//ResultGet/CodAutorizacion"),
      LocalDate.parse(parser.text(doc, "//ResultGet/FchVto"), YYYYMMDD)));
}

Que ningún FAILED se quede colgado.

@Component
public class ReconciliacionJob {

  private final ComprobanteRepository repo;
  private final Wsfev1Client wsfev1;
  private final ArcaMetrics metrics;

  @Scheduled(cron = "0 30 2 * * *")  // 2:30 AM todos los días
  public void reconciliarFailed() {
    List<Comprobante> failed = repo.findByEstado("FAILED");

    for (Comprobante c : failed) {
      try {
        Optional<ComprobanteRegistrado> arca =
            wsfev1.consultar(c.ptoVta(), c.cbteTipo(), c.cbteNro());

        if (arca.isPresent()) {
          // ARCA SÍ lo tenía aprobado. Actualizar nuestro estado.
          repo.recuperarComoAprobado(c.id(), arca.get().cae(), arca.get().caeVto());
          metrics.reconciliacionExitosa();
          log.info("Reconciliado FAILED {} como APROBADO. CAE={}",
              c.id(), arca.get().cae());
        } else {
          // ARCA no lo tiene. El comprobante nunca se autorizó.
          repo.confirmarComoFailedDefinitivo(c.id());
          metrics.reconciliacionConfirmaFallo();
        }
      } catch (Exception e) {
        log.error("Reconciliación falló para {}, reintentar mañana", c.id(), e);
      }
    }
  }
}

Patrón powerful: el sistema se auto-cura. Comprobantes que quedaron en duda ayer, hoy tienen un estado definitivo. Lo dejás corriendo y dormís tranquilo.

Antes de retentar, preguntá.

El POS no recibió respuesta del gateway por timeout. Vuelve a llamar con el mismo X-Request-Id. Nosotros consultamos a ARCA antes de procesar nuevamente.

@Service
public class CaeService {

  public ResultadoCae procesar(SolicitudCae s) {
    // Idempotencia: ya procesado?
    Optional<Comprobante> existente = repo.findByRequestId(s.requestId());
    if (existente.isPresent()) {
      return existente.get().estado().equals("APROBADO")
          ? aprobadoDe(existente.get())
          : reprocesar(existente.get(), s);
    }

    // Primera vez: flujo normal
    return nuevaSolicitud(s);
  }

  private ResultadoCae reprocesar(Comprobante c, SolicitudCae s) {
    // Si estado es FAILED: chequear contra ARCA primero
    if (c.estado().equals("FAILED")) {
      Optional<ComprobanteRegistrado> arca =
          wsfev1.consultar(c.ptoVta(), c.cbteTipo(), c.cbteNro());

      if (arca.isPresent()) {
        repo.recuperarComoAprobado(c.id(), arca.get().cae(), arca.get().caeVto());
        return new Aprobado(c.cbteNro(), arca.get().cae(), arca.get().caeVto());
      }
    }

    // No estaba en ARCA: retentamos
    return nuevaSolicitud(s);
  }
}

El sistema se conoce a sí mismo.

• FECompConsultar implementado, devuelve Optional según existencia.
• Job de reconciliación corre nocturno, repara estados FAILED.
• Pre-retry check: antes de re-procesar, preguntás a ARCA.
• Métricas: cuántas reconciliaciones por día, exitosas vs definitivamente fallidas.
• Alertas: si FAILED no se reconcilia en 24h, page al equipo.

OpenAPI primero, controllers después.

El POS habla con vos vía REST/JSON. Diseñá la API antes de implementarla. OpenAPI 3 te da contrato, doc auto, validación y stubs gratis.

# src/main/resources/openapi/gateway.yaml
openapi: 3.0.3
info:
  title: ARCA Gateway API
  version: 1.0.0

paths:
  /api/v1/comprobantes:
    post:
      summary: Solicitar autorización (CAE) de un comprobante
      parameters:
        - in: header
          name: X-Request-Id
          required: true
          schema:
            type: string
            format: uuid
          description: ID idempotente único por solicitud
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SolicitudCaeDto"
      responses:
        "200":
          description: CAE otorgado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RespuestaCaeDto"
        "422":
          description: Validación falló (local o ARCA)
        "503":
          description: ARCA no disponible, reintentar

Beneficio enorme: tu equipo de POS recibe el YAML y puede generar clientes en su lenguaje (TS, C#, Java). Sin Skype, sin idas y vueltas.

Thin controller, service hace todo.

@RestController
@RequestMapping("/api/v1")
@Validated
public class ComprobantesController {

  private final CaeService caeService;
  private final SolicitudCaeDtoMapper mapper;

  @PostMapping("/comprobantes")
  public ResponseEntity<?> solicitar(
      @RequestHeader("X-Request-Id") @NotBlank String requestId,
      @RequestBody @Valid SolicitudCaeDto dto) {

    SolicitudCae domain = mapper.toDomain(dto, requestId);
    ResultadoCae r = caeService.procesar(domain);

    return switch (r) {
      case Aprobado a -> ResponseEntity.ok(mapper.aprobadoDto(a));
      case Observado o -> ResponseEntity.ok(mapper.observadoDto(o));
      case ValidacionLocalFalla v -> ResponseEntity.unprocessableEntity()
          .body(new ErrorDto("VALIDATION", v.errores()));
      case ArcaRechazo a -> ResponseEntity.unprocessableEntity()
          .body(new ErrorDto("ARCA_REJECTED", a.errores()));
      case ErrorTransitorio t -> ResponseEntity.status(503)
          .header("Retry-After", "30")
          .body(new ErrorDto("TRANSIENT", t.mensaje()));
      case ErrorAuth e -> ResponseEntity.status(500)
          .body(new ErrorDto("AUTH", e.mensaje()));
      case ErrorDesconocido e -> ResponseEntity.status(500)
          .body(new ErrorDto("UNKNOWN", e.mensaje()));
    };
  }

  @GetMapping("/ultimo-comprobante")
  public UltimoCbteDto ultimo(
      @RequestParam int ptoVta,
      @RequestParam int cbteTipo) {
    return new UltimoCbteDto(wsfev1.ultimoAutorizado(ptoVta, cbteTipo));
  }
}

El switch sobre sealed interface es exhaustivo: si agregás un caso a ResultadoCae sin tocar acá, no compila. Hermosa propiedad.

Errores 400 antes de llegar al service.

public record SolicitudCaeDto(
    @NotNull @Min(1) Integer puntoVenta,
    @NotNull @Min(1) Integer tipoComprobante,
    @NotNull LocalDate fechaComprobante,
    @NotNull @Valid ReceptorDto receptor,
    @NotNull @Min(1) @Max(3) Integer concepto,
    @NotNull @Valid ImportesDto importes,
    @NotNull List<@Valid AlicuotaIvaDto> alicuotasIva,
    List<@Valid TributoDto> tributos,
    @NotNull @Valid MonedaDto moneda) {
}

public record ImportesDto(
    @NotNull @DecimalMin("0.00") BigDecimal neto,
    @NotNull @DecimalMin("0.00") BigDecimal iva,
    @NotNull @DecimalMin("0.00") BigDecimal tributos,
    @NotNull @DecimalMin("0.00") BigDecimal exento,
    @NotNull @DecimalMin("0.00") BigDecimal noGravado,
    @NotNull @DecimalMin("0.01") BigDecimal total) {
}

@RestControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(MethodArgumentNotValidException.class)
  public ResponseEntity<ErrorDto> handleValidation(MethodArgumentNotValidException e) {
    List<String> mensajes = e.getBindingResult().getFieldErrors().stream()
        .map(err -> err.getField() + ": " + err.getDefaultMessage())
        .toList();
    return ResponseEntity.badRequest()
        .body(new ErrorDto("VALIDATION", mensajes));
  }
}

Mismo requestId → misma respuesta.

// El POS genera UUID v4 antes de llamar.
// Si timeout, reintenta con el MISMO X-Request-Id.
// Si el gateway ya lo procesó, devuelve la respuesta original.

@Service
public class CaeService {

  private final ComprobanteRepository repo;
  private final Wsfev1Client wsfev1;

  public ResultadoCae procesar(SolicitudCae s) {
    // Step 1: chequear idempotencia
    Optional<Comprobante> existente = repo.findByRequestId(s.requestId());

    if (existente.isPresent()) {
      Comprobante c = existente.get();
      return switch (c.estado()) {
        case APROBADO -> new Aprobado(c.cbteNro(), c.cae(), c.caeVto());
        case OBSERVADO -> new Observado(c.cbteNro(), c.cae(), c.caeVto(), c.observaciones());
        case RECHAZADO -> new ArcaRechazo(c.errores());
        case FAILED -> reconciliarYDecidir(c, s);
        case PENDING -> new ErrorTransitorio("En proceso, reintentar");
      };
    }

    // Step 2: nuevo flujo
    return ejecutarFlujoCompleto(s);
  }

  // El INSERT por requestId es atómico gracias al UNIQUE INDEX
  // ux_comprobante_request_id. Si dos llegan en paralelo,
  // uno gana, el otro recibe DataIntegrityViolation y
  // puede reintentar el SELECT.
}

La clave UNIQUE en request_id es la garantía. Sin esa restricción de DB, dos requests concurrentes podrían crear dos comprobantes.

Springdoc y listo.

# pom.xml
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.5.0</version>
</dependency>

# application.yml
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method

Listo. Levantás la app y tenés:

• GET /api-docs — JSON OpenAPI v3 actualizado en cada rebuild.
• GET /swagger-ui.html — UI interactiva para probar.
• Anotás los controllers con @Operation, @ApiResponse para personalizar.
• El equipo de POS lo bookmarkea, problemas de "cómo llamar a la API" desaparecen.

Importante: el OpenAPI auto-generado no reemplaza el yaml manual de la sección anterior — son herramientas distintas. El YAML manual es el contrato que vos decidís; el auto-generado verifica que la implementación coincida. Si difieren, hay un bug en algún lado.

API REST completa, idempotente, documentada.

• OpenAPI 3 yaml como contrato del POS.
• Controllers thin, switch exhaustivo sobre ResultadoCae.
• Bean Validation con records y constraints declarativas.
• Mappers explícitos DTO <> domain.
• Idempotencia con UNIQUE INDEX sobre request_id.
• GlobalExceptionHandler estandariza errores.
• Swagger UI funcionando para developers de POS.
• Tests integración end-to-end con MockMvc + WireMock (próximas slides).

Tres capas, cada una con su rol.

    /\
   /E2E\           ←  pocos, lentos, reales
  /------\
 /Integration\     ←  medianos, WireMock
/--------------\
   Unit tests      ←  muchos, rápidos, aislados

Tabla de casos, parametrizado.

class SolicitudCaeValidatorTest {

  private final SolicitudCaeValidator validator = new SolicitudCaeValidator();

  @Test
  void happy_path_factura_b_consumidor_final() {
    SolicitudCae s = facturaBValida();
    assertThat(validator.validar(s)).isEmpty();
  }

  @ParameterizedTest
  @MethodSource("casosImporteTotalIncorrecto")
  void rechaza_imp_total_que_no_cuadra(Importes imp, String mensajeEsperado) {
    SolicitudCae s = facturaBValida().conImportes(imp);
    List<String> errores = validator.validar(s);
    assertThat(errores).anyMatch(m -> m.contains(mensajeEsperado));
  }

  static Stream<Arguments> casosImporteTotalIncorrecto() {
    return Stream.of(
        Arguments.of(new Importes("100", "21", "0", "0", "0", "120"),  // debería ser 121
            "ImpTotal no cuadra"),
        Arguments.of(new Importes("100", "21", "5", "0", "0", "121"),  // 126
            "ImpTotal no cuadra"),
        Arguments.of(new Importes("100", "21", "0", "50", "0", "121"), // 171
            "ImpTotal no cuadra"));
  }

  @Test
  void fecha_fuera_de_5_dias_para_productos_falla() {
    SolicitudCae s = facturaBValida()
        .conConcepto(Concepto.PRODUCTOS)
        .conFecha(LocalDate.now().minusDays(10));
    assertThat(validator.validar(s))
        .anyMatch(m -> m.contains("CbteFch fuera"));
  }
}

Generar cert en el test, firmar y verificar.

class CmsSignerTest {

  @Test
  void firma_es_verificable_con_el_mismo_cert() throws Exception {
    // 1. Generar par de claves + cert auto-firmado para el test
    KeyPair kp = KeyPairGenerator.getInstance("RSA").genKeyPair();
    X509Certificate cert = generarCertSelfSigned(kp);

    String tra = "<TRA>contenido a firmar</TRA>";
    CmsSigner signer = new CmsSigner();

    // 2. Firmar
    String base64 = signer.firmar(tra, kp.getPrivate(), cert);

    // 3. Verificar
    byte[] bytes = Base64.getDecoder().decode(base64);
    CMSSignedData cms = new CMSSignedData(bytes);

    SignerInformation si = cms.getSignerInfos().getSigners().iterator().next();
    X509CertificateHolder holder = (X509CertificateHolder)
        cms.getCertificates().getMatches(si.getSID()).iterator().next();

    boolean ok = si.verify(new JcaSimpleSignerInfoVerifierBuilder()
        .setProvider("BC").build(holder));

    assertThat(ok).isTrue();
  }

  @Test
  void firma_falla_si_clave_no_corresponde_al_cert() throws Exception {
    KeyPair kp1 = KeyPairGenerator.getInstance("RSA").genKeyPair();
    KeyPair kp2 = KeyPairGenerator.getInstance("RSA").genKeyPair();
    X509Certificate cert = generarCertSelfSigned(kp1);

    // Usar clave equivocada
    assertThatThrownBy(() -> signer.firmar("x", kp2.getPrivate(), cert))
        .isInstanceOf(CmsSigningException.class);
  }
}

WireMock responde como ARCA.

public class ArcaWireMockStubs {

  public static void stubWsaaSuccess(WireMockServer wm, TicketAccesoFixture ta) {
    wm.stubFor(post("/ws/services/LoginCms")
        .withHeader("SOAPAction", equalTo("loginCms"))
        .willReturn(ok(loginCmsResponseXml(ta))
            .withHeader("Content-Type", "text/xml; charset=utf-8")));
  }

  public static void stubWsaaError1001(WireMockServer wm) {
    wm.stubFor(post("/ws/services/LoginCms")
        .willReturn(aResponse().withStatus(500)
            .withBody(soapFault("ns1:1001", "El CEE ya posee un TA"))));
  }

  public static void stubFeCompUltimo(WireMockServer wm, long cbteNro) {
    wm.stubFor(post(urlMatching("/wsfev1/service.asmx"))
        .withRequestBody(matchingXPath("//*[local-name()='FECompUltimoAutorizado']"))
        .willReturn(ok(feCompUltimoResponseXml(cbteNro))));
  }

  public static void stubFeCaeSolicitarAprobado(WireMockServer wm, String cae) {
    wm.stubFor(post("/wsfev1/service.asmx")
        .withRequestBody(matchingXPath("//*[local-name()='FECAESolicitar']"))
        .willReturn(ok(feCaeResponseXml("A", cae, "20260530"))));
  }

  public static void stubFeCaeSolicitarRechazado(WireMockServer wm, ArcaError... errores) {
    wm.stubFor(post("/wsfev1/service.asmx")
        .withRequestBody(matchingXPath("//*[local-name()='FECAESolicitar']"))
        .willReturn(ok(feCaeRespRechazoXml(errores))));
  }
}

Tener estos helpers en un archivo aparte hace que cada test sea legible. Mirás el test y entendés qué simula ARCA en cada caso.

Service completo, ARCA simulado.

@SpringBootTest(webEnvironment = MOCK)
@AutoConfigureMockMvc
@AutoConfigureWireMock(port = 0)
@ActiveProfiles("test")
class CaeIntegrationTest {

  @Autowired MockMvc mvc;
  @Autowired WireMockServer arcaWireMock;
  @Autowired ObjectMapper json;

  @BeforeEach
  void setup() {
    ArcaWireMockStubs.stubWsaaSuccess(arcaWireMock, ticketFixture());
    ArcaWireMockStubs.stubFeCompUltimo(arcaWireMock, 12345);
    ArcaWireMockStubs.stubFeCaeSolicitarAprobado(arcaWireMock, "75123456789012");
  }

  @Test
  void emite_factura_b_completa_end_to_end() throws Exception {
    SolicitudCaeDto dto = facturaBValidaDto();
    String requestId = UUID.randomUUID().toString();

    mvc.perform(post("/api/v1/comprobantes")
            .header("X-Request-Id", requestId)
            .contentType(APPLICATION_JSON)
            .content(json.writeValueAsString(dto)))
       .andExpect(status().isOk())
       .andExpect(jsonPath("$.cae").value("75123456789012"))
       .andExpect(jsonPath("$.numero").value(12346))
       .andExpect(jsonPath("$.observaciones").isEmpty());

    // Verificación lateral: persistido en DB
    Comprobante guardado = repo.findByRequestId(requestId).orElseThrow();
    assertThat(guardado.estado()).isEqualTo("APROBADO");
    assertThat(guardado.cae()).isEqualTo("75123456789012");
  }
}

Mismo X-Request-Id, misma respuesta exacta.

@Test
void mismo_request_id_devuelve_mismo_cae_sin_llamar_arca() throws Exception {
  String requestId = UUID.randomUUID().toString();
  SolicitudCaeDto dto = facturaBValidaDto();

  // Primera llamada
  String resp1 = mvc.perform(post("/api/v1/comprobantes")
          .header("X-Request-Id", requestId)
          .contentType(APPLICATION_JSON)
          .content(json.writeValueAsString(dto)))
      .andExpect(status().isOk())
      .andReturn().getResponse().getContentAsString();

  // Reset stubs: si la segunda llama, falla con 500
  arcaWireMock.resetAll();
  arcaWireMock.stubFor(post(anyUrl()).willReturn(serverError()));

  // Segunda llamada con mismo requestId
  String resp2 = mvc.perform(post("/api/v1/comprobantes")
          .header("X-Request-Id", requestId)
          .contentType(APPLICATION_JSON)
          .content(json.writeValueAsString(dto)))
      .andExpect(status().isOk())
      .andReturn().getResponse().getContentAsString();

  // Las dos respuestas son idénticas
  assertThat(resp1).isEqualTo(resp2);

  // ARCA solo se llamó UNA vez (en la primera)
  arcaWireMock.verify(0, postRequestedFor(urlMatching("/wsfev1/.*")));
}

Este test es oro. Cualquier refactor que rompa idempotencia accidentalmente, falla acá inmediatamente.

Cada error de ARCA tiene su test.

@ParameterizedTest
@MethodSource("erroresArca")
void mapea_errores_arca_al_codigo_correcto(
    String codigoArca, String mensaje, int statusHttpEsperado) throws Exception {

  arcaWireMock.resetAll();
  ArcaWireMockStubs.stubWsaaSuccess(arcaWireMock, ticketFixture());
  ArcaWireMockStubs.stubFeCompUltimo(arcaWireMock, 100);
  ArcaWireMockStubs.stubFeCaeSolicitarRechazado(arcaWireMock,
      new ArcaError(codigoArca, mensaje));

  mvc.perform(post("/api/v1/comprobantes")
          .header("X-Request-Id", UUID.randomUUID().toString())
          .contentType(APPLICATION_JSON)
          .content(json.writeValueAsString(facturaBValidaDto())))
     .andExpect(status().is(statusHttpEsperado))
     .andExpect(jsonPath("$.errores[0].codigo").value(codigoArca));
}

static Stream<Arguments> erroresArca() {
  return Stream.of(
      Arguments.of("10015", "CbteFch fuera de rango",        422),
      Arguments.of("10016", "Punto de venta no habilitado",   422),
      Arguments.of("10018", "CbteNro fuera de secuencia",     422),
      Arguments.of("10048", "ImpTotal incorrecto",            422),
      Arguments.of("600",   "Token vencido",                  500),
      Arguments.of("503",   "Servicio temporalmente caído",    503));
}

Lo que esperamos al cerrar B12.

• ~70 tests unitarios. Suite corre en < 5 segundos.
• ~20 tests de integración con WireMock + MockMvc. < 60 segundos.
• ~6 tests E2E contra ARCA homologación, taggeados, on-demand.
• Cobertura unit + integration: > 80% líneas.
• Tests parametrizados para casos sucios (8+ códigos de error).
• Test de idempotencia verde (el más importante del set).
• WireMock stubs reutilizables en archivo aparte.
• CI ejecuta unit + integration en cada push. E2E en cron nocturno.

Tests verifican código. Evals verifican comportamiento.

Aplicando los conceptos del módulo de Evals del curso, en un gateway las evaluaciones no son sobre LLMs sino sobre el comportamiento end-to-end del sistema en condiciones realistas.

Un test gigante contra staging real.

@SpringBootTest
@ActiveProfiles({"homo", "eval"})
@Tag("eval")
public class GatewayEvalSuite {

  @Test
  void eval_runs_500_solicitudes_y_reporta_metricas() throws Exception {
    List<EvalCase> cases = cargarDataset("evals/dataset.json");
    EvalResults results = new EvalResults();

    for (EvalCase ec : cases) {
      Instant start = Instant.now();
      try {
        ResultadoCae r = caeService.procesar(ec.solicitud());
        results.record(ec, r, Duration.between(start, Instant.now()));
      } catch (Exception e) {
        results.recordError(ec, e, Duration.between(start, Instant.now()));
      }
    }

    // Reporte estructurado
    results.exportar("target/eval-report-" + Instant.now() + ".json");

    // Asserts sobre métricas agregadas, no sobre casos individuales
    assertThat(results.tasaExito()).isGreaterThan(0.95);
    assertThat(results.p95Latency()).isLessThan(Duration.ofSeconds(3));
    assertThat(results.tasaErrorTransient()).isLessThan(0.02);
    assertThat(results.idempotenciaConsistency()).isEqualTo(1.0);
  }
}

Tags: @Tag("eval") para excluirlo del build normal. Se ejecuta a mano antes de releases mayores, o nightly en CI.

JSON, después HTML, después decisión.

// target/eval-report-2026-05-14T15:00:00Z.json
{
  "timestamp": "2026-05-14T15:00:00Z",
  "total_cases": 500,
  "resumen": {
    "aprobados": 478,
    "observados": 12,
    "rechazados_validacion": 7,
    "rechazados_arca": 3,
    "errores_transient": 0,
    "errores_auth": 0,
    "errores_desconocidos": 0
  },
  "latencias_ms": {
    "p50": 847,
    "p95": 2103,
    "p99": 3450,
    "max": 8920
  },
  "casos_lentos": [
    {"id": "factura-a-cuit-grande", "latencia_ms": 8920, "resultado": "APROBADO"},
    ...
  ],
  "regresion_vs_baseline": {
    "p95_delta": "+103ms",
    "tasa_exito_delta": "-0.4%",
    "alerta": "latencia p95 subió, investigar"
  }
}

Después un script convierte esto en HTML legible, lo subís a S3, o lo enviás a Slack. Lo importante: cada eval queda registrado, comparable contra runs anteriores.

Cómo invalidar tu propia evaluación.

Casos reales donde se rompe.

• Cliente sin requestId. El POS olvida el header. Si pasa, lo registrás como bug del cliente, no inventás uno vos.
• RequestId que vos generás. Si el gateway pone el UUID, perdés idempotencia entre llamadas — cada llamada es "nueva" desde tu perspectiva.
• Carrera entre dos requests simultáneos. Mismo requestId, llegan en el mismo milisegundo. UNIQUE INDEX gana, pero el segundo tiene que esperar y leer.
• Transacción mal usada. SELECT por requestId fuera de la TX donde se hace el INSERT. Read uncommitted o race.
• Cache stale. Caché en memoria que no se invalida cuando otra instancia inserta.
• Crash entre INSERT y respuesta a ARCA. Cliente reintenta, encuentra PENDING, no sabe qué hacer.

Lo importante: la idempotencia no es magia. Es una propiedad emergente de varios componentes funcionando bien juntos. Cualquiera de los seis puntos arriba puede romperla.

Dos POS, mismo número de comprobante.

Sin protección: POS-A y POS-B preguntan ultimoAutorizado, ambos reciben 100. Ambos intentan emitir 101. Uno gana, el otro recibe error 10018 (CbteNro fuera de secuencia). Si los reintenta sin lock, el bug se repite.

// Solución: lock pesimista en la app antes de ARCA

@Component
public class NumeroComprobanteAllocator {

  private final JdbcTemplate jdbc;
  private final Wsfev1Client wsfev1;

  @Transactional
  public long proximoNumero(long cuit, int ptoVta, int cbteTipo) {
    // Lock distribuido por la combinación específica
    String resource = "nro:" + cuit + ":" + ptoVta + ":" + cbteTipo;
    jdbc.update("EXEC sp_getapplock @Resource=?, @LockMode='Exclusive', @LockTimeout=15000", resource);

    // Dentro del lock: consultar y devolver el siguiente
    long ultimo = wsfev1.ultimoAutorizado(ptoVta, cbteTipo);

    // Verificar consistencia con DB local
    Long ultimoLocal = jdbc.queryForObject(
        "SELECT MAX(cbte_nro) FROM comprobante WHERE cuit=? AND pto_vta=? AND cbte_tipo=? AND estado='APROBADO'",
        Long.class, cuit, ptoVta, cbteTipo);

    long base = Math.max(ultimo, ultimoLocal != null ? ultimoLocal : 0L);
    return base + 1;
  }
}

El lock se libera al final de la transacción automáticamente (siempre que uses @LockOwner='Transaction', default). Los otros requests esperan hasta 15s.

Confiar en la DB, no en la lógica.

public Comprobante insertarPendingIdempotent(SolicitudCae s, long cuit, long nro) {
  try {
    UUID id = UUID.randomUUID();
    jdbc.update("""
        INSERT INTO comprobante (id, request_id, pos_id, cuit, pto_vta, cbte_tipo,
                                cbte_nro, cbte_fch, doc_tipo, doc_nro,
                                imp_total, imp_neto, imp_iva, estado, payload_json, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'PENDING', ?, SYSUTCDATETIME())
        """, id, s.requestId(), s.posId(), cuit, s.ptoVta(), s.cbteTipo(),
            nro, s.cbteFch(), s.receptor().tipoDoc().codigo(), s.receptor().numeroDoc(),
            s.importes().total(), s.importes().neto(), s.importes().iva(),
            json(s));
    return findById(id);

  } catch (DuplicateKeyException e) {
    // Otro request con mismo X-Request-Id ya estaba en flight.
    // Leer la fila existente y devolver eso.
    log.info("Idempotente: requestId={} ya existía", s.requestId());
    return findByRequestId(s.requestId())
        .orElseThrow(() -> new IllegalStateException("Race lost data"));
  }
}

Patrón: intentar INSERT, capturar DuplicateKeyException, leer la fila ganadora. Es atómico, sin necesidad de SELECT-FOR-UPDATE.

Cien threads, un solo requestId.

@Test
void cien_requests_concurrentes_con_mismo_request_id() throws Exception {
  String requestId = UUID.randomUUID().toString();
  SolicitudCaeDto dto = facturaBValidaDto();

  ArcaWireMockStubs.stubWsaaSuccess(arcaWireMock, ticketFixture());
  ArcaWireMockStubs.stubFeCompUltimo(arcaWireMock, 100);
  ArcaWireMockStubs.stubFeCaeSolicitarAprobado(arcaWireMock, "75123456789012");

  ExecutorService exec = Executors.newFixedThreadPool(20);
  List<Future<String>> futures = new ArrayList<>();

  for (int i = 0; i < 100; i++) {
    futures.add(exec.submit(() -> {
      MvcResult res = mvc.perform(post("/api/v1/comprobantes")
              .header("X-Request-Id", requestId)
              .contentType(APPLICATION_JSON)
              .content(json.writeValueAsString(dto)))
          .andReturn();
      return res.getResponse().getContentAsString();
    }));
  }

  Set<String> respuestasDistintas = futures.stream()
      .map(this::getQuietly)
      .collect(Collectors.toSet());

  // Las 100 respuestas son IDÉNTICAS
  assertThat(respuestasDistintas).hasSize(1);

  // ARCA fue llamado UNA sola vez (idempotencia operacional)
  arcaWireMock.verify(1, postRequestedFor(urlMatching(".*/wsfev1/.*"))
      .withRequestBody(matchingXPath("//*[local-name()='FECAESolicitar']")));

  // Hay un solo comprobante en DB
  assertThat(repo.countByRequestId(requestId)).isEqualTo(1);
}

RequestId no es para siempre.

Si guardamos cada requestId para siempre, la tabla crece sin límite. Política razonable: idempotencia garantizada por 7 días. Después, el mismo requestId genera un comprobante nuevo (porque ya nadie se acuerda del viejo).

-- Limpieza nocturna
DELETE FROM comprobante
WHERE created_at < DATEADD(DAY, -7, SYSUTCDATETIME())
  AND estado IN ('RECHAZADO', 'VALIDATION_FAIL');

-- Los APROBADOS NUNCA se borran. Quedan para auditoría fiscal.
-- Pero el UNIQUE INDEX sobre request_id puede liberarse
-- archivando viejos a tabla histórica:
INSERT INTO comprobante_historico
SELECT * FROM comprobante
WHERE approved_at < DATEADD(MONTH, -3, SYSUTCDATETIME());

-- Borrado solo del request_id en comprobante activo:
UPDATE comprobante SET request_id = NULL
WHERE approved_at < DATEADD(MONTH, -3, SYSUTCDATETIME());

El comprobante quedó, el CAE quedó, pero el requestId se libera para evitar bloqueo de uniqueness a futuro. Trade-off explícito documentado.

Idempotencia testeada y operativa.

• UNIQUE INDEX sobre request_id garantiza atomicidad.
• Try INSERT / catch DuplicateKey, leer fila ganadora.
• Lock distribuido con sp_getapplock para numeración consecutiva.
• Test de 100 threads concurrentes con mismo requestId pasa.
• TTL definido y job de limpieza nocturna implementado.
• Manejo de PENDING/FAILED en re-llamadas idempotentes.

Cinco métricas que mirás todos los días.

Tres números que tienen que estar en la pantalla principal del dashboard: tasa de aprobación últimos 5 min, latencia p95, vencimiento del TA. Si los tres están verdes, dormís.

AOP o decoradores, no manual en cada método.

@Aspect
@Component
public class ArcaMetricsAspect {

  private final MeterRegistry registry;

  @Around("execution(* com.miempresa.arcagw.infrastructure.arca.*Client.*(..))")
  public Object instrumentarLlamada(ProceedingJoinPoint pjp) throws Throwable {
    String classSimple = pjp.getTarget().getClass().getSimpleName();
    String method = pjp.getSignature().getName();

    Timer.Sample sample = Timer.start(registry);
    String resultado = "success";

    try {
      return pjp.proceed();
    } catch (ArcaException e) {
      resultado = "arca_error";
      throw e;
    } catch (Exception e) {
      resultado = "unknown_error";
      throw e;
    } finally {
      sample.stop(Timer.builder("arca.client.latency")
          .tag("client", classSimple)
          .tag("method", method)
          .tag("resultado", resultado)
          .publishPercentileHistogram()
          .register(registry));
    }
  }
}

Todo método de un cliente ARCA queda automáticamente medido. No hay olvidos. No hay duplicación. Si agregás un cliente nuevo mañana, ya viene con métricas.

Logs JSON. Buscables, correlacionables.

# logback-spring.xml — configuración para JSON en prod
<appender name="STDOUT_JSON" class="ch.qos.logback.core.ConsoleAppender">
  <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
    <providers>
      <timestamp/>
      <version/>
      <loggerName/>
      <logLevel/>
      <message/>
      <mdc/>                  <!-- traceId, requestId, etc -->
      <stackTrace/>
      <arguments includeNonStructuredArguments="false"/>
    </providers>
  </encoder>
</appender>

// Cómo logear con contexto
@Slf4j
public class CaeService {

  public ResultadoCae procesar(SolicitudCae s) {
    MDC.put("requestId", s.requestId());
    MDC.put("ptoVta", String.valueOf(s.ptoVta()));
    MDC.put("cbteTipo", String.valueOf(s.cbteTipo()));
    try {
      log.info("Procesando solicitud CAE",
          kv("importeTotal", s.importes().total()),
          kv("docNro", s.receptor().numeroDoc()));
      // ...
    } finally {
      MDC.clear();
    }
  }
}

En Splunk, Datadog, ELK, etc: filtrar por requestId="abc" y ver todo el viaje de una solicitud. Sin esto, debugging en producción es arqueología.

UP/DOWN significa algo.

@Component
public class ArcaHealthIndicator implements HealthIndicator {

  private final Wsfev1Client wsfev1;
  private final TokenProvider tokens;

  @Override
  public Health health() {
    Map<String, Object> details = new HashMap<>();

    // Check 1: Token disponible y vigente
    try {
      TicketAcceso ta = tokens.get(cuit, "wsfe");
      details.put("tokenExpiresIn",
          Duration.between(Instant.now(), ta.expirationTime()).toMinutes() + "m");
    } catch (Exception e) {
      return Health.down().withDetail("token", e.getMessage()).build();
    }

    // Check 2: WSFEv1 responde a Dummy (operación health-only de ARCA)
    try {
      String resp = wsfev1.dummy();   // AppServer, DbServer, AuthServer = OK
      details.put("arcaStatus", resp);
      if (!resp.contains("OK")) {
        return Health.down().withDetails(details).build();
      }
    } catch (Exception e) {
      return Health.outOfService()
          .withDetails(details).withException(e).build();
    }

    return Health.up().withDetails(details).build();
  }
}

El método FEDummy de WSFEv1 existe para esto: verifica que los tres componentes de ARCA (AppServer, DbServer, AuthServer) estén OK. Es rápido y no usa créditos de rate limit.

Dashboard de una sola pantalla.

El sistema sigue, aunque ARCA no.

ARCA históricamente tiene 3-5 caídas significativas por año. Algunas duran horas. Tu POS no puede dejar de cobrar.

Decisión típica: implementás A para outages cortos (< 30 min) automáticamente, B como respaldo permanente, C como último recurso del operador humano.

Cuándo declarar a ARCA caído.

@Component
public class ArcaCircuitBreaker {

  private final MeterRegistry registry;
  private final SlidingWindowCounter errores = new SlidingWindowCounter(Duration.ofMinutes(5));
  private final SlidingWindowCounter totales = new SlidingWindowCounter(Duration.ofMinutes(5));
  private volatile Estado estado = Estado.CLOSED;

  public boolean permitir() {
    return estado != Estado.OPEN;
  }

  public void registrarExito() {
    totales.incr();
    if (estado == Estado.HALF_OPEN) {
      estado = Estado.CLOSED;
      log.info("Circuit breaker CLOSED");
    }
  }

  public void registrarFallo() {
    totales.incr();
    errores.incr();
    double tasaError = (double) errores.sum() / totales.sum();
    if (totales.sum() >= 10 && tasaError > 0.5) {
      if (estado != Estado.OPEN) {
        log.error("Circuit breaker OPEN. tasaError={}", tasaError);
        estado = Estado.OPEN;
        scheduleHalfOpen(Duration.ofSeconds(30));
      }
    }
  }

  private enum Estado { CLOSED, OPEN, HALF_OPEN }
}

Cuando el breaker está OPEN, el gateway no llama a ARCA — responde 503 inmediato al POS. Eso permite a ARCA recuperarse sin que vos lo bombardees con retries.

Aceptás la solicitud, avisás que va a tardar.

@PostMapping("/comprobantes")
public ResponseEntity<?> solicitar(...) {

  if (!circuitBreaker.permitir()) {
    // Modo cola: persistir como PENDING_QUEUED y devolver 202
    UUID id = caeService.encolarParaCuandoVuelva(s);
    return ResponseEntity.accepted()
        .header("Location", "/api/v1/comprobantes/" + id)
        .body(new EncoladoDto(id, "PENDING_QUEUED",
            "Solicitud en cola, ARCA temporalmente no disponible"));
  }

  // flujo normal
}

// Job que vacía la cola cuando ARCA vuelve
@Scheduled(fixedDelay = 30000)
public void procesarCola() {
  if (!circuitBreaker.permitir()) return;  // todavía caído

  List<Comprobante> encolados = repo.findByEstado("PENDING_QUEUED");
  for (Comprobante c : encolados) {
    try {
      caeService.procesar(reconstruirSolicitud(c));
    } catch (Exception e) {
      log.warn("Reintentar mañana: {}", c.id());
      break;  // si uno falla, ARCA volvió a caer, parar
    }
  }
}

Limitación: el POS espera un CAE para imprimir. Si encolás, no podés imprimir con número fiscal aún. El POS necesita estar diseñado para esto (poll-back o webhook). En la práctica para retail físico esto NO funciona — ahí necesitás CAEA.

Para outages largos, CAEA es la única salida.

CAEA: pedís a ARCA un código autorizador antes de necesitarlo. Te da 15 días para facturar. Después informás los comprobantes que usaste.

El sistema, resilient by design.

• Circuit breaker detecta outages automáticamente.
• Modo cola para outages cortos (< 30 min).
• Documentación de cómo activar CAEA manualmente para outages largos.
• Talonario manual documentado como último recurso.
• Tests que simulan ARCA caído (WireMock con delays y errores).
• Runbook: cuándo el operador decide cambiar de modo.

Infrastructure as code, no clics en consolas.

# terraform/main.tf
resource "aws_db_instance" "gateway" {
  identifier        = "arca-gw-prod"
  engine            = "sqlserver-ex"
  multi_az          = true
  backup_retention  = 7
}

resource "aws_secretsmanager_secret" "cert" {
  name = "arca-gw/cert-prod"
}

resource "aws_lb" "gateway" {
  internal = true   # solo desde VPN de POS
}

Cert de prod, manos humanas.

Tip: agregá al calendario una recordatorio "Cert ARCA prod vence en X días" con 60, 30 y 7 días de anticipación. Los certificados duran 2 años, fácil olvidarse hasta el día antes.

Treinta items para no olvidar nada.

Plan para volver atrás, probado.

# ROLLBACK_PLAN.md

## Cuándo ejecutar rollback
- Tasa de aprobación < 80% en los primeros 15 minutos.
- Errores transitorios > 30% por 5 minutos.
- Latencia p95 > 10s.
- Error masivo de auth (token rechazado).

## Quién decide
On-call engineer + tech lead, máximo 5 min de debate.
Si en duda: ROLLBACK. Mejor un rollback innecesario que
perder 1 hora de facturación.

## Pasos del rollback
1. ALB: weight nuevo deploy = 0%.
2. Verificar tráfico volvió a versión anterior (1 min).
3. Si los POS dependen del gateway nuevo:
   - opción A: revertir el código del cliente POS al estado anterior.
   - opción B: redirigir POS a sistema viejo (si todavía está vivo).
4. Comunicar incidente al equipo en canal #incidents.
5. Post-mortem dentro de 48hs.

## DB rollback
Las migraciones Flyway de este release son ADITIVAS.
No hay que revertir schema. Las nuevas columnas/tablas
quedan no usadas por la versión vieja.

## Comunicación a POS team
Template ya redactado en docs/incident-templates/

El gateway atiende tráfico real.

• Infraestructura en AWS via Terraform.
• Cert de producción obtenido y rotado correctamente.
• DB SQL Server Multi-AZ con backups automáticos.
• Deploy canary verificado antes de full rollout.
• Métricas y alertas en producción.
• Rollback plan documentado y simulado en staging.
• Primer comprobante real emitido en producción. Screenshot.

Para cada alerta, un playbook.

# docs/runbooks/cert-expirando.md

## Alerta: Cert ARCA vence en < 30 días

### Severidad
P3 (planificable, no urgente)

### Pre-requisitos
- Acceso a clave fiscal de la CUIT correspondiente.
- Acceso a Secrets Manager (rol SecretsAdmin).
- Una máquina con openssl.

### Pasos
1. Generar nueva clave privada:
   `openssl genrsa -aes256 -out gateway-prod-NEW.key 4096`

2. Generar CSR con CUIT real (ver docs/cuits.md):
   `openssl req -new -key gateway-prod-NEW.key -subj "..." -out new.csr`

3. Loguearse a ARCA con clave fiscal.
4. Ingresar a "Administrador de Certificados Digitales".
5. Subir el CSR. Descargar el .crt.
6. Asociar el cert al servicio "wsfe".
7. Crear PKCS12: openssl pkcs12 -export -in new.crt -inkey ... -out new.p12
8. Subir new.p12 a Secrets Manager (nueva versión).
9. Rolling restart de las instancias del gateway.
10. Verificar emisión de comprobante de prueba.
11. Revocar cert viejo en ARCA (después de 24hs de estabilidad).

### Verificación de éxito
- 1 comprobante de prueba emitido OK.
- Métrica `arca_cae_aprobados_total` sigue incrementando.
- Logs sin errores de "cms.bad" o similares.

### Si algo sale mal
- Rollback: restaurar versión anterior del secret.
- Rolling restart con la versión anterior del secret.
- Contactar: tech-lead + counter consultor fiscal.

Cada uno con su playbook.

Cinco minutos de check matinal.

El objetivo es que esto sea aburrido. Sistema bien construido = mañanas tranquilas. Sistema con shortcuts = mañanas con sorpresas.

Documentación que trabaja por vos.

• 10 runbooks documentados, uno por alerta común.
• Procedimiento de rotación de certificados probado en ambiente de homologación primero.
• Check matinal de 5 min definido.
• Post-mortem template listo para incidentes.
• Calendario con recordatorios de vencimientos y mantenimientos.
• Onboarding doc para nuevos miembros del equipo.

El MVP es el comienzo, no el final.

Lecciones que trascienden el caso.

• Plan es el 40% del trabajo, no el 5%. Cada hora gastada en SPEC y ADR vale 5 horas de código mal escrito.
• Steer es continuo. CLAUDE.md no se escribe una vez. Se actualiza cada vez que el agente alucina o se desvía. Va creciendo.
• Decompose es donde te juzgan. Specs ambiguas o gigantes generan output que no podés revisar. Specs chicas y precisas generan progreso medible.
• Delegate ≠ abandonar. Vos seguís siendo el dueño del diseño, el agente es un ejecutor muy rápido. La firma CMS, la lógica fiscal, la config de prod: no se delegan jamás.
• Systematize es lo que separa POC de producto. Tests, evals, métricas, runbooks. Sin esto, lo que construiste se rompe en producción y no podés repararlo.

Construir el gateway sin Claude Code te hubiera tomado semanas de trabajo manual y hubieras cometido la mayoría de los errores que evitamos. Construirlo a "ver qué hace el agente" te hubiera dado un código basura imposible de mantener. El framework es el camino del medio: alta velocidad sin sacrificar calidad.

Anexo B completado.

Tenés un gateway POS para CAE en ARCA, end-to-end, en producción, operable, mantenible, con tests, evals, observabilidad, runbooks.

Un vault de notas con prompts integrados.

Obsidian (o cualquier sistema de notas en markdown). El objetivo: capturar, procesar, crear sin volver a empezar de cero cada vez.

# Template: spec.md

---
spec_id: SPEC-{{id}}
feature: {{nombre}}
estado: draft | active | done
prioridad: P0 | P1 | P2
---

## Contexto
{{¿Qué problema resuelve? ¿Por qué ahora?}}

## Comportamiento
1. ...
2. ...

## Out of scope
- ...

## Tests requeridos
- ...

## Definición de hecho
- ...

Iteración con humanos reales.

No necesitás seguir cada anuncio.

Un buen sistema de ingeniería con AI te hace agnóstico a la herramienta. Cuando sale algo nuevo, lo evaluás con criterio en vez de con ansiedad.

El curso, en una sola pantalla.

Total: ~6 horas de contenido + práctica al ritmo de cada uno. Stack: Java 21, Spring Boot, SQL Server, Astro. Tool: Claude Code. v1.1 — revisada en junio 2026 tras el lanzamiento de Claude Fable 5: la tesis sobrevivió a su primer cambio de modelo.