Saltar a contenido

Guías de tareas

Recetas concretas para tareas puntuales. A diferencia de la Referencia (que describe qué hay) o de Entender el sistema (que explica por qué), acá el foco es cómo hago X, paso a paso.

Casi todo esto pega contra AFIP homologación

Las recetas de CAE/CAEA asumen el perfil dev (AFIP en HOMOLOGACION) y el backend arriba. Nunca corras un "test de prueba" apuntando a producción: algunos endpoints emiten comprobantes reales. Si no tenés el backend levantado, mirá primero Setup del entorno.

Backend

Emitir un CAE de prueba

Emite una Factura B de Consumidor Final por $121 (neto 100 + IVA 21) contra AFIP homologación, para un POS configurado.

  1. Asegurate de tener un SucPosPV cargado (ver más abajo) y de saber su suc/pos.
  2. Pegale al test runner del cockpit: 
    curl -X POST http://localhost:8080/api/cockpit/test/cae ^
  -H "Content-Type: application/json" ^
  -d "{\"suc\": 1, \"pos\": 1}"
  3. La respuesta trae {ok, durationMs, comprobante, cae, resultado, caeFchVto, traffic}. resultado: "A" = aprobado. El bloque traffic tiene el XML SOAP exacto que se mandó/recibió de ARCA.

Probar el anti-doble-facturación

Reenviá el mismo nroTicketPos y vas a recibir el CAE existente en vez de uno nuevo: ejercita la idempotencia del flujo real (fecaeSolicitarNextGen). 

curl -X POST http://localhost:8080/api/cockpit/test/cae ^
  -H "Content-Type: application/json" ^
  -d "{\"suc\": 1, \"pos\": 1, \"nroTicketPos\": \"TICKET-DEMO-001\"}"

Es un CAE real en homologación

El backend loguea un WARN ruidoso ([COCKPIT-CAE-PRUEBA] EMITIENDO CAE REAL…). Solo usalo en el ambiente de prueba. Detalle en Cockpit.

Configurar un SucPosPV

SucPosPV mapea sucursal + POS físico → punto de venta AFIP. El ABM va gateado por secret.

  1. Definí el secret al arrancar (env var COCKPIT_ADMIN_SECRET, ya está en run.bat). Sin secret, el ABM responde 503.
  2. Dá de alta el mapeo (mandando el secret en el header X-Cockpit-Secret): 
    curl -X POST http://localhost:8080/api/cockpit/sucpospv ^
  -H "X-Cockpit-Secret: %COCKPIT_ADMIN_SECRET%" ^
  -H "Content-Type: application/json" ^
  -d "{\"suc\": 1, \"pos\": 1, \"pvcae\": 3, \"pvcaea\": 4}"
    pvcaea es opcional (un POS puede facturar solo CAE).
  3. Verificá la lista: 
    curl http://localhost:8080/api/cockpit/sucpospv -H "X-Cockpit-Secret: %COCKPIT_ADMIN_SECRET%"
  4. (Opcional) Validá los PV contra AFIP a demanda: 
    curl -X POST http://localhost:8080/api/cockpit/sucpospv/1/validar-arca ^
  -H "X-Cockpit-Secret: %COCKPIT_ADMIN_SECRET%"
    409 = el PV no existe o está bloqueado en AFIP; 502 = AFIP no respondió.

Detalle de códigos y revalidación en Cockpit.

Correr el smoke contra AFIP homologación

El smoke pega contra la red real de AFIP con el cert .p12. Está gateado (@EnabledIfSystemProperty): no corre en el mvn test normal.

:: atajo del repo (equivale al comando de abajo)
tt.bat

:: o explícito:
mvn -o test -Dtest=AfipHomologacionSmokeTest -Dafipsmoke=true -Dafip.p12.password=<clave-del-p12>

AfipHomologacionSmokeTest hace el flujo end-to-end de lectura: WSAA LoginCms (firma CMS → token) + WSFE FECompUltimoAutorizado (read-only, no emite).

El TA tiene cooldown — corré el smoke UNA vez

AFIP rechaza el re-login si ya hay un TA vigente ("ya posee un TA valido") por ~12 h. El propio test lo avisa. No lo corras en loop. La clave del .p12 va por system property (-Dafip.p12.password=…), nunca en el repo.

Hay smoke tests hermanos para otros flujos: CaeaHomologacionSmokeTest (CAEA) y, contra DB real, CockpitRealDbSmokeTest / RealDbSchemaValidationTest (perfil realdb, gateados aparte).

Ver el estado de los jobs

curl http://localhost:8080/api/cockpit/jobs

Devuelve una fila por job con cron, ultimaEjecucion, resultado (OK/ERROR), error y proximaEjecucion. Para entender qué hace cada job y cómo dar de alta uno nuevo, mirá Jobs Quartz.

Documentación

Correr esta doc en local

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
mkdocs serve

Abrí http://127.0.0.1:8000. mkdocs serve recarga en vivo al editar.

Antes de pushear:

mkdocs build --strict

Exportar la doc a un PDF

El sitio se exporta a un único PDF (con portada, índice y los diagramas Mermaid renderizados) vía mkdocs-exporter. La primera vez hay que instalar el Chromium headless:

pip install -r requirements.txt
python -m playwright install chromium

El export está desactivado por defecto (para que serve/build sean rápidos). Se activa con la variable PDF_EXPORT:

$env:PDF_EXPORT = "true"; mkdocs build

El PDF queda en site/pdf/tifacturaonline-documentacion.pdf.

Mermaid y el separador ;

Mermaid usa ; como separador de sentencias: no uses ; dentro del texto de un nodo o el diagrama no compila (usá <br/> para saltos de línea). La portada vive en pdf-cover.html y el hook que renderiza Mermaid en el PDF es docs/assets/wait-mermaid.js — no lo borres.

Por dónde seguir