Conceptos clave

Una introducción breve y práctica al sistema de facturación electrónica de Chile: el vocabulario que vas a encontrar en la documentación del SII y en la API de dte-sdk. No necesitas memorizarlo, pero saber qué es un CAF o un TED hace que cada código de error sea más fácil de entender.

¿Qué es un DTE?#

Un DTE (Documento Tributario Electrónico) es un documento tributario (una factura, una boleta, una guía de despacho o una nota) emitido como un archivo XML firmado e informado al SII (Servicio de Impuestos Internos). El XML es el documento legal. Una copia impresa o en PDF es solo su representación, y lleva un código de barras para que cualquiera pueda contrastarla con el original.

Un DTE se identifica por tres valores: el RUT del emisor, el tipo de documento y el folio. La combinación es única: el SII no acepta dos documentos que compartan los tres.

Tipos de documento#

El tipo es un código numérico. dte-sdk soporta ocho:

En cualquier tipo puedes marcar líneas con exempt: true para dejarlas fuera de la base del IVA. La constante DTE_TYPES asocia cada código con su nombre oficial, que es el que corresponde imprimir en el documento.

Folios y el CAF#

El folio es el número del documento dentro de su tipo. Los folios no se eligen libremente: el SII los autoriza por rangos, por tipo de documento, mediante un CAF (Código de Autorización de Folios). Un CAF es un archivo XML que contiene:

• el RUT del emisor y el tipo de documento que cubre,
• el rango autorizado, por ejemplo los folios 1001 a 2000,
• la fecha de autorización y la firma del propio SII sobre todo lo anterior,
• un par de llaves RSA. La llave privada es la que usas para timbrar cada documento.

De ahí salen algunas reglas:

• Un folio, un documento. Lleva registro de los folios que usas, idealmente en la misma transacción que guarda el documento, para que dos procesos no timbren el mismo.
• Un CAF, un tipo y un emisor. Timbrar una nota de crédito con el CAF de facturas falla con CAF_MISMATCH.
• Los CAF vencen. Los folios que quedan en un CAF vencido no se pueden usar; stampDte() lanza CAF_EXPIRED. Pide rangos acordes a tu volumen y solicita el siguiente CAF antes de quedarte sin folios.

import { readFile } from 'node:fs/promises'
import { parseCaf } from 'dte-sdk'
 
const caf = parseCaf(await readFile('./caf/33.xml', 'latin1'))
 
caf.type      // 33
caf.issuerRut // '76.123.456-0'
caf.range     // { from: 1001, to: 2000 }
caf.expiresAt // after this date, stampDte() throws CAF_EXPIRED

El TED y el código PDF417#

El TED (Timbre Electrónico DTE) es un pequeño bloque firmado dentro de cada DTE. Contiene un resumen de los campos clave (RUT del emisor y del receptor, tipo, folio, fecha, monto total y el primer ítem) junto con el CAF, y se firma con la llave privada del CAF. Como el CAF lleva la firma del SII, el TED demuestra que el folio fue autorizado, y el resumen amarra esa prueba a este documento en particular.

El TED también es la parte que se imprime. En la versión en papel o PDF aparece como un código de barras PDF417, para que el receptor o un fiscalizador lo escanee y verifique el documento sin conexión.

stampDte() produce ambos: ted (el bloque XML) y pdf417 (el contenido que le pasas a un generador de códigos de barra). dte-sdk no genera PDF ni códigos de barra por sí mismo.

El certificado digital#

El TED prueba el folio; la firma XML prueba quién emitió el documento. Cada DTE se firma con XMLDSig usando un certificado digital: un archivo .pfx o .p12 más su contraseña, emitido por un proveedor acreditado a una persona natural autorizada ante el SII para firmar en nombre de la empresa.

El mismo certificado te autentica ante los servicios web del SII. Para enviar documentos o consultar su estado, el cliente firma una semilla de un solo uso que entrega el SII y la canjea por un token de corta duración. sendToSii() y getStatus() se encargan de ese intercambio y guardan el token en caché por certificado.

Como el certificado pertenece a una persona, el RUT de su titular suele ser distinto del de la empresa. Ese es el senderRut que le pasas a sendToSii().

Certificación y producción#

El SII opera dos ambientes separados:

• Certificación es un ambiente de pruebas. Las empresas se convierten en emisores electrónicos completando ahí un proceso de certificación, que incluye emitir un set de pruebas definido por el SII. Los documentos enviados a certificación no tienen efecto tributario.
• Producción es el ambiente real. Cada documento aceptado ahí es un documento tributario válido.

Los dos no comparten nada: un CAF solicitado en certificación solo funciona en certificación, y los track ids de un ambiente no significan nada en el otro.

dte-sdk no tiene un environment por defecto: lo pasas explícitamente a sendToSii() y getStatus(), para que una prueba no llegue a producción por accidente.

Estados de aceptación del SII#

Enviar no es lo mismo que ser aceptado. sendToSii() responde apenas el SII recibe el envío, con un track id. Luego el SII revisa de forma asíncrona el esquema, las firmas, el TED y sus reglas de negocio, y getStatus() informa en qué va:

Un envío puede llevar varios documentos, así que el estado también trae un resultado por documento, con un reason cada vez que uno tiene reparos o fue rechazado.

Referencias: notas de crédito y débito#

Las notas de crédito (61) y de débito (56) no existen por sí solas: modifican un documento que ya existe, así que deben referenciarlo. createDte() exige al menos una referencia para estos tipos y lanza MISSING_FIELD si falta.

Una referencia identifica el documento original por tipo, folio y fecha, y su code indica qué hace la nota:

import { createDte } from 'dte-sdk'
 
// `invoice` is the type 33 document from the Quick Start.
const creditNote = createDte({
  type: 61,
  folio: 501,
  issuer: invoice.issuer,
  receiver: invoice.receiver,
  items: [{ name: 'Licencia anual', quantity: 1, unitPrice: 120000 }],
  references: [
    { type: 33, folio: 1024, date: '2026-10-28', code: 1, reason: 'Anula factura' },
  ],
})
 
creditNote.totals.total // 142800, the full amount of the voided invoice

La nota necesita su propio folio, de un CAF tipo 61. En certificación, los documentos emitidos para el set de pruebas del SII llevan además una referencia de tipo 'SET' que identifica el caso de prueba.

Glosario#

A dónde ir ahora#