Inicio rápido

loadCertificateFromPkcs12() recibe los bytes de un archivo .pfx o .p12 (sirven los cifrados antiguos y los modernos) y su clave. Si en cambio tienes una llave y un certificado en PEM, usa loadCertificateFromPem(). La clave sale de tu entorno, nunca de tu código.

import { readFileSync } from 'node:fs'
import { loadCertificateFromPkcs12, loadCertificateFromPem } from 'dte-sdk'
 
const certificate = loadCertificateFromPkcs12(readFileSync('firma.pfx'), process.env.PFX_PASSWORD!)
 
// O desde PEM (una llave PKCS#1 o PKCS#8 sin cifrar):
// const certificate = loadCertificateFromPem({
//   privateKeyPem: readFileSync('firma.key.pem', 'utf8'),
//   certificatePem: readFileSync('firma.cert.pem', 'utf8'),
// })
 
certificate.rut // el RUT del titular, leído del certificado (o null)
certificate.notAfter // cuándo vence

Ambos cargadores comprueban que la llave corresponda al certificado y que este no haya vencido. Lanzan CERT_PASSWORD_WRONG, CERT_INVALID o CERT_EXPIRED; pasa { allowExpired: true } como último argumento para cargar igual un certificado vencido (en pruebas).

parseCaf() lee el XML que descargaste del SII y valida su estructura, tipo, rango y llave. El CAF contiene una llave privada: mantenlo fuera del control de versiones y de los logs.

import { parseCaf } from 'dte-sdk'
 
const caf = parseCaf(readFileSync('caf-33.xml', 'utf8'))
 
caf.documentType // 33
caf.range // { from: 1, to: 100 }
caf.authorizationDate // '2026-10-31'

Tú eliges el folio, dentro del rango del CAF. El SDK no recuerda qué folios ya usaste; la entrada dte-sdk/portal trae un registro local de folios para eso (Folios y CAF).

issueDocument() ejecuta todo el flujo: valida la entrada y calcula los totales (createDocument), timbra el documento con el CAF (stampDocument) y lo firma con tu certificado (signDocument).

import { issueDocument } from 'dte-sdk'
 
const issuer = {
  rut: '76543210-3',
  businessName: 'Comercial Andina SpA',
  businessActivity: 'Software',
  address: 'Av. Los Aromos 1540',
  commune: 'Santiago',
  activityCode: 620200,
}
 
const invoice = issueDocument({
  document: {
    type: 33,
    folio: 1,
    issuer,
    receiver: {
      rut: '12345678-5',
      businessName: 'Comercializadora Rapel Ltda',
      businessActivity: 'Comercio',
      address: 'Pasaje Los Olmos 88',
      commune: 'Providencia',
    },
    items: [{ name: 'Plan anual', quantity: 1, unitPrice: 100000 }],
  },
  caf,
  certificate,
})

Sin issueDate, el documento toma la fecha de hoy en Chile. Se comprueba el vencimiento del CAF (pasa checkCafExpiry: false para omitirlo), y un folio fuera del rango, un CAF de otro tipo o de otro emisor y cualquier campo inválido lanzan un DteError antes de firmar nada.

invoice.header.totals
// { netAmount: 100000, vatRate: 19, vatAmount: 19000, totalAmount: 119000 }
 
invoice.ted.xml // el timbre electrónico <TED>
invoice.xml // el <DTE> firmado, sin prólogo XML

Los montos son pesos enteros, redondeados línea por línea, como los revisa el SII. El resultado de issueDocument() es un SignedDocument: el propio documento más ted, xml, signedAt y signature.

El SII recibe los documentos dentro de un sobre. createEnvelope() agrupa documentos firmados bajo una carátula (Carátula) y signEnvelope() firma el SetDTE con el certificado de la persona que envía.

import { createEnvelope, signEnvelope, encodeLatin1 } from 'dte-sdk'
 
const envelope = signEnvelope(
  createEnvelope({
    kind: 'dte',
    documents: [invoice],
    cover: {
      issuerRut: '76543210-3',
      senderRut: certificate.rut!,
      resolutionDate: '2024-01-15',
      resolutionNumber: 123,
    },
  }),
  certificate,
)
 
envelope.xml // <?xml version="1.0" encoding="ISO-8859-1"?> <EnvioDTE> …
encodeLatin1(envelope.xml) // los bytes, si quieres guardar el archivo

Los campos de la carátula son issuerRut, senderRut (el titular del certificado que firma), resolutionDate (AAAA-MM-DD o DD-MM-AAAA), resolutionNumber (0 en certificación) y, opcionalmente, receiverRut (por defecto el SII), signedAt y setId (ambos se generan si se omiten). kind: 'dte' produce un EnvioDTE. Un sobre sin documentos lanza ENVELOPE_EMPTY y uno que mezcla boletas con otros documentos lanza ENVELOPE_KIND_MISMATCH.

createSiiClient() devuelve datos planos: cada operación es una función libre que recibe el cliente como primer argumento. Los tokens se obtienen y se renuevan solos.

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

environment es 'certification' (el ambiente de pruebas del SII, maullin) o 'production' (palena). El certificado firma la semilla que entrega el SII y su titular es el remitente por defecto. El cliente también recibe transport (fetch por defecto), retry, timeouts, logger, capture y archive, entre otros: revisa Servicios web del SII.

import { uploadEnvelope } from 'dte-sdk'
 
const upload = await uploadEnvelope(sii, { envelope })
 
upload.trackId // el identificador de seguimiento del SII para este envío (solo dígitos)
upload.receivedAt // cuándo lo recibió el SII, hora de Chile
upload.duplicate // true si el SII ya tenía este archivo y devolvió el track id original

El XML sube como bytes ISO-8859-1, así que debe abrir con una declaración XML que nombre ISO-8859-1; los sobres que arma este SDK lo hacen. Un rechazo lanza SII_UPLOAD_REJECTED, con el STATUS del SII como número y sus líneas de error en details.

El SII valida el sobre de forma asíncrona. waitForUploadStatus() consulta cada intervalMs (5000 por defecto) hasta que el estado deja de ser pending, o se rinde tras timeoutMs (600000 por defecto).

import { waitForUploadStatus } from 'dte-sdk'
 
const status = await waitForUploadStatus(sii, { trackId: upload.trackId, channel: upload.channel })
 
status.status // 'accepted' | 'acceptedWithObjections' | 'rejected' | …
status.message // la glosa del SII, en español
status.code // el código propio del SII, por ejemplo 'EPR'
status.counts // { reported, accepted, rejected, objections } cuando el SII los entrega, si no null

status.status es la clase del código del SII: accepted (por ejemplo EPR, "Envío procesado"), acceptedWithObjections (RPR), rejected (por ejemplo RCH o RSC) o unknown para un código que el SDK no conoce. status.raw conserva la respuesta del SII tal como llegó. Si el SII no se pronuncia a tiempo, la espera lanza WAIT_TIMEOUT con el último código que vio; puedes volver a consultar más tarde con el mismo track id.

queryUploadStatus() consulta una sola vez, sin esperar. Pasa channel: upload.channel para consultar el estado por el canal por el que subió el sobre (soap en un EnvioDTE).