arca-facturacion

name	arca-facturacion
description	Facturación argentina vía ARCA/AFIP WSAA/WSFEv1: comprobantes, receptores dinámicos, CAE, QR/PDF y automatización reusable.
version	0.2.0
author	ARCA Facturación contributors
license	MIT
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["argentina","afip","arca","facturacion","wsfe","wsaa","cae"]}}

ARCA Facturación

Skill para operar facturación argentina programáticamente por web services oficiales ARCA/AFIP.

Visión: ver VISION.md. La meta es que esta sea la skill definitiva para facturar en ARCA, empezando por comprobantes clase C y evolucionando hacia un proyecto OSS genérico.

Capacidades actuales

• WSAA: autenticación con certificado X.509 + firma CMS/PKCS#7.
• WSFEv1: consulta de último comprobante y solicitud de CAE.
• Receptor dinámico por CLI: CUIT/DNI/Consumidor Final, razón social, domicilio, condición IVA.
• CondicionIVAReceptorId incluido en el request.
• Tipo de comprobante configurable con --tipo-cbte — default 11.
• PDF con QR oficial según esquema ARCA/AFIP.
• Logs locales sin imprimir token/sign.
• Directorio de datos externo al código: no hardcodear datos fiscales ni credenciales.

Cuándo usarla

Usar esta skill cuando el usuario pida emitir, probar, consultar o automatizar comprobantes ARCA/AFIP; por ejemplo: facturar a una S.A., consultar último comprobante, preparar certificado, validar receptor o generar PDF/QR.

Directorio de datos

Preferido:

export ARCA_HOME=~/arca

Compatibilidad:

export AFIP_HOME=~/arca

Estructura esperada:

$ARCA_HOME/
├── emisor_config.json
├── certs/
│   ├── private_key.key
│   ├── request.csr                 # generado localmente, se sube a ARCA
│   ├── certificate.crt             # descargado desde ARCA luego del login
│   └── token_cache.json            # autogenerado
└── comprobantes_log.json           # autogenerado

emisor_config.json mínimo:

{
  "cuit": "20XXXXXXXXX",
  "punto_venta": 1,
  "razon_social": "APELLIDO NOMBRE",
  "condicion_iva": "Responsable Monotributo",
  "domicilio": "Domicilio fiscal/comercial",
  "ingresos_brutos": "Exento",
  "inicio_actividades": "DD/MM/YYYY"
}

Comandos principales

Desde el directorio de la skill:

export ARCA_HOME=~/arca
bash scripts/run_arca.sh diagnostico

Construir payload offline — no emite:

bash scripts/run_arca.sh build-request \
  --tipo-cbte 11 \
  --monto 1 \
  --descripcion "Prueba de facturación" \
  --concepto 1 \
  --receptor-doc-tipo 80 \
  --receptor-doc-nro 30XXXXXXXXX \
  --receptor-nombre "CLIENTE S.A." \
  --receptor-condicion-iva-id 1 \
  --receptor-domicilio "Domicilio fiscal del cliente"

Emitir con CAE — irreversible:

bash scripts/run_arca.sh emitir \
  --tipo-cbte 11 \
  --monto 1 \
  --descripcion "Prueba de facturación" \
  --concepto 1 \
  --receptor-doc-tipo 80 \
  --receptor-doc-nro 30XXXXXXXXX \
  --receptor-nombre "CLIENTE S.A." \
  --receptor-condicion-iva-id 1 \
  --receptor-domicilio "Domicilio fiscal del cliente" \
  --condicion-venta "Transferencia Bancaria" \
  --pdf-path "$ARCA_HOME/comprobantes/comprobante_011_00001_00000001.pdf" \
  --yes

Notas:

• Si no se pasa --condicion-venta, el PDF/log usan default Contado; copiar la condición del draft anterior cuando corresponda.
• Si no se pasa --pdf-path, el PDF se genera relativo al working directory del comando. Para artefactos finales, usar una ruta absoluta bajo $ARCA_HOME/comprobantes/ y verificarla con stat/file.
• --receptor-doc-tipo 80 = CUIT.
• --receptor-condicion-iva-id 1 suele corresponder a Responsable Inscripto.
• Consumidor Final: --receptor-doc-tipo 99 --receptor-doc-nro 0 --receptor-condicion-iva-id 5.
• Si --concepto 2 o 3, agregar --desde YYYY-MM-DD --hasta YYYY-MM-DD.
• El agente debe mostrar siempre un draft completo de la factura/comprobante al usuario antes de emitir: emisor, punto de venta, tipo, receptor, concepto, descripción, período, monto e IVA. Emitir sin haber mostrado el draft en el chat es incorrecto.
• El agente debe contar con autorización explícita después de mostrar el draft antes de ejecutar emitir --yes.
• --sin-pdf evita generar PDF.

Workflow del agente

1. Verificar prerequisitos:

   bash scripts/run_arca.sh diagnostico
   

2. Verificar el punto de venta real antes de emitir:

   bash scripts/run_arca.sh ultimo --tipo-cbte 11
   

   Si aparece WSFE 11002 o FEParamGetPtosVenta devuelve 602, revisar la constancia de alta de punto de venta y seguir references/punto-venta-wsfe-troubleshooting.md. No asumir que el número indicado informalmente es correcto.
3. Si faltan datos/certificados/dependencias, pedir exactamente lo faltante.
4. Antes de emitir, mostrar resumen:
   • CUIT emisor y punto de venta.
   • tipo de comprobante.
   • receptor: doc tipo/nro, nombre, condición IVA.
   • monto, concepto, descripción, fechas si aplica.
5. Emitir con --yes solo después de confirmación explícita posterior al draft, salvo que el usuario ya haya dicho explícitamente que emitas ese draft exacto.
6. Verificar post-emisión antes de responder: correr ultimo --tipo-cbte ... para confirmar que WSFE avanzó al número emitido, revisar comprobantes_log.json para CAE/vencimiento/receptor/monto, y verificar que el PDF exista y sea válido (stat/file) si se generó.
7. Reportar número, CAE, vencimiento, PDF/log y la verificación real observada.

Archivos útiles

• VISION.md — visión y criterios de arquitectura.
• scripts/comprobantes.py — CLI principal genérico.
• scripts/wsaa.py — autenticación WSAA.
• scripts/config.py — config local.
• scripts/pdf.py — PDF + QR.
• scripts/ssl_compat.py — sesión HTTPS compatible con ARCA.
• scripts/generar_certificado.sh — private key + CSR.
• scripts/run_arca.sh — wrapper con venv.
• references/setup.md — setup inicial.
• references/receiver-codes.md — códigos frecuentes.
• references/punto-venta-wsfe-troubleshooting.md — diagnóstico de punto de venta Web Services cuando WSFE devuelve 11002/602.
• references/live-emission-safety.md — secuencia segura para emitir en vivo: diagnosticar, confirmar punto de venta, mostrar draft, emitir con autorización explícita y verificar ultimo/log/PDF antes de reportar éxito.
• references/github-sync.md — checklist e instrucciones para publicar/sincronizar el proyecto en GitHub sin filtrar secretos.
• references/oss-roadmap.md — roadmap OSS.
• references/oss-publication-checklist.md — checklist before publishing: README/LICENSE/.gitignore, secret/artifact scan, ignore verification, tests and initial commit.