Características

dte-sdk cubre la vida completa de un documento tributario electrónico (DTE) chileno: construirlo, totalizarlo, timbrarlo con un CAF, firmarlo con tu certificado, agruparlo en un sobre, enviarlo al SII y seguir su estado. Alrededor de la emisión cubre también la verificación de los documentos que te envían tus proveedores, los libros del SII, el portal (folios, el registro de compras y ventas), el proceso de certificación y las muestras impresas. Esta página es el mapa: las páginas de la sección, cómo encajan las piezas de la emisión y qué tienen en común todas las funciones del SDK.

Las páginas#

Cómo se componen las piezas de la emisión#

Emitir un documento es una cadena corta. Cada paso recibe la salida del anterior y devuelve un objeto nuevo, así que puedes detenerte en cualquier punto, mirar el resultado y seguir.

En código, paso a paso:

import { readFileSync } from 'node:fs'
import {
  createDocument,
  createEnvelope,
  createSiiClient,
  loadCertificateFromPkcs12,
  parseCaf,
  signDocument,
  signEnvelope,
  stampDocument,
  uploadEnvelope,
  waitForUploadStatus,
} from 'dte-sdk'
 
const certificate = loadCertificateFromPkcs12(readFileSync('firma.pfx'), process.env.PFX_PASSWORD!)
const caf = parseCaf(readFileSync('caf-33.xml', 'utf8'))
 
const document = createDocument(input) // Document: validado, con los totales calculados
const stamped = stampDocument(document, caf) // StampedDocument: agrega el TED
const signed = signDocument(stamped, certificate) // SignedDocument: signed.xml
 
const envelope = signEnvelope(
  createEnvelope({
    kind: 'dte',
    documents: [signed],
    cover: {
      issuerRut: '76543210-3',
      senderRut: certificate.rut!,
      resolutionDate: '2026-10-31',
      resolutionNumber: 0,
    },
  }),
  certificate,
)
 
const sii = createSiiClient({ environment: 'certification', certificate, companyRut: '76543210-3' })
const receipt = await uploadEnvelope(sii, { envelope })
const status = await waitForUploadStatus(sii, { trackId: receipt.trackId })

Cuando no necesitas detenerte a la mitad, issueDocument ejecuta los tres primeros pasos en una sola llamada:

import { issueDocument } from 'dte-sdk'
 
const signed = issueDocument({ document: input, caf, certificate })

Dos helpers sirven en cualquier punto de la cadena: calculateTotals para totalizar un carrito antes de que exista un documento, y buildDocumentXml o toSiiDocument (Documentos) para mirar lo que se enviará. Las boletas (39, 41) van en su propio tipo de sobre, 'receipt' (EnvioBOLETA); mira Sobres.

Qué tienen en común todas las funciones#

Estas reglas valen en todo el SDK, así que las aprendes una sola vez.

• Un modelo tipado en inglés, documentado en dos idiomas. Los campos están en inglés legible (issuer.businessName, totalAmount), y un codec los convierte a las etiquetas oficiales del SII (RznSoc, MntTotal) en orden de esquema. Cada tipo, función y campo trae JSDoc en inglés y español, con la etiqueta del SII que representa, así tu editor muestra ambos.
• Datos planos y funciones libres. No hay clases que instanciar. Un Certificate, un Caf, un Document o un cliente del SII es un objeto plano, y cada operación es una función que lo recibe como argumento (signDocument(stamped, certificate), uploadEnvelope(sii, …)).
• Resultados inmutables. Una función nunca modifica lo que le pasas; devuelve un objeto nuevo. stampDocument devuelve tu documento más un ted, y el original queda como estaba. Los tipos son readonly.
• El reloj es inyectable. Todo lo que depende de la hora (la fecha de emisión, TSTED, TmstFirma, los chequeos de vencimiento del certificado y del CAF) acepta { now: Date }, así los tests son deterministas. Sin él, el SDK usa la hora de Chile (America/Santiago), nunca la zona horaria del proceso.
• Una sola clase de error con códigos estables. Todo lanza DteError. Discrimina por error.code, nunca por el mensaje. Los mensajes son genéricos y no llevan RUT, nombres, montos ni llaves; el valor ofensivo, si lo hay, vive en error.details. isDteError(value) lo reconoce y errorCode(value) entrega su código. Mira Errores.
• Identidad con rut.ts. Cada RUT se valida y normaliza con rut.ts a la forma que usan los esquemas del SII (12345678-5).
• Las respuestas de negocio son datos. El estado de un envío y el resultado de un reclamo vuelven clasificados (accepted, rejected, un código de reclamo) para que actúes sobre ellos; los errores son para lo que falló en el transporte o en tu entrada.

import { createDocument, isDteError } from 'dte-sdk'
 
try {
  createDocument({ ...input, items: [{ name: 'x'.repeat(81), unitPrice: 1 }] })
} catch (error) {
  if (isDteError(error)) {
    error.code // 'FIELD_TOO_LONG'
    error.details // { field: 'NmbItem', maxLength: 80, length: 81, value: '…' }
  }
}

Dónde vive cada área#

El paquete tiene cuatro puntos de entrada. La raíz corre en cualquier parte; los otros necesitan Node.

La entrada raíz nunca menciona un módulo node:: es la parte que puedes empaquetar para un navegador o correr en un runtime de borde. El paquete publica solo módulos ES (un proyecto CommonJS igual puede usar require()) y necesita Node 22.12 o superior. Mira Puntos de entrada para los detalles e Instalación para instalarlo y fijar la versión.

Siguientes pasos#

• Sigue un flujo completo en Emitir una factura, Emitir una nota de crédito y Emitir una boleta.
• Aprende las piezas (folios, CAF, certificados, ambientes) en Conceptos.
• Lee Estado antes de planificar algo alrededor del SII real.