Declaraciones API

Propósito

Endpoints que generan, calculan y persisten las declaraciones tributarias que la empresa presenta al SII: F29 (IVA mensual) y declaraciones juradas anuales 1879 (honorarios pagados) y 1887 (sueldos pagados). Cada declaración consolida datos del periodo desde otros dominios (operaciones, honorarios, remuneraciones) y produce un archivo descargable para presentar.

Mapa de Familias

Familia	Prefijo	Router	Servicio responsable
F29 (IVA mensual)	/api/declaraciones/f29	routes/declaraciones/f29.ts	DeclaracionesService
DJ 1879 (honorarios)	/api/declaraciones-juradas/1879	routes/declaraciones_juradas/dj1879.ts	DeclaracionesService
DJ 1887 (sueldos)	/api/declaraciones-juradas/1887	routes/declaraciones_juradas/dj1887.ts	DeclaracionesService

Formulario 29 (IVA mensual)

Método	Ruta	Uso
GET	/api/declaraciones/f29	Lista F29 generados con filtros por año y estado.
GET	/api/declaraciones/f29/:periodo	Obtiene F29 de un periodo (formato YYYY-MM).
POST	/api/declaraciones/f29/calcular	Calcula el F29 del periodo desde las operaciones (preview, no persiste).
POST	/api/declaraciones/f29/generar	Persiste el F29 calculado y genera el archivo SII.
GET	/api/declaraciones/f29/:periodo/pdf	Descarga el F29 en PDF.

Preview F29

curl -X POST "http://localhost:8000/api/declaraciones/f29/calcular?periodo=2026-05" \
  -b cookies.txt

Response 200

{
  "success": true,
  "data": {
    "periodo": "2026-05",
    "iva_debito": 1900000,
    "iva_credito": 1200000,
    "iva_a_pagar": 700000,
    "ppm": 350000,
    "total_a_pagar": 1050000,
    "estado": "PREVIEW"
  }
}

Declaración Jurada 1879 (Honorarios)

Reporta los honorarios pagados a profesionales durante el año tributario, con las retenciones del 10% (2 cat).

Método	Ruta	Uso
GET	/api/declaraciones-juradas/1879	Lista DJ 1879 generadas.
GET	/api/declaraciones-juradas/1879/:año	Obtiene DJ 1879 del año tributario.
POST	/api/declaraciones-juradas/1879/calcular	Calcula la DJ 1879 desde los honorarios del año (preview).
POST	/api/declaraciones-juradas/1879/generar	Persiste y genera archivo SII.
GET	/api/declaraciones-juradas/1879/:año/archivo	Descarga el archivo en formato del SII.

Declaración Jurada 1887 (Sueldos)

Reporta los sueldos y remuneraciones pagadas a empleados durante el año tributario.

Método	Ruta	Uso
GET	/api/declaraciones-juradas/1887	Lista DJ 1887 generadas.
GET	/api/declaraciones-juradas/1887/:año	Obtiene DJ 1887 del año tributario.
POST	/api/declaraciones-juradas/1887/calcular	Calcula la DJ 1887 desde las liquidaciones del año (preview).
POST	/api/declaraciones-juradas/1887/generar	Persiste y genera archivo SII.
GET	/api/declaraciones-juradas/1887/:año/archivo	Descarga el archivo en formato del SII.

Convenciones

• Periodo F29: formato YYYY-MM (mes tributario).
• Año DJ: año tributario (entero), no calendario.
• Preview vs. Generación: calcular no persiste y permite iterar; generar cierra la declaración y produce el archivo final.
• Las declaraciones generadas son inmutables; correcciones se hacen vía rectificatoria (no documentado aún en API).