Skip to content
BranchesTags
 
 

Repository files navigation

mcp-sii

Servidor MCP open source para el Sistema de Facturación Gratuito del SII (mipyme.sii.cl). Permite a agentes IA (Claude, etc.) consultar documentos tributarios emitidos y recibidos.

Requisitos

  • Node.js 24+
  • agent-browser instalado globalmente: npm install -g agent-browser && agent-browser install
  • Certificado digital del SII instalado en el keychain del sistema (para operaciones marcadas con *)

Instalación

npm install
npm run build

Autenticación: sesión por RUT

Ya no hay una única credencial fija por proceso. Antes de llamar cualquier tool de consulta hay que abrir sesión para el RUT que se va a usar:

  1. sii_iniciar_sesion(rut, clave) — autentica al SII con el RUT y la clave tributaria de esa persona. La credencial vive sólo en memoria del proceso (no se persiste a disco) y queda asociada a ese rut. Repetir la llamada con el mismo RUT no abre una sesión nueva mientras la anterior siga vigente (dentro de 2 horas) — abrir sesiones de más agota el límite del SII para ese RUT.
  2. Cualquier otra tool (sii_bhe_resumen, sii_dte_list_documentos_emitidos, sii_rcv_resumen, etc.) recibe rut como su primer parámetro obligatorio y opera sobre la sesión que abrió el paso anterior. Si no hay sesión iniciada para ese RUT, la tool devuelve { "ok": false, "error": "SESION_NO_INICIADA" } en vez de autenticar sola — no hay auto-login implícito.
  3. sii_cerrar_sesion(rut) — cierra la sesión en el SII y olvida la credencial de ese RUT. Conviene llamarla siempre al terminar: el SII limita cuántas sesiones simultáneas puede tener un RUT y las bloquea al superarlas (error 01.01.190.500.720.27).

Esto permite operar varios RUT en paralelo desde el mismo proceso, cada uno con su propia credencial y su propia sesión (cookie jar independiente).

Limitación actual: sii_iniciar_sesion sólo acepta rut + clave (autenticación por clave tributaria, que corre por navegador). No hay hoy forma de autenticar con certificado digital por esta vía. Las tools que consultan por HTTP en vez de navegador (sii_bhe_*, sii_rcv_*, sii_dte_*, sii_renta_*, sii_mipyme_list_*) necesitan el archivo de cookies que sólo produce la autenticación con certificado — una sesión abierta con clave vía sii_iniciar_sesion no lo genera, y esas tools van a fallar (RequiereCertificado) para un RUT autenticado así. Hoy funcionan sin problema con sii_iniciar_sesion las tools que operan por navegador: sii_persona_list_bienes_raices y sii_mipyme_emitir_dte.

Configuración

Variables de entorno (crear .env o configurar en Claude Desktop):

# RUT de la persona natural autorizada (no el RUT de la empresa). Requerida
# para que el proceso arranque, aunque ya no se usa para autenticar tools:
# la autenticación de tools pasa por sii_iniciar_sesion(rut, clave).
SII_RUT=12345678

# RUT de la empresa a operar (requerido si la persona opera múltiples empresas).
# Se sigue usando como fallback cuando la tool no recibe empresaRut.
SII_EMPRESA_RUT=22222222

# Sólo para EMITIR DTE en el portal mipyme: la clave del certificado digital que
# el contribuyente tiene cargado EN EL SII (el "certificado centralizado"), con
# la que el SII firma el documento del lado servidor.
SII_CERT_CLAVE_SII=claveDelCertCargadoEnElSii

SII_CERT_CLAVE_SII no se deriva de SII_CERT_PASSWORD, aunque parezca lo mismo. El certificado cargado en el SII puede ser otro archivo, o el mismo cargado con otra clave — y en ese segundo caso comparar los certificados diría "coinciden" mientras la clave sigue sin servir. Si en tu caso son la misma clave, configurá las dos variables con el mismo valor: queda explícito y no depende de una suposición del código.

Sin esta variable, emitir falla pidiéndola; todo lo demás (consultas y la previsualización de un DTE) funciona igual.

Perfiles de verificación contra el SII real

Verificar el servicio entero necesita cuatro credenciales, no una: lo que un contribuyente puede consultar depende de qué es y de cómo factura, y el certificado es además otra forma de entrar.

Perfil Qué es Verifica
SII_PERSONA_* Persona natural BHE emitidas y recibidas, bienes raíces, renta
SII_MIPYME_* Inscrito en Facturación Gratuita del SII El portal mipyme entero
SII_MERCADO_* Factura con software de mercado RCV, DTE, F29
SII_CERT_* Certificado digital (.pfx en disco) Lo mismo que su titular, más firmar: emitir-dte

El de certificado no es otro contribuyente sino la otra forma de autenticar, y es la única con la que se puede firmar. El .env guarda la ruta del .pfx —es un binario de varios KB— y la conversión a base64 que piden las rutas la hace perfilesVerificacion.ts.

El de mipyme no es intercambiable: si el RUT no está inscrito en Facturación Gratuita, el selector de empresas del portal viene sin una sola opción y no hay nada que consultar. Eso no se ve en el .env ni en ningún otro lado hasta que se intenta, y por eso existe:

npx ts-node src/scripts/clasificarCredencial.ts          # los que estén cargados
npx ts-node src/scripts/clasificarCredencial.ts mipyme   # uno en particular

Sondea las rutas REST de producción y dice para qué sirve realmente cada credencial. Conviene correrlo antes de empezar una ronda, no a la mitad.

perfilesVerificacion.ts no sustituye un perfil por otro: si falta el que se pide, falla diciendo cuál. Un fallback haría correr la verificación contra un contribuyente distinto, y ahí ni el verde ni el rojo dicen nada sobre lo que se quería probar.

Ver .env.example para la plantilla completa.

Legado: SII_CLAVE / SII_CERT_PATH (una sola credencial por proceso)

SII_CLAVE=mipassword
# o, con precedencia sobre la clave:
SII_CERT_PATH=/ruta/al/certificado.pfx
SII_CERT_PASSWORD=passwordDelCert

Estas variables ya no son la forma de autenticar las tools: el código que las lee (getConfig()/validateEnv()) sigue existiendo, pero ninguna tool de consulta pasa por ahí — todas usan la credencial que dejó sii_iniciar_sesion para el rut de la llamada. Quedan documentadas acá sólo porque npm run validate-cert (más abajo) las sigue leyendo para validar el .pfx fuera del flujo de sesión.

Validar certificado digital

Antes de usar SII_CERT_PATH/SII_CERT_PASSWORD, puedes verificar que el .pfx existe y que la contraseña lo desbloquea correctamente (sin exponer el subject/issuer, que suele contener datos personales):

npm run validate-cert

Lee SII_CERT_PATH y SII_CERT_PASSWORD desde el entorno (.env) y termina con código 0 si el certificado es válido, o 1 con un mensaje de error si no.

Uso con Claude Desktop

Agregar en claude_desktop_config.json:

{
  "mcpServers": {
    "sii": {
      "command": "node",
      "args": ["/ruta/a/mcp-sii/dist/src/index.js"],
      "env": {
        "SII_RUT": "12345678",
        "SII_EMPRESA_RUT": "22222222"
      }
    }
  }
}

SII_RUT sigue siendo requerida para que el proceso arranque, pero ya no autentica nada por sí sola. Una vez conectado, autenticá cada RUT con el que vayas a operar llamando sii_iniciar_sesion(rut, clave) desde el chat antes de pedir cualquier consulta.

Tools disponibles

Todas las consultas son de solo lectura, con una única excepción marcada como tal. Todas reciben rut como primer parámetro — ver Autenticación: sesión por RUT.

Sesión

Tool Descripción
sii_iniciar_sesion Autentica un RUT con su clave tributaria. Necesaria antes de llamar cualquier otra tool con ese RUT
sii_cerrar_sesion Cierra la sesión en el SII para ese RUT y olvida su credencial (conviene al terminar)

Portal mipyme — Sistema de Facturación Gratuito

Tool Descripción
sii_mipyme_list_empresas Empresas que la persona puede operar en este portal
sii_mipyme_list_dte_emitidos Historial de DTE emitidos por este portal, de a 100 por página
sii_mipyme_list_dte_recibidos DTE recibidos por la empresa, con el estado del acuse
sii_mipyme_list_borradores Borradores guardados, con todos los campos del SII
sii_mipyme_emitir_dte Emite un DTE. Acto tributario real e irreversible — ver la advertencia abajo

Consultas DTE

Tool Descripción
sii_dte_list_documentos_emitidos Resumen por tipo de documento del período, con detalle opcional
sii_dte_list_documentos_recibidos Ídem, del lado recibido
sii_dte_get_documento_emitido Detalle de un documento emitido
sii_dte_get_documento_recibido Detalle de un documento recibido
sii_dte_validez Si un DTE (emisor, tipo, folio) fue recibido por el SII
sii_dte_verificar Si emisor, receptor, folio, fecha y monto coinciden con lo informado al SII
sii_f29_estado_declaracion Estado del F29 (IVA mensual) de un período

sii_dte_validez y sii_dte_verificar eran consultas públicas del SII y hoy están detrás del login, así que van con sesión. La segunda es la que sirve para validar una factura recibida antes de pagarla: datosCoinciden es el veredicto, y el texto del SII distingue "Datos coinciden con los registrados" de "datos NO coinciden" con casi las mismas palabras — se midió con el mismo documento y el monto cambiado en un peso.

sii_f29_estado_declaracion consulta la declaración de IVA de un período (AAAAMM): folio, estado, observaciones, fecha y moneda. El PDF del formulario compacto —donde están todos los montos— se pide aparte por REST (/v1/f29/formulario-compacto). La Consulta Integral del SII es una app GWT sin API pública: el servicio habla su protocolo GWT-RPC directamente, así que esta consulta es más frágil que las demás —si el SII recompila la app cambia un hash interno y hay que re-relevarlo—, y falla explícito cuando eso pasa.

Impuestos y registros

Tool Descripción
sii_rcv_resumen Registro de Compras y Ventas, resumen del período
sii_rcv_detalle Registro de Compras y Ventas, documento por documento
sii_rcv_tipos_documento Catálogo de los 46 tipos de documento del registro
sii_rcv_async_solicitar Genera el detalle del RCV en background para volúmenes grandes
sii_rcv_async_estado Estado (CREADO/EN PROCESO/TERMINADO) de una solicitud async del RCV
sii_rcv_empresas_autorizadas Empresas que el RUT puede consultar en el RCV
sii_renta_get_f22 Formulario 22 completo de un año tributario
sii_renta_estado_declaracion Estado de la declaración de renta

sii_rcv_detalle devuelve 26 campos por documento, no sólo los montos básicos: además de neto, exento, IVA y total, informa el IVA no recuperable con su código, el neto e IVA de activo fijo, el IVA de uso común, el impuesto sin derecho a crédito, el IVA no retenido, los tres montos de tabaco, las fechas de recepción y de acuse, y el tipo de transacción. Para cuadrar un F29 no son opcionales: el IVA no recuperable, el de uso común y el de activo fijo cambian el crédito fiscal. sii_rcv_resumen informa los dos primeros por tipo de documento y en los totales.

Dos criterios al leer esos campos. Los montos vienen en 0 y los códigos en null: el SII manda 0 cuando el concepto no aplica al documento, y ahí el cero ES el dato, mientras un código en 0 no sería "código cero" sino "no hay". Y fechaRecepcion trae hora y fechaEmision no (23/06/2026 12:51:37 contra 23/06/2026): son dos formatos distintos en la misma fila, tal como los manda el SII, y no se normalizan para que la diferencia se vea en vez de descubrirse parseando.

sii_mipyme_list_borradores sale de otra aplicación del SII, no del portal clásico: mipymeinternetui, con su propia API. Devuelve los campos con los nombres del SII (EFXP_*) sin renombrar, porque un borrador trae decenas que dependen del tipo de documento y elegir cuáles exponer sería adivinar qué necesita quien consulta. Verificado con un borrador real: ehdr_CODIGO es el código y ptdc_CODIGO el tipo de documento.

Los borradores cuelgan de la empresa activa, así que empresa_rut importa: sin él, un RUT que opera varias empresas recibe los borradores de la que dejó la consulta anterior. No es teórico — con la empresa sin fijar, las cinco empresas de prueba devolvían cero borradores, y un listado vacío se lee como "no tenés borradores" en vez de "preguntaste por otra empresa".

Tres cosas del catálogo de apigateway no se homologaron, y no por falta de tiempo:

  • borrador-pdf. Depende de tener un borrador; sin ninguno no hay nada que relevar ni con qué verificar.
  • info-contribuyente. El formulario de emisión no expone ningún CGI de consulta de contribuyente: los datos del receptor aparecen recién al previsualizar, o sea que no hay una consulta separada que homologar.

El PDF de un documento existe sólo como ruta REST (POST /v1/mipyme/dte-pdf), no como tool MCP, igual que el de BHE: un PDF en base64 dentro de una respuesta MCP satura el contexto sin que el modelo pueda hacer nada con él. Se pide por el codigo que devuelve el listado y no por el folio, que se repite entre emisores y entre tipos de documento.

El respaldo XML (POST /v1/mipyme/respaldo-xml) es la fuente buena para procesar documentos: devuelve el SetDTE firmado tal como lo entrega el portal, con el detalle línea a línea (NmbItem, QtyItem, PrcItem, MontoItem) y el giro del emisor (Acteco, GiroEmis) en campos. El PDF sirve para mirar un documento; el XML, para clasificarlo sin parsear una maqueta de impresión. Tampoco es tool MCP: un respaldo entero en el contexto del modelo no le sirve de nada.

Dos cosas que definen su forma, las dos verificadas contra el SII:

  • El camino no es el que enlaza el menú. /Portal001/auth.html sólo redirige por JavaScript a auth.cgi, que es el CGI que abre el contexto de descarga; después van lista_documentos.cgi (fija la búsqueda) y download.cgi (entrega el XML). Quedarse en el .html daba el falso negativo de que "el portal no ofrece XML". El reCAPTCHA de esa pantalla no bloquea: el propio JavaScript manda el token sólo si existe, y download.cgi responde sin él.

  • El SII no entrega más de 20 documentos por descarga, y el tope lo impone el servidor, no el JavaScript. Un rango que lo exceda se parte al medio y cada mitad se pide aparte, hasta que todas pasen; la respuesta trae un tramo por descarga, cada uno un SetDTE válido por sí solo. No se concatenan: dos SetDTE pegados no son XML bien formado, y unificarlos obligaría a reescribir contenido firmado. Lo que no se pudo bajar sale en limitaciones en vez de descartar todo el respaldo (ver docs/integracion-api.md).

  • Un día suelto que TODAVÍA excede el tope con tipo_dte puesto tiene un tercer eje —folio para emitidos, contraparte para recibidos—, pero cada eje queda apagado por defecto y tiene SU PROPIA variable (ver .env.example): RESPALDO_XML_TERCER_NIVEL_FOLIO prende el eje de emitidos, que ya se verificó en vivo contra el SII real, y RESPALDO_XML_TERCER_NIVEL_CONTRAPARTE prende el eje de recibidos, que todavía NO está verificado. Por eso conviene verificar el eje de contraparte primero con src/scripts/verificarRespaldoXml.ts (VERIF_TIPO_DTE + VERIF_CONTRAPARTE) antes de prender esa variable en un ambiente que atienda recibidos. El interruptor único original, RESPALDO_XML_TERCER_NIVEL, sigue existiendo por compatibilidad y prende los dos ejes a la vez; las variables por eje tienen precedencia sobre él.

    Verificar EN VIVO con src/scripts/verificarRespaldoXml.ts (npm run verificar-respaldo-xml):

    • Modo de una consulta: VERIF_EMPRESA, VERIF_ORIGEN (recibidos por defecto o emitidos), VERIF_DESDE/VERIF_HASTA (default: mes pasado), VERIF_TIPO_DTE, VERIF_FOLIO/VERIF_FOLIO_HASTA, VERIF_CONTRAPARTE, VERIF_RZN_SOC, VERIF_MAX_TRAMOS (default 10, igual que la ruta REST), VERIF_SALIDA (directorio donde deja los XML bajados).
    • Modo plan (VERIF_PLAN=ruta/al/plan.json): corre VARIAS combinaciones de filtros en la MISMA corrida, contra la MISMA sesión del SII (un solo login), con la pausa de ritmoSii.ts entre cada una. El formato: 
      {
  "pausa_ms": 1500,
  "consultas": [
    { "origen": "recibidos", "desde": "2026-01-01", "hasta": "2026-01-31" },
    { "origen": "recibidos", "desde": "2026-01-01", "hasta": "2026-01-31", "tipo_dte": 33, "folio": 1, "folio_hasta": 500 },
    { "origen": "recibidos", "desde": "2026-01-01", "hasta": "2026-01-31", "tipo_dte": 33, "contraparte": "77777777-7" }
  ]
}
      VERIF_EMPRESA y VERIF_SALIDA siguen valiendo para el plan entero (la empresa a consultar y, en este modo, dónde queda el reporte). VERIF_SALIDA es OBLIGATORIO en modo plan: ahí se escribe reporte-verificacion-plan.txt, un solo archivo con las consultas EN ORDEN, sus veredictos, si alguna quedó INCOMPLETA (con la causa y la acción correspondiente, no comparable con una completa) y —arriba de todo— cuántos logins hizo la corrida. A diferencia del modo de una consulta, el modo plan NO guarda los XML bajados — sólo el reporte comparable; si hace falta archivar el XML de una combinación puntual, correla aparte en modo de una consulta con esos mismos filtros. max_tramos también se puede fijar por consulta (default 10, igual que la ruta REST), para que un rango ancho no tope el límite y quede como respaldo parcial sin que se note en el reporte.
    • Por qué existe el modo plan y no alcanza con encadenar corridas sueltas: cada corrida de este script abre un Browser nuevo (un login nuevo al SII), porque compartir contexto entre sesiones fue un bug real (ver registroSesionesSii.ts). Encadenar quince corridas para probar quince combinaciones de filtros es encadenar quince logins — el patrón que el SII bloquea por sesiones simultáneas — y una vez dio resultados DISTINTOS para el mismo mes y el mismo tipo de documento en corridas consecutivas (3 documentos contra 7), sin ninguna página de error de por medio: la herramienta de medición estaba alterando lo que medía. El modo plan corre todas las consultas en un solo proceso y una sola sesión para que el resultado sea comparable consigo mismo.

sii_mipyme_list_dte_recibidos es el espejo de list_dte_emitidos y comparte su forma, con el emisor como contraparte en vez del receptor. Trae algo que sii_rcv_* no tiene: el estado del acuse (DTE Recibido Sin Reparos, con Reparos), que es la respuesta que la empresa dio al documento.

sii_rcv_empresas_autorizadas no es lo mismo que sii_mipyme_list_empresas: éstas son las empresas que el RUT puede consultar en el registro, y las de mipyme las que puede operar en el portal de facturación gratuita. Un RUT puede estar en una lista y no en la otra. Confundirlas llevaría a ofrecer facturar por una empresa que sólo se puede mirar.

Indicadores y valores publicados

Tool Descripción
sii_indicadores_uf Valor diario de la UF de un año
sii_indicadores_dolar Dólar observado diario de un año
sii_indicadores_utm UTM, UTA e IPC por mes
sii_indicadores_correccion_monetaria Factores de corrección monetaria por mes
sii_indicadores_impuesto_2da_categoria Tramos del impuesto único de 2ª categoría (art. 43)
sii_indicadores_impuesto_2da_categoria_art52 Tramos del art. 52 bis

Tasación de vehículos

Tool Descripción
sii_vehiculos_tipos Tipos de vehículo de la planilla de un año
sii_vehiculos_marcas Marcas, opcionalmente por tipo
sii_vehiculos_modelos Modelos de una marca con versiones y años tasados
sii_vehiculos_tasacion Tasación fiscal y permiso, por código SII o marca+modelo
sii_vehiculos_equipamiento Diccionario de siglas de equipamiento

Contribuyentes y Mi SII

Tool Descripción
sii_actividades_economicas Los ~670 códigos de actividad económica, filtrables por categoría, IVA y texto
sii_actividad_economica Un código de actividad económica
sii_verificar_rut Formato y dígito verificador de un RUT (aritmética, no consulta al SII)
sii_misii_datos_contribuyente La ficha del contribuyente autenticado según Mi SII

Las tres primeras van sin credencial: la tabla de códigos es una página pública y el verificador de RUT es módulo 11. sii_verificar_rut no dice si el RUT existe —para eso está sii_contribuyente_situacion_tributaria—, sólo si está bien formado. La categoría tributaria viene tal como la publica el SII ("1", "2" o alguna letra como "G" que su tabla no explica); traducirla sería inventar.

sii_misii_datos_contribuyente lee el JSON que la home de Mi SII trae embebido (DatosCntrNow): identificación, tipo y subtipo, segmento, glosa de actividad, fechas, capital, direcciones vigentes y atributos (regímenes y autorizaciones con su vigencia). No trae representantes, socios ni giros: esas secciones no se pudieron relevar con datos.

Sin rut ni credencial, como indicadores. La fuente no es la consulta interactiva del portal —exige un captcha propio del SII antes de cualquier búsqueda— sino las planillas XLSX anuales que el SII publica (liv{año} para livianos, pes{año} para pesados, desde 2020). La primera consulta de un año baja la planilla entera (~7 MB, unos segundos) y las siguientes salen de memoria. Livianos y pesados traen columnas distintas: pesados tiene carga y pasajeros y no trae permiso (va en null); livianos al revés. El diccionario de siglas de equipamiento está en /v1/vehiculos/equipamiento.

Ni estas tools ni las de vehículos reciben rut ni credencial, ni necesitan sii_iniciar_sesion: el SII publica estas tablas abiertas. En REST viven bajo /v1/indicadores/… y /v1/vehiculos/…, y siguen pasando por el auth de tenant y el rate-limit, como todas.

Tres cosas al leerlas:

  • Un día que el SII no publicó no aparece, en vez de aparecer en cero. El dólar sólo trae días hábiles, y el año en curso llega hasta el último día publicado. Un cero en un tipo de cambio no es lo mismo que "no hay dato".
  • La corrección monetaria es triangular: un mes no tiene factor contra los meses anteriores, así que muchas celdas vienen en null, y ese null significa "no corresponde".
  • En los tramos de 2ª categoría, el tramo exento trae exento: true y sus números en null, no en 0. Un factor 0 daría el mismo impuesto por un camino que la tabla no dice. El art. 43 trae los cuatro períodos (MENSUAL, QUINCENAL, SEMANAL, DIARIO) y el art. 52 bis sólo el mensual; el último tramo de cada período no tiene tope, y ahí hasta va en null.

Los resultados se cachean en memoria por año e indicador. Un año ya cerrado no se vuelve a consultar nunca —el valor de la UF de un día pasado no cambia— y el año en curso se revisa cada seis horas. Cada consulta baja una página entera del SII, y el SII corta por volumen: sin caché, convertir cien montos a UF bajaría cien veces la misma tabla.

Boletas de honorarios y persona natural

Tool Descripción
sii_bhe_list_emitidas Boletas de honorarios emitidas
sii_bhe_list_recibidas Boletas de honorarios recibidas
sii_bhe_resumen Resumen anual de boletas emitidas
sii_bhe_resumen_recibidas Resumen anual de boletas recibidas
sii_persona_list_bienes_raices Bienes raíces de la persona, con los códigos del catastro
sii_bienes_raices_comunas Comunas del catastro con su código
sii_bienes_raices_consultar_rol Un bien raíz cualquiera por rol: avalúo y contribuciones
sii_bienes_raices_multipropietarios Copropietarios de un rol
sii_bienes_raices_solicitudes Historial de certificados pedidos, con la url del PDF

Los dos resúmenes anuales devuelven siempre los doce meses, en orden: un mes sin actividad viene en cero y con los folios en null. Devolver sólo los meses con boletas obligaba a interpretar una ausencia, y "no tuvo" se veía igual que "no se pudo leer".

sii_bhe_resumen_recibidas no equivale a sumar sii_bhe_list_recibidas: son dos CGI distintos del SII, y el anual informa una retención del contribuyente que el informe mensual de recibidas no muestra. Para 07/2026 el anual da 19.063 de retención y el mensual muestra "Retenido 0" en las cuatro boletas — en la UI del portal y en la API por igual. Si necesitás la retención de las boletas recibidas, sale de ahí y de ningún otro lado.

En ese informe, además, folioInicial y folioFinal vienen siempre en null, por mes y del año. El portal no muestra folios ahí, y un rango no significaría nada: cada boleta la folió un emisor distinto.

sii_bhe_list_recibidas pagina los meses de más de 100 boletas encadenando el código de continuación del informe; no hay captura real de un mes así y la garantía son los chequeos de integridad (conteo y duplicados). El detalle está en la guía de integración, sección de limitaciones.

Bienes raíces ya no usa navegador: la SPA del portal tiene detrás una API REST/JSON (/app/vica/{rut}/v1/…) y el servicio le pide lo mismo que la SPA. Sin esa cookie del contexto /app que deja el handshake de la SPA, la API responde cero bytes, no un error. Los certificados de avalúo (/v1/bienes-raices/certificado-avaluo) y el PDF de una solicitud (/v1/bienes-raices/documento) van sólo por REST: un PDF en base64 satura el contexto del modelo. Pedir un certificado es una solicitud real que queda en el historial del contribuyente; no es un acto tributario ni tiene costo, pero tampoco es una lectura, y por eso no se cachea ni se reintenta solo.

sii_persona_list_bienes_raices funciona con la sesión que abre sii_iniciar_sesion (clave, por navegador). El resto de las consultas por HTTP —Consultas DTE, Impuestos y registros, boletas de honorarios y los listados de mipyme— aceptan clave tributaria o certificado digital: las dos producen el cookie jar que esa vía necesita. La única que sigue exigiendo certificado es sii_mipyme_emitir_dte cuando firma, porque firmar un DTE necesita el certificado de verdad y no basta una sesión autenticada.

Situación tributaria de terceros

POST /v1/contribuyente/situacion-tributaria con { rut }. Es la única ruta del adaptador que no lleva credencial del contribuyente: el SII publica esta consulta abierta, así que se puede preguntar por cualquier RUT. Sigue pasando por el auth de tenant y el rate-limit del servidor, como todas.

Devuelve razón social, si presenta inicio de actividades y desde cuándo, si es empresa de menor tamaño (pro-pyme), si declara en moneda extranjera, y las actividades económicas vigentes con su código, giro, categoría y si afectan IVA.

Tres cosas que conviene saber:

  • El dígito verificador se valida antes de consultar. El SII resuelve por el cuerpo del RUT, así que un DV mal escrito devolvería los datos del contribuyente con el DV corregido — o sea que un RUT inválido saldría como válido. Con DV incorrecto la respuesta es 400, y el detalle dice cuál era el que correspondía.
  • Hay caché en memoria de 24 horas por RUT. Esta consulta le pega dos veces a zeus.sii.cl (captcha más informe) y el dato casi no cambia. Sólo se cachean los éxitos: un fallo del portal, o un RUT que todavía no tiene datos, se vuelven a consultar.
  • observaciones y documentos_timbrados no se emiten todavía: no hay una captura del informe que los traiga, y escribir el parseo a ciegas devolvería datos plausibles que nadie revisaría. Está anotado en la spec del endpoint.

Cambios recientes que rompen contrato

La migración del portal mipyme a HTTP directo (2026-08-03) cambió dos cosas para quien ya usaba estas tools:

  • sii_mipyme_list_empresas y sii_mipyme_list_dte_emitidos ahora requieren certificado digital. Antes corrían por navegador y aceptaban clave tributaria. El camino HTTP necesita el archivo de cookies que sólo produce la autenticación con certificado, igual que el resto de las consultas. Fallan de entrada, con el mensaje que dice qué configurar. sii_mipyme_emitir_dte sigue por navegador y sigue aceptando clave.
  • limit ya no existe en sii_mipyme_list_dte_emitidos: se reemplaza por pagina. El CGI entrega de a 100 documentos por página y recortar del lado del cliente escondía que había más. La respuesta ahora informa pagina y totalPaginas.

La resolución de la empresa no cambió: el parámetro gana, si no vino se usa SII_EMPRESA_RUT, y si tampoco hay se resuelve sola cuando el RUT opera una única empresa en el portal.

Advertencias

  • sii_mipyme_emitir_dte está probablemente inoperativa. Apunta a mipeDocAlta.cgi, que responde 404 (medido el 2026-08-03). La ruta del portal es mipeLaunchPage.cgi?OPCION=<tipo>&TIPO=4, pero no se corrigió sin relevar antes el formulario que sirve: apuntarla a ciegas convertiría un fallo visible en un camino que emite documentos tributarios reales con parámetros adivinados.
  • sii_dte_* y sii_rcv_* no son comparables. Responden preguntas distintas y sus cifras no cuadran: Consultas DTE incluye guías de despacho, clasifica las facturas de compra del lado emitido, y sus recibidos difieren de los del RCV. Ninguno está mal.
  • Cada aplicación del SII tiene su propia lista de empresas autorizadas. La de sii_mipyme_list_empresas no coincide con la que habilitan el RCV o Consultas DTE.

Adaptador REST: contrato de errores

Las rutas /v1/* responden siempre HTTP 200 —salvo 400 por body inválido— y el resultado va en el cuerpo: {"ok": true, ...} o {"ok": false, "error": "..."}.

Lo que un consumidor necesita saber de cada código es si reintentar sirve:

error ¿Reintentar? Cuándo aparece
BAD_REQUEST (HTTP 400) No El body no valida. Trae detalle con el campo y el motivo
CREDENCIALES_INVALIDAS No El portal dijo explícitamente que la clave es incorrecta
NO_ENCONTRADO No El SII confirmó que el dato no existe. Trae detalle
LIMITE_CONOCIDO No Un límite que ya conocemos: un descuadre entre lo que el SII informa y lo que se recupera, o un cambio de formato de un CGI. Trae detalle
SESIONES_SIMULTANEAS Sí, tras esperar El RUT ya tiene demasiadas sesiones abiertas en el SII. Trae detalle
LIMITE_SII Sí, esperando de verdad El SII cortó las consultas por volumen (su propio error 429). Trae detalle
SERVICIO_OCUPADO Sí, en segundos Nosotros estamos ocupados: demasiadas consultas de indicadores esperando turno. Trae detalle
SII_NO_DISPONIBLE Sí, más tarde El portal mipyme respondió su propia página de error interno («Error al contribuyente») en vez del historial o listado pedido. Trae detalle
ERROR Sí Todo lo demás: cola de espera del SII, fallo de red, una excepción no controlada

LIMITE_SII es el que más cambia qué hacer: el SII tiene rate limiting propio y, con muchas consultas al mismo portal en poco tiempo, corta ESE PORTAL ENTERO por un rato — para todos. Reintentar de inmediato es lo que mantiene el corte: hay que esperar minutos, no segundos, y bajar el ritmo. Los barridos internos ya van con pausa por esto mismo (src/ritmoSii.ts).

Un detalle que cuesta diagnosticar: el SII no devuelve un status 429, devuelve una página HTML. Sin mirar el cuerpo es indistinguible del HTML del login —o sea de "la sesión expiró"— y las dos cosas piden lo contrario: una que esperes, la otra que reintentes reautenticando.

SESIONES_SIMULTANEAS se comporta igual que ERROR —reintentar sirve— y existe por lo que permite decirle a la persona. Con ERROR sólo cabe "probá de nuevo en unos minutos"; con éste se le puede decir que hay otra consulta en curso sobre el mismo contribuyente, que es accionable: sabe que dejó otra pestaña abierta o que un colega está mirando el mismo caso. Salía mezclado en ERROR y eso mandaba a diagnosticar timeouts y problemas de red que no existían.

Los dos códigos con "no" que podrían confundirse:

  • CREDENCIALES_INVALIDAS se reserva para cuando el portal lo dice con esas palabras. Un fallo transitorio sale como ERROR, nunca como credencial inválida — si no, un consumidor que borra la credencial al recibirlo estaría borrando claves que sí servían por una caída del SII.
  • LIMITE_CONOCIDO existe porque esos casos son permanentes y salían como ERROR: el consumidor reintentaba en loop algo que nunca iba a funcionar.

Desarrollo

npm test          # correr tests
npm run dev       # desarrollo con ts-node
npm run build     # compilar TypeScript

Pruebas contra el SII real

npm test usa el navegador mockeado y no toca la red. Existe además una suite que le pregunta al portal de verdad, con su propio comando:

npm run test:e2e

Necesita SII_RUT y SII_CLAVE en el .env; sin credenciales se saltea sola en vez de fallar. Cubre dos cosas: que la clave correcta autentique y deje cookies de sesión utilizables, y que un login que no puede tener éxito no se reporte como exitoso. Ese segundo caso existe porque fue un bug real en producción (validar-clave respondía ok:true con cualquier clave) y ningún test con el navegador mockeado podía detectarlo: el criterio de éxito estaba mal, y el mock contestaba lo que le habíamos enseñado a contestar.

Va separada de npm test a propósito. Cada test abre una sesión real, y el SII limita las sesiones simultáneas por RUT y bloquea las claves con varios intentos fallidos, así que no conviene que se dispare desde CI ni sin querer.

Hay un tercer caso, apagado por defecto, que manda una clave incorrecta al RUT propio para verificar que se clasifica como CREDENCIALES_INVALIDAS:

SII_E2E_CLAVE_MALA=1 npm run test:e2e

Es el único que ejercita esa clasificación de punta a punta, y también el único que acumula intentos fallidos sobre una cuenta real. Correlo puntualmente, no en loop.

About

MCP SII http

Resources

Readme
License
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages