dte-sdk

Un SDK TypeScript sin dependencias para documentos tributarios electrónicos (DTE) de Chile: crea, timbra, firma y envía al SII facturas, boletas, guías de despacho y notas de crédito o débito, con una API tipada y pequeña.

Versión preliminar. El paquete publicado dte-sdk@0.0.2 es un placeholder que solo exporta hello(). Estas páginas documentan la API planificada para la 1.0: nombres y firmas todavía pueden cambiar antes del lanzamiento. Sigue el avance en GitHub.

Por qué dte-sdk#

Emitir un DTE exige acertar en muchos detalles pequeños: un esquema XML, codificación ISO-8859-1, IVA redondeado a pesos enteros, un timbre electrónico firmado con la llave del CAF, una firma XMLDSig hecha con tu certificado y una autenticación con el SII antes de poder subir cualquier cosa. dte-sdk convierte cada uno de esos pasos en una función enfocada:

Documentos validados

createDte() revisa RUT, montos y campos obligatorios desde el inicio y devuelve un documento inmutable. Los errores aparecen en tu código, no días después en el SII.

Totales confiables

CLP enteros, redondeo half-up, IVA de 19%, líneas exentas y boletas con precios brutos, calculados siempre de la misma forma.

Timbra y firma donde sea

Generación del TED con tu CAF y firma XMLDSig sobre Web Crypto. El mismo código corre en Node, Deno, Bun y el navegador.

Cuidadoso con los secretos

Los mensajes de error nunca incluyen RUT, montos, llaves del CAF ni contraseñas del certificado. Sin dependencias en runtime, unos 8,4 KB min+gzip.

El ciclo de vida de un vistazo#

Todo documento pasa por los mismos cinco pasos. Cada función recibe el resultado de la anterior, y los tipos impiden saltarse un paso: no puedes firmar un documento sin timbrar, ni enviar uno sin firmar.

Paso	Función	Qué ocurre
1. Crear	`createDte()`	Valida la entrada y calcula los totales
2. Timbrar	`stampDte()`	Genera el TED (timbre electrónico) con el CAF que cubre el folio
3. Firmar	`signDte()`	Firma el documento con tu certificado digital (XMLDSig)
4. Enviar	`sendToSii()`	Lo envuelve en un `EnvioDTE`, se autentica y lo sube; devuelve un track id
5. Consultar	`getStatus()`	Pregunta al SII si el documento fue aceptado

calculateTotals() y toXml() son utilidades que puedes usar en cualquier paso, mientras que parseCaf() y loadCertificate() cargan las dos credenciales que necesita el flujo. Esa es toda la superficie: nueve funciones.

Ejemplo rápido#

TypeScript

import { createDte, DTE_TYPES } from 'dte-sdk'
 
const invoice = createDte({
  type: 33,
  folio: 1024,
  issuer: {
    rut: '76.123.456-0',
    businessName: 'Arrow Software SpA',
    activity: 'Desarrollo de software',
    acteco: 620200,
    address: 'Av. Providencia 1234',
    commune: 'Providencia',
  },
  receiver: {
    rut: '77.654.321-7',
    businessName: 'Comercial Los Andes Ltda.',
    activity: 'Comercio al por menor',
    address: 'Huérfanos 1055',
    commune: 'Santiago',
  },
  items: [{ name: 'Licencia anual', quantity: 1, unitPrice: 120000 }],
})
 
DTE_TYPES[invoice.type] // 'Factura electrónica'
invoice.totals          // { net: 120000, exempt: 0, vatRate: 19, vat: 22800, total: 142800 }

Desde aquí, stampDte(), signDte() y sendToSii() llevan el documento el resto del camino. El Inicio rápido recorre los cinco pasos.

Qué vas a necesitar#

El paquete se encarga del formato, la criptografía y el transporte. Para emitir documentos que el SII acepte también necesitas tres cosas que solo el SII y un proveedor de certificación pueden darte:

Un CAF por cada tipo de documento que emitas: el archivo que autoriza un rango de folios.
Un certificado digital (.pfx o .p12) de una persona autorizada para firmar por la empresa.
Autorización como emisor electrónico: el número y la fecha de la resolución del SII, o acceso al ambiente de certificación mientras haces pruebas.

Conceptos clave explica cada uno. Los dos primeros son secretos: lee Seguridad antes de llevarlos a un servidor.

A dónde ir ahora#

Instalación

Instala con npm, pnpm, bun o yarn, y verifica tu configuración.

Inicio rápido

Emite una factura tipo 33 de punta a punta, de la creación a la aceptación.

Conceptos clave

Tipos de DTE, folios y CAF, el TED, certificados y estados del SII.

Características

Cada paso del ciclo de vida en detalle.

Ejemplos

Flujos completos de factura y nota de crédito listos para copiar.

Referencia de la API

Cada firma, tipo, constante y código de error.

Licencia#

MIT © Arrow Software. Libre para uso personal y comercial, incluidos productos de código cerrado y de pago, sin límite de uso y sin atribución requerida más allá de mantener el aviso de licencia.

Siguiente →Instalación