🇨🇱 SII Chile Pre IVA

Actor de Apify para automatizar la preparación del IVA mensual extrayendo el Registro de Compras y Ventas (RCV) y generando el Formulario 29 completo del Servicio de Impuestos Internos (SII) de Chile.

Perfecto para contadores, empresas y desarrolladores que necesitan automatizar la preparación de declaraciones mensuales de IVA.

✨ Características Principales

📊 Extracción Completa de Datos

• ✅ Registro de Compras y Ventas (RCV) con resúmenes por tipo de documento
• ✅ Formulario 29 Completo con todos los códigos tributarios
• ✅ Cálculo Automático de IVA (Débito, Crédito, Determinado)
• ✅ Remanente Acumulado con persistencia automática entre períodos
• ✅ PPM (Pago Provisional Mensual) calculado al 2% de ventas

🔢 Códigos del Formulario 29 Incluidos

Código	Descripción	Fuente
502	IVA Débito Fiscal (Facturas)	RCV
510	Notas de Crédito Ventas	RCV
513	Notas de Débito Ventas	RCV
538	Total Débito Fiscal	Calculado
520	IVA Crédito Fiscal (Facturas)	RCV
528	Notas de Crédito Compras	RCV
532	Notas de Débito Compras	RCV
535	DIN (Declaración de Ingreso)	RCV
504	Remanente Mes Anterior	Período N-1
537	Total Crédito Fiscal	Calculado
89	IVA Determinado	Calculado
50	Remanente Acumulado	Persistido
49	Retención 3%	F29 HTML ⚠️
48	Impuesto Único 2da Cat.	F29 HTML ⚠️
756	IVA Postergado	F29 HTML
151	Retención de Honorarios	Boletas Electrónicas
62	PPM (2% ventas)	Calculado
91	TOTAL A PAGAR	Calculado

⚠️ Nota: Los códigos 048 y 049 actualmente están en desarrollo (código parcialmente funcional en standby).

🏗️ Arquitectura Profesional

• ✅ Clean Architecture con servicios independientes
• ✅ TypeScript Strict Mode con validación Zod
• ✅ Manejo Robusto de Errores con screenshots automáticos
• ✅ Protección Anti-Modales del SII
• ✅ Logging Detallado para debugging
• ✅ Servicios Modulares:
  • RCVService: Extracción de Registro de Compras y Ventas
  • F29Service: Códigos 048, 049, 756 del Formulario 29
  • BoletasService: Código 151 de Retención de Honorarios

🔐 Seguridad y Fiabilidad

• ✅ Autenticación automática con RUT y Clave Tributaria
• ✅ Validación de RUT chileno con dígito verificador
• ✅ Soporte para proxies chilenos (recomendado)
• ✅ Manejo de sesiones independientes por servicio
• ✅ Protección de credenciales con secretos de Apify

🚀 Uso Rápido

En Apify Console

1. Ve a Apify Console 2. Busca el Actor "SII Chile Pre IVA"
2. Configura el input:

{
  "rut": "76515462-6",
  "password": "tu_clave_tributaria",
  "periodo": "202510"
}

4. ¡Ejecuta y obtén tu Formulario 29 completo!

Via API

curl -X POST https://api.apify.com/v2/acts/YOUR_ACTOR_ID/runs \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rut": "76515462-6",
    "password": "tu_clave_tributaria",
    "periodo": "202510"
  }'

Usando el SDK de Apify (Node.js/TypeScript)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: 'YOUR_API_TOKEN',
});

// Ejecutar el actor
const run = await client.actor('YOUR_ACTOR_ID').call({
  rut: '76515462-6',
  password: 'tu_clave_tributaria',
  periodo: '202510', // Octubre 2025
});

// Obtener resultados
const { items } = await client.dataset(run.defaultDatasetId).listItems();
const formulario29 = items[0].f29Completo;

console.log('Total a Pagar:', formulario29.Compras['Codigo 91'].valor);

📥 Input Schema

Campo	Tipo	Requerido	Descripción	Ejemplo
rut	string	✅	RUT sin puntos, con guión	"76515462-6"
password	string	✅	Clave tributaria del SII	"miClave123"
periodo	string	✅	Período en formato YYYYMM	"202510"
proxyConfiguration	object	❌	Configuración de proxy	Ver abajo

Formato del Período

• YYYYMM: Año (4 dígitos) + Mes (2 dígitos)
• Ejemplo: 202510 = Octubre 2025
• Ejemplo: 202412 = Diciembre 2024

Configuración de Proxy (Recomendado)

{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "CL"
  }
}

📤 Output Schema

El actor devuelve un objeto completo con:

1. Formulario 29 Completo (f29Completo)

{
  "periodo": "10-2025",
  "Ventas": {
    "Codigo 502": { "descripcion": "IVA FACTURA", "valor": 12484187 },
    "Codigo 759": { "descripcion": "BOLETAS", "valor": 0 },
    "Codigo 510": { "descripcion": "N.C", "valor": -1557665 },
    "Codigo 513": { "descripcion": "N.D", "valor": 0 },
    "Codigo 538": { "descripcion": "TOTAL DÉBITO", "valor": 10926522 }
  },
  "Compras": {
    "Codigo 520": { "descripcion": "IVA Factura Electronica", "valor": 8069290 },
    "Codigo 532": { "descripcion": "NOTA DE DEBITO", "valor": 0 },
    "Codigo 528": { "descripcion": "NOTA DE CRÉDITO", "valor": 0 },
    "Codigo 535": { "descripcion": "DIN", "valor": 0 },
    "Codigo 504": { "descripcion": "REMANENTE", "valor": 8069290 },
    "Codigo 537": { "descripcion": "TOTAL CRÉDITO", "valor": 8069290 },
    "Codigo 89": { "descripcion": "IVA determinado", "valor": -5212058 },
    "Codigo 50": { "descripcion": "REMANENTE ACUMULADO", "valor": 5212058 },
    "Codigo 756": { "descripcion": "IVA POSTERGADO", "valor": 0 },
    "Codigo 49": { "descripcion": "RETENCIÓN 3%", "valor": 0 },
    "Codigo 48": { "descripcion": "IMPUESTO ÚNICO", "valor": 0 },
    "Codigo 151": { "descripcion": "RETENCIÓN DE HONORARIOS", "valor": 546897 },
    "Codigo 62": { "descripcion": "PPM", "valor": 1478089.42 },
    "Codigo 91": { "descripcion": "TOTAL A PAGAR", "valor": 0 }
  }
}

2. Datos Originales del SII (datosOriginales)

{
  "periodo": "202510",
  "compras": [
    {
      "tipoDocumento": "33 - FACTURA ELECTRONICA",
      "cantidadDocumentos": 12,
      "montoExento": 0,
      "montoNeto": 42470000,
      "montoIvaRecuperable": 8069300,
      "montoIvaNoRecuperable": 0,
      "montoIvaUsoComun": 0,
      "montoIvaActFijo": 0,
      "montoTotal": 50539300
    }
    // ... más documentos
  ],
  "ventas": [
    {
      "tipoDocumento": "33 - FACTURA ELECTRONICA",
      "cantidadDocumentos": 120,
      "montoExento": 0,
      "montoNeto": 65706250,
      "montoIVA": 12484187,
      "montoTotal": 78190437
    }
    // ... más documentos
  ],
  "remanentePeriodoAnterior": 8069290,
  "ivaDeterminadoPeriodoAnterior": -8069290
}

🔧 Desarrollo Local

Requisitos

• Node.js 18+ o 20+
• npm o yarn
• Apify CLI (opcional)

Instalación

# Clonar el repositorio
git clone https://github.com/yourusername/apify-sii-scraper.git
cd apify-sii-scraper

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

Ejecutar Localmente

Opción 1: Con Apify CLI (Recomendado)

# Instalar Apify CLI
npm install -g apify-cli

# Login (solo primera vez)
apify login

# Ejecutar localmente
apify run

Opción 2: Con npm

# Configurar input en .actor/INPUT.json
npm run dev

Input Local (.actor/INPUT.json)

{
  "rut": "76515462-6",
  "password": "tu_clave_tributaria",
  "periodo": "202510"
}

🚀 Deploy a Apify

Método 1: Apify CLI

# Push al registry de Apify
apify push

Método 2: GitHub Integration

1. Conecta tu repositorio GitHub a Apify Console
2. Cada push a main desplegará automáticamente

Método 3: Manual Upload

1. Compila el proyecto: npm run build
2. Sube dist/ y package.json en Apify Console

📊 Casos de Uso

1. Integración con Backend (NestJS)

// backend/src/services/sii.service.ts
import { Injectable } from '@nestjs/common';
import { ApifyClient } from 'apify-client';

@Injectable()
export class SIIService {
  private client: ApifyClient;

  constructor() {
    this.client = new ApifyClient({
      token: process.env.APIFY_TOKEN,
    });
  }

  async generarFormulario29(rut: string, password: string, periodo: string) {
    const run = await this.client.actor('YOUR_ACTOR_ID').call({
      rut,
      password,
      periodo,
    });

    const { items } = await this.client
      .dataset(run.defaultDatasetId)
      .listItems();

    return items[0];
  }
}

2. Endpoint API REST

// backend/src/controllers/f29.controller.ts
import { Controller, Post, Body } from '@nestjs/common';

@Controller('sii')
export class F29Controller {
  constructor(private siiService: SIIService) {}

  @Post('formulario-29')
  async obtenerF29(@Body() body: { rut: string; password: string; periodo: string }) {
    const resultado = await this.siiService.generarFormulario29(
      body.rut,
      body.password,
      body.periodo
    );

    return {
      success: true,
      data: resultado.f29Completo,
      totalAPagar: resultado.f29Completo.Compras['Codigo 91'].valor,
    };
  }
}

3. Scheduled Run (Mensual Automático)

// Programar ejecución automática el día 5 de cada mes
const schedule = await client.schedules().create({
  actorId: 'YOUR_ACTOR_ID',
  name: 'Formulario 29 Mensual',
  cronExpression: '0 9 5 * *', // Día 5 de cada mes a las 9 AM
  input: {
    rut: '76515462-6',
    password: process.env.SII_PASSWORD, // Usar secret
    // periodo se auto-calcula al mes anterior
  },
});

4. Frontend React

// frontend/src/hooks/useFormulario29.ts
import { useState } from 'react';
import { ApifyClient } from 'apify-client';

export const useFormulario29 = () => {
  const [loading, setLoading] = useState(false);
  const [data, setData] = useState(null);

  const generarF29 = async (rut: string, password: string, periodo: string) => {
    setLoading(true);
    
    const client = new ApifyClient({ token: process.env.REACT_APP_APIFY_TOKEN });
    const run = await client.actor('YOUR_ACTOR_ID').call({
      rut,
      password,
      periodo,
    });

    const { items } = await client.dataset(run.defaultDatasetId).listItems();
    setData(items[0]);
    setLoading(false);
  };

  return { generarF29, loading, data };
};

⚠️ Manejo de Errores

El actor incluye manejo robusto de errores con códigos específicos:

Código	Descripción	Solución
LOGIN_ERROR	Error en autenticación	Verificar RUT y clave tributaria
INVALID_RUT	Formato de RUT inválido	Usar formato sin puntos: 12345678-9
NAVIGATION_ERROR	Error navegando al módulo	Verificar conexión/proxy
EXTRACTION_ERROR	Error extrayendo datos	Verificar que el período tenga datos
EXECUTION_ERROR	Error general de ejecución	Ver screenshot de error

Screenshot Automático

En caso de error, se guarda un screenshot en el Key-Value Store:

const screenshot = await Actor.getValue('ERROR_SCREENSHOT');
// screenshot es un Buffer con la imagen PNG

🔐 Seguridad y Buenas Prácticas

1. NUNCA Hardcodear Credenciales

❌ MAL:

const password = 'miClaveSecreta123'; // ¡NO HAGAS ESTO!

✅ BIEN:

const password = process.env.SII_PASSWORD; // Variable de entorno
// O usando secretos de Apify:
const password = await Actor.getValue('SII_PASSWORD');

2. Usar Proxies Chilenos

El SII puede bloquear IPs extranjeras. Usa proxies chilenos:

{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "CL"
  }
}

3. Rate Limiting

No ejecutes el scraper más de una vez cada 5 minutos para el mismo RUT. El SII tiene rate limiting.

4. Almacenamiento Seguro

Los datos del Formulario 29 son sensibles. Usa:

• Encriptación en reposo
• HTTPS para transmisión
• Acceso restringido con autenticación

5. Cumplimiento Legal

Este scraper es para uso legítimo de contribuyentes que tienen derecho legal a acceder a sus propios datos tributarios. No debe usarse para:

• Acceso no autorizado a datos de terceros
• Evasión tributaria
• Cualquier actividad ilegal

📝 Notas Importantes

1. Periodo de Datos: Solo puedes extraer datos de períodos con información registrada en el SII.

2. Remanente Acumulado: Se persiste automáticamente entre ejecuciones usando Apify Key-Value Store.

3. Código 048 y 049: Actualmente en desarrollo. Los demás códigos están 100% funcionales.

4. Cambios en el SII: Si el SII actualiza su interfaz, puede requerirse actualización del actor.

5. Tiempo de Ejecución: Aproximadamente 2-3 minutos por ejecución completa.

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama: git checkout -b feature/AmazingFeature
3. Commit: git commit -m 'feat: Add amazing feature'
4. Push: git push origin feature/AmazingFeature
5. Abre un Pull Request

Conventional Commits

Usamos Conventional Commits:

• feat: Nueva funcionalidad
• fix: Corrección de bug
• docs: Cambios en documentación
• refactor: Refactorización de código
• test: Agregar o modificar tests
• chore: Mantenimiento

📄 Licencia

MIT License - Ver archivo LICENSE

🆘 Soporte

• Issues: GitHub Issues
• Email: hola@sevenscale.io
• Website: sevenscale.io
• Documentación SII: SII Chile

🔗 Links Útiles

• Apify Documentation
• Playwright Documentation
• SII Chile
• Formulario 29 - Información Oficial
• TypeScript Handbook

📈 Roadmap

• Extracción RCV (Compras y Ventas)
• Códigos básicos del F29
• Remanente acumulado con persistencia
• Código 151 (Retención Honorarios)
• Código 756 (IVA Postergado)
• PPM (Pago Provisional Mensual)
• Arquitectura modular con servicios
• Código 048 (Impuesto Único) - En desarrollo
• Código 049 (Retención 3%) - En desarrollo
• Exportación a PDF del F29
• Dashboard de visualización
• Comparación multi-período
• API REST standalone
• Integración con sistemas contables

---

Desarrollado con ❤️ por SevenScale.io

Automatizando la contabilidad tributaria chilena, un formulario a la vez.

SevenScale.io - Soluciones de automatización y scraping profesional para empresas.