sii-cli

# sii CLI + servidor MCP para automatizar interacciones rutinarias con el **SII de Chile** (Servicio de Impuestos Internos), para un operador (persona o contador) que actúa sobre su propio RUT y sobre las cuentas que representa o le confían — **multi-cuenta**, sin custodiar nunca la Clave de un tercero (cookies-only, ADR-028). - `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 [--add]` / `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**, y muestra el roster de cuentas conocidas. - **multi-cuenta (contador)** — varias cuentas autenticadas **en paralelo**, y cambias la activa **al instante, sin re-login** (estilo `firebase use`; cookies por RUT, ADR-028). `auth login --browser --add` agrega otra cuenta sin desloguear las demás; `accounts list` muestra el roster (rut, alias, activa, sesión viva/expirada); `accounts alias <rut> <nombre>` la nombra; `use <rut|alias>` cambia la activa. El RUT se acepta **en cualquier formato** (con o sin puntos/guion, DV en mayúscula o minúscula) — se normaliza solo. **Nunca custodiamos la Clave de un cliente** (cookies-only). El RUT operativo por-llamada (`--rut`, ADR-015) es algo distinto de la cuenta activa. - **`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`](docs/ROADMAP.md) y como issues de GitHub. ## Instalación Requiere **Python 3.12+**. Se instala directo desde PyPI, **sin clonar el código**: ```bash # 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): ```bash 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: ```bash uvx --from sii-cli sii status ``` ### Desde el código (desarrollo) ```bash 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: ```bash # 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: ```bash 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. ```bash # 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) # Múltiples cuentas (contador) — varias sesiones vivas en paralelo, sin re-login al cambiar sii auth login --browser --add # agrega OTRA cuenta sin desloguear las demás (cookies-only) sii accounts list # roster: rut, alias, activa, sesión viva/expirada sii accounts alias 11111111-1 acme # nombra una cuenta para usarla por alias sii use acme # cambia la cuenta activa al instante (selecciona, no autentica) # 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; `add=True` para multi-cuenta], `account_use`, `accounts_list`, `profile`, `rcv_summary`, `rcv_list`, `rcv_match`, `f29_draft`, `f29_status`, `dte_authorized`, `bte_list`, `current_config`): ```bash 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](LICENSE)). Eres responsable de su uso y de cumplir los términos del SII. ## Licencia [Apache-2.0](LICENSE) © Alberto Marturelo Lorenzo.