sii

CLI + servidor MCP para automatizar interacciones rutinarias con el SII de Chile (Servicio de Impuestos Internos), para un único usuario que actúa sobre su propio RUT (o una empresa que representa legalmente).

• sii — la CLI (basada en Typer)
• sii-mcp — el servidor Model Context Protocol (FastMCP, stdio)

El mismo motor sii.core respalda ambos frontends, así que las salvaguardas legales y operativas (throttling por RUT, log de auditoría, manejo de credenciales, ciclo de vida de la sesión) aplican sin importar si quien lo usa es una persona o un asistente de IA.

Estado

Orientado a producción — solo prod por defecto, sin sandbox de certificación (ADR-016). Implementado de punta a punta contra el portal real del SII:

• auth — login interactivo + lectura de identidad (login / login --browser / status [--refresh] / logout). --browser abre un navegador donde tipeas la Clave en el SII (nunca en la terminal ni en el chat; cookies-only, no toca el keyring). status --refresh reporta también el régimen tributario.
• profile — snapshot completo del contribuyente (incluye PII).
• rcv — Registro de Compras y Ventas: summary (un período, --year, o rango --from/--to) + list (filas por DTE) + match (reconciliar un folio).
• f29 — Declaración Mensual de IVA: draft (la propuesta pre-llenada) + status (estado de la declaración presentada). Solo lectura.
• dte — authorized: tipos de DTE que un RUT está autorizado a emitir. Consulta pública (sin login, sirve para cualquier RUT, incluidas contrapartes).
• bte — list: Boletas de Honorarios Electrónicas (recibidas / emitidas), resumen anual (--year) o detalle mensual (--period).

DTE con firma (factura electrónica, SOAP), f29 submit, bte emit, la carpeta tributaria completa y F22 (renta) están en el docs/ROADMAP.md y como issues de GitHub.

Instalación

Requiere Python 3.12+. Se instala directo desde PyPI, sin clonar el código:

# Como herramienta aislada (recomendado) — con uv o pipx:
uv tool install sii-cli
pipx install sii-cli

# O en tu entorno/venv actual con pip:
pip install sii-cli

Luego instala una sola vez el navegador headless que usa el portal (~150 MB):

uvx --from sii-cli playwright install chromium
# (si instalaste con pip dentro de un venv, basta:  playwright install chromium)

Esto deja los comandos sii y sii-mcp disponibles en tu PATH.

¿Solo quieres probarla sin instalar nada? Ejecútala efímera con uv:

uvx --from sii-cli sii status

Desde el código (desarrollo)

git clone https://github.com/albertomarturelo/sii-cli
cd sii-cli
uv sync
uv run playwright install chromium
# ejecuta con:  uv run sii ...

Actualización

Para subir a la última versión publicada en PyPI, según cómo la instalaste:

# uv (herramienta aislada):
uv tool upgrade sii-cli

# pipx:
pipx upgrade sii-cli

# pip (dentro de tu entorno/venv):
pip install -U sii-cli

¿Solo quieres correr la última sin tocar tu instalación? Ejecútala efímera:

uvx --from sii-cli@latest sii version

Comprueba qué versión tienes instalada con sii version (o sii --version / sii -V).

Uso rápido

La autenticación es interactiva (ADR-018/019): la Clave Tributaria se pide por pantalla, nunca se pasa por la línea de comandos ni queda en el historial del shell.

# Inicia sesión una vez — pide RUT + Clave Tributaria, la guarda en el keyring del SO
sii auth login
# O en un navegador visible (tipeas la Clave en el SII, no en la terminal; cookies-only)
sii auth login --browser

# Sesión + identidad
sii auth status              # lectura local de la sesión cacheada
sii auth status --refresh    # consulta al SII: identidad + régimen desde Mi Sii
sii profile                  # snapshot completo del contribuyente (PII; usa status -r para el subconjunto seguro)

# Registro de Compras y Ventas (COMPRA = recibidas, VENTA = emitidas)
sii rcv summary --period 2026-05 --side COMPRA
sii rcv summary --year 2026 --side VENTA
sii rcv list --period 2026-05 --type compras --doc-type-code 33
sii rcv match --folio 12345

# F29 (IVA mensual) — solo lectura, nunca envía
sii f29 draft --period 2026-05     # la propuesta pre-llenada del SII
sii f29 status --period 2026-05    # estado de la declaración presentada

# Boletas de Honorarios (recibidas / emitidas)
sii bte list --type recibidas --year 2026         # resumen anual
sii bte list --type emitidas --period 2026-05     # detalle mensual

# DTE: tipos que un RUT está autorizado a emitir — consulta pública, sin login
sii dte authorized --rut 11111111-1

# Operar sobre una empresa que representas legalmente (ADR-015)
sii f29 draft --period 2026-05 --rut 11111111-1

# Versión instalada
sii version                  # o:  sii --version  /  sii -V

# Chequeo rápido: hostnames resueltos + rate limit
sii status

# Cierra la sesión limpiamente al terminar (evita el bloqueo por sesión vieja, ADR-011)
sii auth logout

La mayoría de los comandos aceptan --format json (por defecto, para canalizar a jq) o --format table.

El servidor MCP corre sobre stdio (por defecto para Claude Desktop / Claude Code) y expone las mismas operaciones (auth_status, auth_login [abre el navegador], profile, rcv_summary, rcv_list, rcv_match, f29_draft, f29_status, dte_authorized, bte_list, current_config):

sii-mcp

(Para depurar desde el código con el MCP Inspector: uv run mcp dev src/sii/mcp/server.py.)

Metodología

Este repositorio sigue Context-First Development (CFD): cada decisión de arquitectura o proceso vive como un ADR en docs/decisions/, las unidades de trabajo se registran como issues de GitHub con una plantilla de cuerpo fija, y la revisión de PRs contrasta el diff contra los índices en vez de leer archivos completos.

• CLAUDE.md — índice raíz (≤100 líneas).
• docs/ARCHITECTURE.md, STACK.md, CONVENTIONS.md, CURRENT_STATUS.md, ROADMAP.md — se cargan bajo demanda.
• docs/decisions/ — 27 ADRs (split de tres capas, single-env prod, el contrato SII in-house, ciclo de sesión, rate limits, multi-RUT, auth interactivo + login por navegador, sesión-autoritativa sobre la credencial, el flujo de GitHub, filosofía de review, los docs de contrato SII, y la publicación open source).
• docs/sii-contract/ — los contratos de cable del SII observados por superficie (endpoints, payloads, leyendas de enums, postura de captcha), un doc por superficie siguiendo una plantilla canónica (ADR-020).
• .claude/commands/ — slash commands (issue-new, issue-start, review-pr, session-start, session-close, etc.).
• .github/ — plantillas de PR + issues alineadas con los ADRs.

CFD en sí: https://github.com/albertomarturelo/context-first-development.

Postura

Este proyecto automatiza la interacción de un usuario con su propia cuenta del SII (o cuentas que representa legalmente). No apunta a uso SaaS multi-tenant; no rota IPs para evadir rate limits; no guarda credenciales compartidas; registra cada operación localmente. Ver docs/decisions/003-tos-posture-own-account-only.md.

Aviso legal. Esta es una herramienta independiente y comunitaria — no está afiliada, autorizada ni avalada por el SII (Servicio de Impuestos Internos). Maneja el portal público del contribuyente observando su comportamiento (no existe una API oficial fuera de DTE); el SII puede cambiar el portal en cualquier momento y romperla sin aviso. Se entrega tal cual, sin garantía (ver LICENSE). Eres responsable de su uso y de cumplir los términos del SII.

Licencia

Apache-2.0 © Alberto Marturelo Lorenzo.