Referencia de la API

Esta sección lista todas las exportaciones de los cuatro puntos de entrada de dte-sdk: funciones, constantes, clases y tipos. Las firmas y las descripciones salen del código fuente de la biblioteca, donde cada símbolo tiene JSDoc bilingüe, así que lo que lees aquí es lo que muestra tu editor al pasar el cursor. Si una página y el código discrepan, tiene razón el código: abre un issue.

Los cuatro puntos de entrada#

El paquete es solo ES modules y requiere Node 22.12 o superior; un proyecto CommonJS igual puede hacer require(). DteError e isDteError vienen de dte-sdk y reconocen lo que lanza cualquier entrada. Para saber qué entrada importar en cada caso, ver Puntos de entrada.

Convenciones#

Estas reglas valen para los cuatro puntos de entrada. Una vez que las conoces, cualquier firma de función se lee igual.

Clientes como datos planos y funciones libres#

No hay clases que instanciar ni métodos que llamar, salvo DteError. createSiiClient y createPortalClient validan sus opciones y devuelven un objeto de datos congelado con todos los campos resueltos. Cada operación es una función libre que recibe ese cliente como primer argumento:

import { createSiiClient, uploadEnvelope } from 'dte-sdk'
 
const sii = createSiiClient({ environment: 'certification', certificate, companyRut: '76543210-3' })
const receipt = await uploadEnvelope(sii, { envelope })

Los documentos, los sobres y los libros siguen el mismo estilo: construyes un valor, se lo pasas a una función y recibes otro valor (Document, StampedDocument, SignedDocument).

Objetos de opciones#

Una función que recibe más de un par de entradas recibe un solo objeto (createSiiClient(options), uploadEnvelope(sii, input)). Los campos opcionales llevan ? en las tablas de campos, y la descripción indica el valor por defecto.

El reloj: now#

Todo lo que lee la hora puede recibirla. Las funciones puras reciben un now: Date opcional (en un objeto de opciones o como último argumento, por ejemplo chileDate(now)). Los clientes y los flujos largos reciben now: () => Date, y los que esperan reciben además un sleep inyectable. Los tests los usan para no depender del reloj real.

import { createDocument } from 'dte-sdk'
 
const doc = createDocument(input, { now: new Date('2026-11-06T12:00:00Z') })

Sobreescrituras por llamada para las llamadas al SII#

Las operaciones que hablan con el SII (las funciones de los servicios web y las operaciones del portal) aceptan un CallOverrides como último argumento: signal para cancelar, timeoutMs para esa llamada y retry para cambiar o desactivar la política de reintentos de esa llamada.

import { waitForUploadStatus } from 'dte-sdk'
 
const controller = new AbortController()
const status = await waitForUploadStatus(sii, { trackId }, { signal: controller.signal, retry: false })

Una operación que cambia estado en el SII (un envío, un reclamo) aplica además su propia regla de reintento, más estricta que la política. Una política puede restringir lo que se reintenta, pero nunca ampliarlo.

Modelo en inglés y etiquetas del SII#

El modelo de dominio está en inglés (totalAmount, issuer.businessName). Los constructores de XML y el codec (toSiiDocument, fromSiiDocument, toSiiPurchaseSalesBook, …) lo traducen a las etiquetas oficiales del SII (MntTotal, RznSoc) en el orden del esquema. Los tipos Sii* describen esas etiquetas.

Inmutabilidad#

Los clientes están congelados en tiempo de ejecución. Los tipos del modelo son readonly y las funciones devuelven valores nuevos en vez de modificar sus argumentos: createDocument es pura, stampDocument devuelve un StampedDocument y signDocument un SignedDocument.

Errores: DteError#

Todo lo que lanza el SDK es un DteError con un code estable y un details estructurado. Discrimina por error.code, nunca por el mensaje: el mensaje es genérico y nunca lleva un RUT ni texto libre.

import { isDteError } from 'dte-sdk'
 
try {
  await uploadEnvelope(sii, { envelope })
} catch (error) {
  if (isDteError(error) && error.code === 'SII_UPLOAD_REJECTED') {
    // error.details.status es el estado de envío del SII
  }
  throw error
}

Los códigos están listados en Errores y explicados en Errores.

Puertos que puedes reemplazar#

El transporte, la caché de tokens, el logger, la captura HTTP, el archivo de envíos, el almacén de folios y el almacén de certificación son funciones u objetos simples que tú pasas. Los valores por defecto son en memoria, silenciosos o apagados; dte-sdk/node ofrece versiones en disco.

Cómo leer estas páginas#

• Los bloques de código listan funciones y constantes como declaraciones de TypeScript. El comentario sobre cada una son las primeras frases de su JSDoc en español. Una firma que quedaría demasiado larga se muestra con sus parámetros en líneas separadas. Un parámetro desestructurado se muestra como input.
• Las tablas de tipos listan los tipos de un grupo con su descripción. Un alias corto va seguido de su definición.
• Las tablas de campos (Campos de …) detallan los tipos de opciones y de resultado que más usas. Un ? después del nombre de un campo lo marca como opcional.
• Un último parámetro load o loadModules existe solo para que los tests del propio SDK reemplacen los módulos de Node. Se omite de las firmas.
• Cada página de entrada parte con su línea de importación, y los grupos siguen el orden en que los usarías.
• Cada grupo enlaza a la guía que explica cómo usarlo.