Instalación

dte-sdk es un solo paquete con cuatro puntos de entrada, solo módulos ES y con los tipos incluidos. Esta página cubre los requisitos, cómo instalarlo y fijar su versión, los paquetes opcionales para las muestras impresas y una prueba de que todo funciona.

Requisitos#

• Node.js 22.12 o superior (engines: node >=22.12). Bun y Deno también ejecutan la entrada raíz, y el CI importa cada entrada en ambos.
• Solo módulos ES. El paquete no trae compilación CommonJS. Desde Node 22.12, un proyecto CommonJS igual puede cargarlo con require(), que devuelve el mismo módulo que entrega un import.
• Un gestor de paquetes: npm, pnpm, bun o yarn.
• TypeScript es opcional. Los tipos vienen incluidos (no hay un paquete @types que instalar) y la librería también funciona en JavaScript puro.

Agregar el paquete#

npm install dte-sdk

Eso instala junto las cuatro dependencias de ejecución: node-forge, @xmldom/xmldom, fast-xml-parser y rut.ts (la librería de RUT de los mismos autores). No se necesita nada más para emitir, timbrar, firmar y enviar documentos.

Fija la versión#

Antes de la 1.0.0 cualquier versión puede cambiar la API, así que instala una versión exacta y pasa a la siguiente a propósito, después de leer su changelog:

npm install --save-exact dte-sdk@0.8.0

Cada versión se publica desde el CI con procedencia de npm, así que npm audit signatures puede comprobar que el paquete que instalaste se construyó desde este repositorio. La página de estado del proyecto dice qué ha probado cada área hasta ahora.

Muestras impresas: dos paquetes opcionales#

Las muestras impresas (dte-sdk/pdf) dibujan PDF y timbres PDF417 con pdf-lib y bwip-js. Son dependencias peer opcionales: no entran en tu instalación a menos que las pidas y se cargan solo cuando renderizas algo.

npm install pdf-lib bwip-js

Sin ellos, las funciones de render lanzan un DteError con código DEPENDENCY_UNAVAILABLE, y details.module nombra el paquete que falta. Nada fuera de dte-sdk/pdf los necesita. Revisa Puntos de entrada.

TypeScript#

Los tipos vienen con el paquete y cada entrada tiene sus propias declaraciones. Para las entradas con subruta (dte-sdk/node, dte-sdk/portal, dte-sdk/pdf) el paquete declara tanto exports como typesVersions, de modo que se resuelven con "moduleResolution": "nodenext", "bundler" y el antiguo "node10". Las pruebas cargan la compilación bajo los tres.

Un tsconfig.json típico para un proyecto Node:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true
  }
}

Verifica la instalación#

import { calculateTotals } from 'dte-sdk'
 
// Una línea de 100000 pesos neto, en una factura (tipo 33)
const totals = calculateTotals([{ amount: 100000 }], { type: 33 })
 
console.log(totals)

node check.mjs

{ netAmount: 100000, vatRate: 19, vatAmount: 19000, totalAmount: 119000 }

const { calculateTotals } = require('dte-sdk')
 
console.log(calculateTotals([{ amount: 2000 }], { type: 39, pricesIncludeVat: true }))
// { netAmount: 1681, vatAmount: 319, totalAmount: 2000 }

Qué necesitas además del paquete#

El paquete se ocupa del formato, la criptografía y el transporte. Para emitir documentos que el SII acepte necesitas además:

• Un CAF por cada tipo de documento que emitas. El SII autoriza los folios por rangos mediante este archivo, que contiene una llave privada. Trátalo como un secreto.
• Un certificado digital (.pfx o .p12, o una llave y un certificado en PEM) de una persona autorizada para firmar por la empresa. Las claves salen de tu entorno (por ejemplo process.env.PFX_PASSWORD), nunca de tu código fuente.
• 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 pruebas.

Conceptos básicos explica cada uno y Seguridad cubre cómo proteger los secretos.

Siguientes pasos#