@devlas/dte-sii

Librería de facturación y boletas electrónicas para el SII de Chile.

Genera, timbra, firma y envía facturas electrónicas, boletas electrónicas, libros contables y automatiza el proceso de certificación ante el SII.

Desarrollada por Devlas SpA · Licencia MIT · Node.js >= 18 · CommonJS

Instalación

npm install @devlas/dte-sii

Tabla de contenidos

• Tipos de DTE soportados
• Uso rápido
• Flujo completo: Factura Electrónica (tipo 33)
• Boletas electrónicas
• Libros electrónicos y RCOF
• Gestión de folios
• Sesión y autenticación con el SII
• Descargar el XML completo desde el portal (Respaldo MIPYME)
• Aceptación y reclamo de DTE (WsReclamo)
• Estados SII: Interpretación de respuestas
• Manejo de errores
• Configuración global y reintentos
• Utilidades
• Uso desde proyectos ESM (interop)
• TypeScript
• Referencia de clases
• Estructura de archivos
• Certificación SII
• Depuración: captura de llamadas al SII
• Ambientes
• Contribuir
• Seguridad
• Licencia

Tipos de DTE soportados

| Tipo | Documento | |------|-----------| | 33 | Factura Electrónica | | 34 | Factura No Afecta o Exenta Electrónica | | 39 | Boleta Electrónica Afecta | | 41 | Boleta Electrónica Exenta | | 43 | Liquidación Factura | | 46 | Factura de Compra | | 52 | Guía de Despacho | | 56 | Nota de Débito | | 61 | Nota de Crédito |

Uso rápido

const { Certificado, CAF, DTE, EnvioDTE, EnviadorSII } = require('@devlas/dte-sii')
const fs = require('fs')

const cert = new Certificado(fs.readFileSync('empresa.pfx'), 'contraseña')
const caf  = new CAF(fs.readFileSync('caf_33.xml', 'utf8'))

const dte = new DTE({
  Encabezado: {
    IdDoc:   { TipoDTE: 33, Folio: 1 },
    Emisor:  { RUTEmisor: '76543210-K', RznSoc: 'Mi Empresa SpA', GiroEmis: 'Software', DirOrigen: 'Av. Ejemplo 123', CmnaOrigen: 'Santiago', Acteco: 620200 },
    Receptor: { RUTRecep: '12345678-9', RznSocRecep: 'Cliente SA', GiroRecep: 'Comercio', DirRecep: 'Calle 456', CmnaRecep: 'Providencia' },
  },
  Detalle: [
    { NmbItem: 'Servicio de desarrollo', QtyItem: 1, PrcItem: 100000 },
  ],
})

dte.generarXML().timbrar(caf).firmar(cert)

const envio = new EnvioDTE({ certificado: cert })
envio.agregar(dte)
envio.setCaratula({ RutEmisor: '76543210-K', RutReceptor: '60803000-K', FchResol: '2024-01-15', NroResol: 123 })
envio.generar()

const enviador = new EnviadorSII(cert, 'produccion') // o 'certificacion'
const resultado = await enviador.enviarDteSoap(envio)
console.log('TrackID:', resultado.trackId)

Flujo completo: Factura Electrónica (tipo 33)

1. Cargar certificado y CAF

const { Certificado, CAF } = require('@devlas/dte-sii')
const fs = require('fs')

const cert = new Certificado(fs.readFileSync('empresa.pfx'), 'clave_pfx')
// cert.getPrivateKeyPem()   → PEM de la llave privada
// cert.getCertificatePem()  → PEM del certificado público

const caf = new CAF(fs.readFileSync('caf_33.xml', 'utf8'))
// caf.getRutEmisor()        → RUT del emisor
// caf.getTipoDTE()          → 33
// caf.getFolioDesde()       → primer folio autorizado
// caf.getFolioHasta()       → último folio autorizado
// caf.isFolioValido(folio)  → boolean

2. Crear el DTE

const { DTE } = require('@devlas/dte-sii')

// Formato simplificado (calcula totales automáticamente)
const dte = new DTE({
  tipo: 33,
  folio: 1,
  emisor: {
    rut: '76543210-K', razonSocial: 'Mi Empresa SpA',
    giro: 'Desarrollo de software', direccion: 'Av. Ejemplo 123',
    comuna: 'Santiago', actividadEconomica: 620200,
  },
  receptor: {
    rut: '12345678-9', razonSocial: 'Cliente SA',
    giro: 'Comercio', direccion: 'Calle 456', comuna: 'Providencia',
  },
  items: [
    { nombre: 'Licencia anual', cantidad: 1, precio: 100000 },
    { nombre: 'Soporte técnico', cantidad: 3, precio: 15000 },
  ],
  resolucion: { fecha: '2024-01-15', numero: 123 },
})

// O bien formato estructurado con XML SII estándar
const dte = new DTE({
  Encabezado: { IdDoc: { TipoDTE: 33, Folio: 1 }, Emisor: { ... }, Receptor: { ... }, Totales: { ... } },
  Detalle: [ { NmbItem: 'Producto', QtyItem: 2, PrcItem: 50000 } ],
  Referencia: [ { TpoDocRef: 61, FolioRef: 5, RazonRef: 'Anula factura' } ], // opcional
})

// Generar XML → timbrar → firmar (chainable)
dte.generarXML().timbrar(caf).firmar(cert)

// Obtener el XML final
console.log(dte.getXML())

3. Crear sobre y enviar

const { EnvioDTE, EnviadorSII } = require('@devlas/dte-sii')

const envio = new EnvioDTE({ certificado: cert })
envio.agregar(dte)
envio.setCaratula({
  RutEmisor:   '76543210-K',
  RutReceptor: '60803000-K', // RUT del SII para envíos propios
  FchResol:    '2024-01-15',
  NroResol:    123,
})
envio.generar()

const enviador = new EnviadorSII(cert, 'produccion')
const resultado = await enviador.enviarDteSoap(envio)
// resultado.trackId   → ID para consultar el estado
// resultado.estado    → 'EPR', 'REC', etc.
// resultado.glosa     → mensaje SII

4. Consultar estado del envío

// Estado del sobre (EnvioDTE)
const estadoSobre = await enviador.consultarEstado({
  trackId: resultado.trackId,
  rutEmisor: '76543210-K',
})
// estadoSobre.esExitoso / esIntermedio / esRechazado
// estadoSobre.codigo   → 'EPR', 'RPR', 'RSC', etc.

// Estado de un DTE individual
const estadoDte = await enviador.consultarEstadoDte({
  rutEmisor:   '76543210-K',
  rutReceptor: '12345678-9',
  tipoDte:     33,
  folio:       1,
  fechaEmision: '2024-06-15',
  montoDte:    145000,
})
// estadoDte.codigo → 'DOK', 'DNK', 'FAU', etc.

Boletas electrónicas

Recomendado para CERTIFICAR boletas: usar CertRunner + BoletaCert, no el camino manual.

Para el proceso de certificación de boletas ante el SII, use el orquestador de alto nivel (require('@devlas/dte-sii/cert') → CertRunner / BoletaCert). Ese camino descarga el set, genera y firma las boletas, arma el EnvioBOLETA + RCOF, obtiene el TrackId y declara el cumplimiento. Es el flujo probado end-to-end.

El camino manual de bajo nivel (DTE + EnvioBOLETA + EnviadorSII) que se muestra más abajo funciona, pero es fácil romperlo. Error frecuente: "optimizar" quitando los xmlns del <DTE> por parecer redundantes con el sobre. NO lo haga: el xmlns="http://www.sii.cl/SiiDte" del <DTE> es parte del documento firmado (se hereda al <Documento> al calcular el DigestValue). Si lo quita, el SII recalcula el digest con el namespace y no coincide → rechazo por "firma inválida". Ver Certificación SII.

Diferencia crítica por ambiente

• Producción → usar la API REST del SII (enviarBoleta) con los datos reales de resolución de la empresa.
• Certificación → la API REST no funciona para el proceso de certificación SII. Usar SOAP (enviarDteSoap) con resolución NroResol: 0 y la fecha de resolución de certificación que entrega el SII.

Usar los datos de empresa incorrectos para el ambiente (por ejemplo, datos de producción en certificación) provoca rechazo inmediato del SII.

Datos de resolución por ambiente

| Campo | Certificación | Producción | |-------|--------------|------------| | NroResol | 0 (siempre cero en cert.) | Número real de resolución SII | | FchResol | Fecha entregada por el SII al iniciar certificación | Fecha real de la resolución | | Método de envío | enviarDteSoap (SOAP) | enviarBoleta (REST) |

Para obtener la fecha y número de resolución de producción automáticamente desde el portal SII, ver SiiPortalAuth.

Certificación: SOAP (obligatorio)

const { DTE, CAF, Certificado, EnvioBOLETA, EnviadorSII } = require('@devlas/dte-sii')
const fs = require('fs')

const cert = new Certificado(fs.readFileSync('empresa_cert.pfx'), 'clave')
const caf  = new CAF(fs.readFileSync('caf_39_cert.xml', 'utf8'))

const dte = new DTE({ tipo: 39, folio: 1, emisor: { rut: '76543210-K', ... }, items: [ ... ] })
dte.generarXML().timbrar(caf).firmar(cert)

const envio = new EnvioBOLETA({ certificado: cert })
envio.agregar(dte)
envio.setCaratula({
  RutEmisor: '76543210-K',
  FchResol:  '2019-10-18',  // fecha de resolución de certificación (entregada por el SII)
  NroResol:  0,             // siempre 0 en certificación
})
envio.generar()

// SOAP - único método que funciona para certificación de boletas
const enviador = new EnviadorSII(cert, 'certificacion')
const resultado = await enviador.enviarDteSoap(envio)
console.log('TrackID:', resultado.trackId)

Producción: REST (recomendado)

const { DTE, CAF, Certificado, EnvioBOLETA, EnviadorSII } = require('@devlas/dte-sii')
const fs = require('fs')

const cert = new Certificado(fs.readFileSync('empresa_prod.pfx'), 'clave')
const caf  = new CAF(fs.readFileSync('caf_39_prod.xml', 'utf8'))

const dte = new DTE({ tipo: 39, folio: 1, emisor: { rut: '76543210-K', ... }, items: [ ... ] })
dte.generarXML().timbrar(caf).firmar(cert)

const envio = new EnvioBOLETA({ certificado: cert })
envio.agregar(dte)
envio.setCaratula({
  RutEmisor: '76543210-K',
  FchResol:  '2024-01-15',  // fecha real de resolución SII de la empresa
  NroResol:  123,           // número real de resolución SII de la empresa
})
envio.generar()

// REST - método estándar para producción
const enviador = new EnviadorSII(cert, 'produccion')
const resultado = await enviador.enviarBoleta(envio)
console.log('TrackID:', resultado.trackId)

Flujo con BoletaService

BoletaService simplifica la creación de boletas individuales. Aplica el mismo criterio de ambiente: usar enviarDteSoap para certificación y enviarBoleta para producción una vez que el servicio retorne el sobre.

const { BoletaService } = require('@devlas/dte-sii')
const fs = require('fs')

const service = new BoletaService()
service.cargarCertificado(fs.readFileSync('empresa.pfx'), 'clave_pfx')
service.cargarCAF(fs.readFileSync('caf_39.xml', 'utf8'))

const boleta = await service.crearBoleta({
  folio:      1,
  emisor:     { rut: '76543210-K', razonSocial: 'Mi Empresa', giro: 'Software', ... },
  items:      [{ nombre: 'Producto', cantidad: 1, precioConIva: 10000 }],
  resolucion: {
    fecha:  process.env.SII_AMBIENTE === 'certificacion' ? '2019-10-18' : '2024-01-15',
    numero: process.env.SII_AMBIENTE === 'certificacion' ? 0           : 123,
  },
})

Libros electrónicos y RCOF

LibroCompraVenta

const { LibroCompraVenta, Certificado } = require('@devlas/dte-sii')

const libro = new LibroCompraVenta()
libro.setCaratula({
  RutEmisorLibro: '76543210-K',
  RutEnvia:       '76543210-K',
  PeriodoTributario: '2024-06',
  FchResol: '2024-01-15', NroResol: 123,
  TipoOperacion: 'VENTA',  // o 'COMPRA'
  TipoLibro: 'MENSUAL',
  TipoEnvio: 'TOTAL',
  FolioNotificacion: 0,
})
libro.setResumen({ /* datos del resumen */ })
libro.setDetalle([ /* array de documentos */ ])
libro.generar().firmar(cert)

const enviador = new EnviadorSII(cert, 'produccion')
await enviador.enviarLibroSoap(libro)

ConsumoFolio (RCOF)

El RCOF es obligatorio para boletas y debe enviarse antes de las 08:00 del día siguiente.

const { ConsumoFolio, CAF, Certificado } = require('@devlas/dte-sii')

const rcof = new ConsumoFolio()
rcof.setCaratula({
  RutEmisor:  '76543210-K',
  FchResol:   '2024-01-15',
  NroResol:   0,
  FchInicio:  '2024-06-15',
  FchFinal:   '2024-06-15',
  SecEnvio:   1,
  TmstFirmaEnv: new Date().toISOString(),
})
rcof.agregar(dte, caf)
rcof.generar().firmar(cert)

const enviador = new EnviadorSII(cert, 'produccion')
await enviador.enviarRcofSoap(rcof)

Gestión de folios

Los folios son el recurso más crítico del ciclo de facturación: sin folio válido no hay DTE. La librería provee tres capas que se complementan:

| Capa | Clase | Responsabilidad | |------|-------|-----------------| | Local | FolioRegistry | Asigna y persiste folios desde un CAF ya descargado | | SII | FolioService | Consulta, solicita y anula rangos de folios ante el SII | | Automática | CafSolicitor | Descarga el XML del CAF nuevo directamente desde el portal SII |

El flujo típico de producción combina las tres: FolioRegistry asigna folios del CAF activo; cuando el rango se agota, CafSolicitor solicita un CAF nuevo al SII sin intervención humana; si quedan folios sin usar de un CAF anterior, FolioService los anula para mantener la contabilidad en orden.

FolioRegistry: registro local

FolioRegistry mantiene un JSON en disco que registra qué folios están reservados, usados o pendientes de confirmación. Previene la doble asignación incluso ante reinicios del proceso.

const { FolioRegistry, CAF, createCafFingerprint } = require('@devlas/dte-sii')
const fs = require('fs')

const registry    = new FolioRegistry()                    // persiste en disco (JSON)
const cafXml      = fs.readFileSync('caf_33.xml', 'utf8')
const caf         = new CAF(cafXml)
const fingerprint = createCafFingerprint(cafXml)           // hash único del CAF

// Reservar el siguiente folio disponible del rango del CAF
const folio = registry.reserveNextFolio({
  rutEmisor:      '76543210-K',
  tipoDte:        caf.getTipoDTE(),
  folioDesde:     caf.getFolioDesde(),
  folioHasta:     caf.getFolioHasta(),
  ambiente:       'produccion',
  cafFingerprint: fingerprint,
})

// ... generar y enviar el DTE ...

// Marcar folio como enviado al recibir trackId del SII
registry.markFolioSent({
  rutEmisor: '76543210-K', tipoDte: 33, folio,
  folioDesde: caf.getFolioDesde(), folioHasta: caf.getFolioHasta(),
  ambiente: 'produccion', cafFingerprint: fingerprint,
  trackId: '0245283324',
})

resolveCafPath busca automáticamente el CAF más reciente disponible con folios libres, evitando la necesidad de hardcodear rutas:

const { resolveCafPath } = require('@devlas/dte-sii')

const cafPath = resolveCafPath({
  tipoDte:       33,
  rutEmisor:     '76543210-K',
  requiredCount: 1,          // necesito al menos 1 folio disponible
  ambiente:      'produccion',
})
const cafXml = fs.readFileSync(cafPath, 'utf8')

FolioService: consulta, solicitud y anulación ante el SII

FolioService se comunica directamente con el SII para operar sobre folios: consultar el estado actual, solicitar un nuevo rango o anular folios no utilizados.

const { FolioService, Certificado } = require('@devlas/dte-sii')

const service = new FolioService({
  ambiente:    'produccion',
  rutEmisor:   '76543210-K',
  certificado: new Certificado(fs.readFileSync('empresa.pfx'), 'clave'),
})

// Consultar cuántos folios quedan y cuál fue el último emitido
const info = await service.consultarFolios({ tipoDte: 33 })
console.log('Último folio final:', info.ultimoFolioFinal)
console.log('Folios disponibles:', info.foliosDisponibles)

// Solicitar un nuevo rango de folios al SII
await service.solicitar({ tipoDte: 33, cantidad: 100 })

// Anular folios que nunca se usaron (evita descuadres en el SII)
await service.anularFolios({
  tipoDte:    33,
  folioDesde: 50,
  folioHasta: 60,
  motivo:     'Folios no utilizados por cambio de CAF',
})

CafSolicitor: obtención automática de CAF

CafSolicitor automatiza la descarga del XML del CAF desde el portal SII usando el certificado PFX, sin intervención manual. Es la pieza que cierra el ciclo de reposición automática de folios.

const { CafSolicitor, Certificado } = require('@devlas/dte-sii')

const solicitor = new CafSolicitor({
  certificado: new Certificado(fs.readFileSync('empresa.pfx'), 'clave'),
  ambiente:    'produccion',
})

const cafXml = await solicitor.solicitar({ tipoDte: 33, cantidad: 200 })
fs.writeFileSync('caf_33_nuevo.xml', cafXml)

Ciclo completo automatizado

El siguiente patrón implementa reposición y limpieza de folios sin intervención humana. Se recomienda ejecutarlo como un job periódico o al detectar que el CAF activo está por agotarse.

const {
  FolioRegistry, FolioService, CafSolicitor, CAF,
  Certificado, createCafFingerprint, resolveCafPath,
} = require('@devlas/dte-sii')
const fs   = require('fs')
const path = require('path')

const CAF_DIR    = path.join(__dirname, 'cafs')
const RUT        = '76543210-K'
const AMBIENTE   = 'produccion'
const TIPO_DTE   = 33
const UMBRAL     = 10   // solicitar nuevo CAF cuando queden menos de N folios
const CANTIDAD   = 200  // folios a solicitar

const cert      = new Certificado(fs.readFileSync('empresa.pfx'), 'clave')
const registry  = new FolioRegistry()
const service   = new FolioService({ ambiente: AMBIENTE, rutEmisor: RUT, certificado: cert })
const solicitor = new CafSolicitor({ certificado: cert, ambiente: AMBIENTE })

async function gestionarFolios() {
  // 1. Consultar estado actual en el SII
  const info = await service.consultarFolios({ tipoDte: TIPO_DTE })
  console.log(`Folios disponibles: ${info.foliosDisponibles}`)

  // 2. Solicitar nuevo CAF si quedan pocos folios
  if (info.foliosDisponibles < UMBRAL) {
    console.log('Solicitando nuevo CAF...')
    const cafXml  = await solicitor.solicitar({ tipoDte: TIPO_DTE, cantidad: CANTIDAD })
    const archivo = path.join(CAF_DIR, `caf_${TIPO_DTE}_${Date.now()}.xml`)
    fs.writeFileSync(archivo, cafXml)
    console.log(`Nuevo CAF guardado en: ${archivo}`)
  }

  // 3. Detectar folios reservados pero nunca enviados (caídos en error)
  //    y anularlos en el SII para mantener la contabilidad limpia
  const pendientes = registry.getFoliosPendientes({ rutEmisor: RUT, tipoDte: TIPO_DTE, ambiente: AMBIENTE })
  for (const rango of pendientes) {
    console.log(`Anulando folios caídos: ${rango.desde}-${rango.hasta}`)
    await service.anularFolios({
      tipoDte:    TIPO_DTE,
      folioDesde: rango.desde,
      folioHasta: rango.hasta,
      motivo:     'Folios reservados no emitidos por error de sistema',
    })
  }
}

// Ejecutar al inicio y luego cada hora
gestionarFolios().catch(console.error)
setInterval(() => gestionarFolios().catch(console.error), 60 * 60 * 1000)

Puntos clave del ciclo automatizado:

• FolioRegistry detecta folios que fueron reservados pero cuyo DTE nunca se envió exitosamente (por crash, timeout, etc.)
• FolioService.anularFolios limpia esos folios en el SII, previniendo descuadres en libros y RCOF
• CafSolicitor descarga el nuevo CAF directamente, sin necesidad de acceder al portal SII manualmente
• resolveCafPath hace que el código de emisión siempre use el CAF vigente, sin cambiar rutas hardcodeadas

Sesión y autenticación con el SII

SiiPortalAuth: autenticación al portal

Obtiene datos de empresa (nro_resol, fch_resol) directamente desde el portal SII usando el certificado PFX. Usa el patrón Singleton por certificado para evitar el límite de sesiones del SII.

const { SiiPortalAuth, Certificado } = require('@devlas/dte-sii')

const cert  = new Certificado(fs.readFileSync('empresa.pfx'), 'clave')
const auth  = new SiiPortalAuth(cert)

await auth.autenticar()
const datos = await auth.obtenerDatosEmpresa()
// datos.nro_resol   → número de resolución
// datos.fch_resol   → fecha de resolución (AAAA-MM-DD)
// datos.razon_social, datos.giro, etc.

// Reutilizar sesión entre componentes (evita múltiples logins)
const cookies = await SiiPortalAuth.getCookieStringForPfx(cert)

Caché de sesión: un mapa por certificado

Un login contra zeusr.sii.cl es un handshake con certificado, caro y contado por el SII, que bloquea el RUT por "máximo de sesiones autenticadas". Por eso las cookies se cachean en disco, en $DATADIR/sii_session_cache.json, con un TTL de 90 minutos.

Desde 2.16.0 el caché es un mapa por huella de certificado. Antes guardaba una sola sesión, así que en un servidor multi-tenant cada certificado invalidaba al anterior y todos re-autenticaban en cada pasada: el costo crecía lineal con la base de clientes.

• El formato viejo se migra, no se descarta.
• Poda automática: expiradas primero, y tope de 200 entradas.
• Escritura atómica y relectura previa, para que dos réplicas sobre el mismo volumen no se borren las sesiones entre sí.

SiiPortalAuth.limpiarSesionCache(certHash)   // borra una
SiiPortalAuth.limpiarSesionCache()           // borra todas

⚠️ En un servidor, apunta DATADIR a un volumen persistente. Sin eso el caché vive en el filesystem del contenedor y se pierde en cada redeploy, forzando un re-login de toda la base.

Reintento ante fallas de red/TLS

autenticar() reintenta 3 veces con espera progresiva (1s, 2s, 4s) ante errores de transporte.

⚠️ El SII devuelve EPROTO de forma intermitente al abrir la conexión TLS con certificado (rsa_pss ... last octet invalid), y reintentando con el mismo certificado funciona. No es señal de certificado vencido ni no habilitado, aunque lo parezca. Interpretarlo así marca como rotos certificados que están sanos.

El límite de sesiones nunca se reintenta (cada intento empeora el bloqueo) y se distingue por err.code === 'SII_LIMITE_SESIONES'.

SiiSession: sesiones HTTP autenticadas

const { SiiSession, Certificado } = require('@devlas/dte-sii')

const session = new SiiSession(new Certificado(fs.readFileSync('empresa.pfx'), 'clave'))
await session.loginWithCertificate()
const resp = await session.request('GET', 'https://herculesr.sii.cl/...')

Descargar el XML completo desde el portal (Respaldo MIPYME)

descargarRespaldoMipyme() baja el XML firmado completo de los DTE emitidos o recibidos desde el "Respaldo de archivos MIPYME" del portal (www1.sii.cl/cgi-bin/Portal001).

Es la única vía que entrega el documento entero: detalle línea por línea, CdgItem del proveedor, referencias y TED. obtenerDetalleDtes() solo trae metadatos y obtenerResumenRegistro() solo totales mensuales.

Requiere únicamente el certificado digital, no estar certificado como emisor.

🔴 Existe SOLO en producción: no hay ambiente de certificación. Medido sobre /cgi-bin/Portal001/lista_documentos.cgi: www1.sii.cl responde 200, maullin.sii.cl redirige a Error404 y www4c.sii.cl da 404 (para contrastar, una ruta real de maullin redirige al login de certificación, no a un 404).

Consecuencia para cualquier consumidor: con el resto del sistema apuntando a maullin, este método igual lee documentos reales del contribuyente. Es de solo lectura contra el SII, pero escribe facturas reales en la base del entorno que lo llame. Un entorno de desarrollo necesita una puerta explícita; no alcanza con mirar la variable de ambiente del DTE, porque esta función no tiene ambientes.

const auth = new SiiPortalAuth({ pfxBuffer, pfxPassword })

const { total, tramos } = await auth.descargarRespaldoMipyme('76543210', '6', {
  origen: 'RCP',            // 'ENV' emitidos | 'RCP' recibidos
  desde:  '2026-01-01',
  hasta:  '2026-08-18',
  tipoDoc: '',              // vacío = todos
  reintentos: 3,
})
// tramos: [{ desde, hasta, total, xml }, ...] — un XML por tramo

Modo streaming (onTramo) — obligatorio para históricos grandes

Sin onTramo todos los XML quedan en memoria hasta el final: ~6,4 KB por documento, o sea unos 7 MB para 1.100 documentos, y crece lineal.

await auth.descargarRespaldoMipyme(rut, dv, {
  origen: 'RCP', desde, hasta,
  onTramo: async (t) => { await guardar(t.xml) },   // se persiste y se suelta
})
// con onTramo, los tramos del resultado vienen SIN `xml`

Qué hay que saber del portal

| | | |---|---| | Tope de 20 por descarga | Es del servidor, no cosmético. Con 21 devuelve HTML de error, no un XML recortado. El método trocea el rango solo, del más reciente al más viejo. | | Un día con más de 20 | No se puede partir más por fecha: se lanza error explícito. Tiene salida cortando por TPO_DOC (un tipo de DTE por consulta). ⚠️ No usar FOLIO/FOLIOHASTA: borran FEC_HASTA en silencio y devuelven otro conjunto. | | Encoding | El XML viene en ISO-8859-1. Leerlo como utf8 rompe los acentos. | | Captcha | Hoy va vacío, pero el SII puede encenderlo sin avisar → RESPALDO_CAPTCHA. | | Alcance | Solo lo registrado en el sistema de facturación gratuito del SII. Un comercio que ya migró a otro sistema no encuentra ahí sus documentos nuevos. |

🔴 El portal viejo comunica sus rechazos por alert() de JavaScript, con HTTP 200 — no en el HTML visible ni en el <title>, que dice otra cosa. Y la página válida trae además un //alert(...) comentado. Clasificar por título, limpiar los <script> antes de parsear, o creerle al alert comentado: las tres cosas producen diagnósticos falsos.

Los errores traen err.mensajePortal con el texto exacto del SII. Mostrar ese texto, no una traducción propia.

⚠️ SIN_DATOS no es lo mismo que INDETERMINADO. El primero es un veredicto definitivo ("acá no hay nada") y el consumidor puede cerrar ese período para siempre. Los otros dos significan "no se pudo concluir" y "no pudimos preguntar": tratarlos igual cerró en falso un período que ya tenía 24 documentos bajados.

| código | qué pasó | ¿reintentar? | |---|---|---| | RESPALDO_SIN_DATOS | el RUT no tiene información en MIPYME | no | | RESPALDO_CAPTCHA | el SII encendió el captcha | no | | RESPALDO_RECHAZADO | rechazo con un texto que no conocemos; llega literal | no | | RESPALDO_INDETERMINADO | varios mensajes del template, sin veredicto único; llegan en err.mensajesPortal | sí, más tarde | | RESPALDO_SIN_EMPRESA | página de ingreso sin ningún alert; causa no determinada | no |

Contrato completo, respuestas reales y los errores que cuestan tiempo (es POST no GET; ORIGEN=ENV no EMI; el listado es obligatorio antes de la descarga) en la sección de arriba.

Aceptación y reclamo de DTE (WsReclamo)

WsReclamo implementa el web service WSRECLAMO del SII (v1.2) para registrar eventos de aceptación/rechazo de DTE por parte del receptor.

WsReclamo no se re-exporta desde index.js. Importar directamente:

const WsReclamo = require('@devlas/dte-sii/WsReclamo')
const { Certificado } = require('@devlas/dte-sii')

const ws = new WsReclamo(new Certificado(fs.readFileSync('empresa.pfx'), 'clave'), 'produccion')

// Consultar historial de eventos de un DTE
const eventos = await ws.listarEventosHistDoc({
  rutEmisor:   '76543210-K',
  tipoDTE:     33,
  folio:       1,
  rutReceptor: '12345678-9',
})

// Consultar estado desde la perspectiva del receptor
const estado = await ws.consultarEstadoReceptor({ ... })

// Registrar aceptación (ACD) o reclamo (RCD)
await ws.ingresarAceptacion({
  rutEmisor: '76543210-K', tipoDTE: 33, folio: 1,
  accion: 'ACD', // ACD=Aceptado, RCD=Reclamado, ERM=Otorga Mercaderías
})

Estados SII: Interpretación de respuestas

EnviadorSII clasifica automáticamente cada código en esExitoso, esIntermedio o esRechazado.

QueryEstUp - Estado del sobre de envío

| Código | Descripción | esExitoso | esIntermedio | esRechazado | |--------|-------------|:-----------:|:--------------:|:-------------:| | EPR | Envío Procesado | ✓ | | | | RPR | Procesado con Reparos | ✓ | | | | REC / SOK / FOK / CRT / PRD / PDR | En proceso de validación | | ✓ | | | RSC | Error en Schema XML | | | ✓ | | RFR | Error en Firma Digital | | | ✓ | | RCT | Error en Carátula | | | ✓ |

QueryEstDte - Estado del DTE individual

| Código | Descripción | Clasificación | |--------|-------------|---------------| | DOK | Datos coinciden | ✓ Exitoso | | DNK | Datos no coinciden | ~ Intermedio | | FAU | Folio no autorizado | ✗ Rechazado | | FNA | Emisor no habilitado | ✗ Rechazado | | FAN / AND / ANC | Anulado | ✗ Rechazado | | EMP | Empresa sin autorización | ✗ Rechazado |

Códigos de error de consulta (-1 a -14)

Los valores negativos son errores del servidor de consulta del SII, no rechazo del documento. Resultan en esIntermedio = true y pueden reintentarse.

Manejo de errores

Todos los errores operacionales lanzan DteSiiError con las propiedades:

| Propiedad | Descripción | |-----------|-------------| | code | Código de error (CERT_ERROR, DTE_ERROR, SII_ERROR, etc.) | | message | Mensaje descriptivo | | cause | Error original (si aplica) |

const { DteSiiError } = require('@devlas/dte-sii')

try {
  await enviador.enviarDteSoap(envio)
} catch (err) {
  if (err instanceof DteSiiError) {
    console.error(`[${err.code}] ${err.message}`)
  }
}

Configuración global y reintentos

const { configure, configureRetry } = require('@devlas/dte-sii')

// Configuración global (aplicar al inicio de la app)
configure({
  ambiente:          'produccion',  // 'produccion' | 'certificacion'
  defaultRutEmisor:  '76543210-K',
  tokenCacheTtlMs:   300_000,       // 5 minutos (default)
})

// Lógica de reintentos para llamadas al SII
configureRetry({
  maxAttempts:     3,
  initialDelayMs:  1_000,
  backoffFactor:   2,
  retryOn:         ['SII_TIMEOUT', 'SII_SERVER_ERROR'],
})

Utilidades

Accesibles como named exports o mediante el namespace utils:

const {
  // RUT
  formatRut, validarRut, calcularDV, splitRut,
  // Sanitización
  sanitizeSiiText, sanitizeRazonSocial, sanitizeNombreItem,
  // XML
  parseXml, parseXmlNoNs, buildXml, formatBase64InXml,
  // Cálculos monetarios
  calcularTotalesDesdeItems, calcularMontoItem, buildDetalle,
  // Construcción de entidades
  buildEmisor, normalizeEmisor, validarEmisor,
  buildReceptor, normalizeReceptor, RECEPTOR_CONSUMIDOR_FINAL,
  buildDocReferencia, buildReferenciasNcNd,
  createResolucion, createResolucionCertificacion,
  // Constantes
  TIPOS_DTE, TIPOS_BOLETA, NOMBRES_DTE, TASA_IVA,
  // Folios
  createCafFingerprint, findLatestCaf, resolveCafPath,
  // Endpoints SII
  SOAP_ENDPOINTS, REST_ENDPOINTS, getHost,
  // Token cache
  getCachedToken, setCachedToken, pruneExpiredTokens,
  // Logging
  logger, configureLogger, createScopedLogger,
} = require('@devlas/dte-sii')

Tabla de referencia rápida

| Función / Constante | Descripción | |---------------------|-------------| | formatRut(rut) | Formatea RUT chileno con puntos y guion | | validarRut(rut) | Valida dígito verificador | | calcularDV(rut) | Calcula dígito verificador de un RUT | | sanitizeSiiText(str) | Elimina caracteres no aceptados por el SII | | sanitizeRazonSocial(str) | Sanitiza razones sociales | | sanitizeNombreItem(str) | Sanitiza nombres de ítems | | calcularTotalesDesdeItems(items) | Calcula MntNeto, IVA, MntTotal | | buildEmisor(data) | Construye nodo <Emisor> | | buildReceptor(data) | Construye nodo <Receptor> | | RECEPTOR_CONSUMIDOR_FINAL | Objeto receptor para boletas sin RUT receptor | | TASA_IVA | 0.19 (IVA Chile) | | TIPOS_DTE | { FACTURA: 33, FACTURA_EXENTA: 34, ... } | | NOMBRES_DTE | Mapeo código → nombre legible | | createCafFingerprint(xml) | Hash único de un CAF (para FolioRegistry) | | findLatestCaf(tipoDte, dir) | Busca el CAF más reciente en un directorio | | resolveCafPath(opts) | Resuelve ruta de CAF con validación de folios disponibles | | getHost(ambiente) | URL base del host SII según ambiente |

Uso desde proyectos ESM (interop)

Esta librería es CommonJS. Para usarla desde un proyecto ESM (Node.js nativo o "type": "module"):

// Node.js ESM puro
import { createRequire } from 'module'
const require = createRequire(import.meta.url)
const { Certificado, CAF, DTE, EnviadorSII } = require('@devlas/dte-sii')

TypeScript con ESM :

import { createRequire } from 'module'
const _require = createRequire(import.meta.url)
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const { Certificado, CAF, DTE } = _require('@devlas/dte-sii') as Record<string, new (...a: any[]) => any>

// WsReclamo se importa directamente (no está en index.js):
const WsReclamo = _require('@devlas/dte-sii/WsReclamo')

TypeScript

La librería incluye tipos completos en dte-sii.d.ts. Interfaces principales:

import type {
  // Entidades
  Emisor, Receptor, DetalleItem, Totales,
  // DTEs
  DteDatos, DteSimplificado,
  // Configuración
  GlobalConfig, RetryConfig, TokenCacheConfig,
  // Errores
  DteSiiError,
} from '@devlas/dte-sii'

Referencia de clases

Clases principales

| Clase | Archivo | Descripción | |-------|---------|-------------| | Certificado | Certificado.js | Carga y gestiona certificados digitales PFX/P12; valida expiración | | CAF | CAF.js | Parsea CAF XML; valida rango de folios; firma TED | | DTE | DTE.js | Genera, timbra y firma documentos tributarios (todos los tipos) | | Signer | Signer.js | Firma XML-DSig compatible con SII (C14N + RSA-SHA1) | | EnvioDTE | Envio.js | Sobre XML para facturas, guías y notas | | EnvioBOLETA | Envio.js | Sobre XML para boletas electrónicas | | EnviadorSII | EnviadorSII.js | Comunicación SOAP/REST con el SII; caché de tokens; reintentos |

Servicios y gestión de folios

| Clase | Archivo | Descripción | |-------|---------|-------------| | BoletaService | BoletaService.js | Flujo simplificado para crear boletas electrónicas | | FolioRegistry | FolioRegistry.js | Registro local JSON de folios reservados/enviados | | FolioService | FolioService.js | Consulta, solicita y anula folios ante el SII | | CafSolicitor | CafSolicitor.js | Solicitud automatizada de CAF al SII | | SiiSession | SiiSession.js | Sesiones HTTP autenticadas con certificado (cookie jar) | | SiiPortalAuth | SiiPortalAuth.js | Autenticación al portal SII; datos de empresa; RCV; respaldo MIPYME (XML completo); caché de sesión por certificado |

Libros y reportes

| Clase | Archivo | Descripción | |-------|---------|-------------| | ConsumoFolio | ConsumoFolio.js | RCOF (Resumen Consumo de Folios) para boletas | | LibroCompraVenta | LibroCompraVenta.js | Libro electrónico de compras/ventas | | LibroGuia | LibroGuia.js | Libro electrónico de guías de despacho |

Web services complementarios

| Clase | Archivo | Descripción | |-------|---------|-------------| | WsReclamo | WsReclamo.js | WS WSRECLAMO v1.2: aceptación, reclamo e historial de eventos de DTE |

Estructura de archivos

dte-sii/
├── index.js              <- Punto de entrada; re-exporta todas las clases públicas
├── dte-sii.d.ts          <- Definiciones TypeScript (979 líneas)
│
├── Certificado.js        <- PFX/P12 loader
├── CAF.js                <- CAF parser
├── DTE.js                <- Document builder (XML, TED, firma)
├── Signer.js             <- XML-DSig
├── Envio.js              <- EnvioDTE + EnvioBOLETA
├── EnviadorSII.js        <- SOAP/REST con SII; caché tokens; reintentos
│
├── BoletaService.js      <- Flujo simplificado de boletas
├── SiiPortalAuth.js      <- Autenticación portal SII (Singleton)
├── SiiSession.js         <- Sesiones HTTP autenticadas
├── SiiSessionStore.js    <- Persistencia de sesiones
├── CafSolicitor.js       <- Solicitud automatizada de CAF
│
├── FolioRegistry.js      <- Registro local de folios (JSON)
├── FolioService.js       <- Gestión de folios ante el SII
│
├── LibroBase.js          <- Clase base para libros electrónicos
├── LibroCompraVenta.js   <- Libro compras/ventas
├── LibroGuia.js          <- Libro guías de despacho
├── ConsumoFolio.js       <- RCOF
│
├── WsReclamo.js          <- WS aceptación/reclamo de DTE
│
├── utils/                <- 20 módulos de utilidades (RUT, XML, cálculos, etc.)
├── cert/                 <- 19 módulos para automatización de certificación SII
└── docs/                 <- PDFs y XSDs oficiales del SII

Certificación SII

El directorio cert/ contiene los helpers necesarios para ejecutar el proceso de certificación ante el SII. Orquestado por CertRunner, incluye:

• Generación de sets básicos, de compra, exentos y guías
• Libros de compras, ventas y guías para certificación
• Envío de boletas de certificación
• Intercambio de DTE entre contribuyentes (simulación)
• Generación de muestras impresas

// Uso desde un proyecto ESM
const { CertFolioHelper } = require('@devlas/dte-sii')

Depuración: captura de llamadas al SII

Cuando el SII rechaza algo, el motivo viene en el HTML o el XML que devuelve, y sin ese cuerpo guardado no hay forma de saber qué pasó. utils/httpDebug.js graba todas las llamadas HTTP de la librería.

Está apagado por defecto: solo actúa si defines SII_HTTP_DEBUG_DIR. Sin esa variable el costo es una comparación por request, así que se puede dejar el código como está en producción.

SII_HTTP_DEBUG_DIR=/tmp/sii-debug node tu-script.js

Deja en ese directorio:

001-POST-DTEUpload-200.html          <- respuesta (cabecera con URL, status, ms, cliente)
001-POST-DTEUpload-200-request.txt   <- cuerpo enviado, si supera 2000 caracteres
index.jsonl                          <- una línea por llamada, para grep/jq

# ¿Qué llamadas hizo y cuánto tardó cada una?
jq -r '"\(.n) \(.method) \(.url) -> \(.status) \(.ms)ms [\(.cliente)]"' /tmp/sii-debug/index.jsonl

Cubre los cinco clientes HTTP de la librería, que son independientes entre sí: SiiSession, SiiPortalAuth, EnviadorSII, CertRunner/BoletaCert y WsReclamo.

Se redactan set-cookie, cookie, authorization y <RSASK> (la llave privada RSA del CAF). Aun así, el resto del contenido son documentos tributarios: trata ese directorio como material sensible y púrgalo.

Para dirigir la captura por etapa, redefine la variable antes de cada bloque: se lee en cada llamada, no una sola vez al cargar el módulo.

Ambientes

| Ambiente | Constante | Descripción | |----------|-----------|-------------| | 'certificacion' | - | Apunta a maullin.sii.cl - para pruebas y certificación | | 'produccion' | - | Apunta a palena.sii.cl - producción real |

Siempre verifica la variable de entorno SII_AMBIENTE (o el parámetro ambiente) antes de ejecutar código DTE para evitar envíos accidentales a producción.

TZ es obligatoria

Define TZ=America/Santiago en el proceso que use esta librería.

CertRunner construye fechas con la hora local al declarar avance y libros. Con el proceso en UTC, entre las ~20:00 y medianoche de Chile genera la fecha del día siguiente: un envío registrado el día 11 se declara como del 12 y el SII responde "FECHA NO CORRESPONDE AL ENVIO", dejando el flujo esperando algo que nunca va a llegar.

Para comprobarlo no sirve date: dentro de un contenedor sin tzdata miente. Usa node -e "console.log(new Date().toString())".

Acentos en el timbre (TED)

El lector de PDF417 del SII pierde los bytes ≥ 128: Cajón llega como Cajnn y el timbre no valida. Por eso DTE normaliza a ASCII RznSocRecep y NmbItem solo dentro del TED, antes de firmarlo.

El cuerpo del DTE conserva las tildes: el documento impreso y el XML que recibe el receptor se ven correctos. Si generas el PDF417 por tu cuenta, respeta esa misma regla.

Contribuir

Los PRs son bienvenidos. Antes de escribir código, lee CONTRIBUTING.md.

Esta librería emite documentos tributarios reales, así que el estándar de evidencia es más alto que en una librería común. En resumen: un PR por cambio, evidencia declarada por nivel (lectura, test, artefacto adjunto, respuesta del SII), y trazar el radio de impacto, porque un valor que entra acá sale por siete lugares distintos y el código de barras firmado es uno de ellos.

npm test        # suite completa, sin red ni SII
npm run scan    # barrido de datos reales (este repo es público)
npm run types   # verificación de dte-sii.d.ts

Las tres corren en CI sobre cada PR, en Node 18, 20 y 22.

Si trabajas con un agente de código, el repo trae la skill pr-dte-sii con estas reglas en formato ejecutable.

Seguridad

Si encuentras un problema de seguridad, no abras un issue público. Ver SECURITY.md para el canal privado y el alcance.

Licencia

MIT - Copyright (c) 2026 Devlas SpA

Implementa el protocolo XML público del SII de Chile. Inspirada conceptualmente en LibreDTE de SASCO SpA.