dte-sdk

Ejemplos

Cuatro programas completos, cada uno construido solo con funciones que existen en la biblioteca y cada uno terminando en un documento que el SII puede recibir. Copia uno, cambia los RUT y las líneas, y ejecútalo contra el ambiente de certificación.

Estos programas corren sobre la 0.8.0 de dte-sdk desde npm, la versión más reciente (ver Instalación). Todavía no se recomienda para producción: la mayoría de las áreas no se ha probado contra el SII real, y hasta la 1.0.0 la API puede cambiar en cualquier versión.

Emitir una factura

Una tipo 33 con descuento y una línea exenta: certificado, CAF, registro de folios, sobre, envío, estado, y captura y archivo para tickets de soporte.

Emitir una nota de crédito

Una tipo 61 que referencia una factura para anularla (código 1), corregir un texto (código 2) o corregir montos (código 3), y una variante con nota de débito.

Emitir una boleta

Una tipo 39 con precios con IVA incluido y sin receptor, el EnvioBOLETA, el reporte de consumo de folios y la boleta exenta (41).

Obtener folios del SII

Pide un CAF al portal desde código: perfil, cupo, solicitud, almacenamiento seguro y un registro local de folios.

Antes de ejecutar cualquiera#

Los cuatro programas comparten la misma preparación.

  • Entorno. Node 22.12 o superior, en un proyecto de módulos ES ("type": "module" en package.json), porque los programas usan await de nivel superior. Ejecútalos con el ejecutor de TypeScript que ya uses, o compílalos antes: solo usan sintaxis de tipos que se puede borrar, así que las versiones recientes de Node también pueden ejecutar el archivo .ts directamente.
  • Tu certificado digital. Un .pfx como firma.pfx y su contraseña en la variable de entorno PFX_PASSWORD. Nunca escribas la contraseña en el código.
  • Un CAF por tipo de documento. caf-33.xml, caf-61.xml, caf-39.xml, etcétera, cada uno emitido para el RUT de tu empresa. Los archivos contienen una llave privada: son secretos. El último ejemplo muestra cómo obtenerlos.
  • La resolución. La fecha y el número de la resolución que autoriza a tu empresa, del ambiente que uses, en SII_RESOLUTION_DATE y SII_RESOLUTION_NUMBER (0 en certificación).
  • Datos ficticios. Los RUT, nombres y direcciones de los ejemplos son inventados: el emisor es 76543210-3, Comercial Andina SpA, y los receptores son 12345678-5 y similares. Reemplázalos por los tuyos.
VariableQué contiene
PFX_PASSWORDContraseña de firma.pfx
SII_RESOLUTION_DATEFecha de la resolución, AAAA-MM-DD
SII_RESOLUTION_NUMBERNúmero de la resolución; 0 en certificación
SII_ENVIRONMENTcertification o production; solo la lee el ejemplo de la boleta

Tres reglas que siguen todos los ejemplos#

Nunca reutilices un folio. Un folio autoriza un documento. Cada ejemplo reserva su folio en un registro local (createDirectoryFolioRegistry, de dte-sdk/node) antes de emitir, y lo registra como enviado cuando el envío devuelve un track id. Un folio reservado que nunca llegó al SII se vuelve a entregar.

Guarda el XML firmado antes de enviarlo. El XML firmado es el documento legal. Escríbelo primero en disco, luego envíalo, luego registra el track id. Si algo falla a la mitad, igual tienes el documento y sabes dónde quedó.

Discrimina por el código de error. Toda falla es un DteError con un code estable. Los mensajes son genéricos y nunca incluyen RUT ni montos, así que no los parsees: usa isDteError(error) y lee error.code y error.details.

TypeScript
import { isDteError } from 'dte-sdk'
 
try {
  // emitir, enviar…
} catch (error) {
  if (isDteError(error) && error.code === 'WAIT_TIMEOUT') {
    // el SII sigue trabajando: consulta más tarde con error.details.trackId
  }
}

El proceso del SII que los rodea#

Emitir documentos en producción es el último paso de un proceso en el SII. Antes, la empresa pasa por la certificación: emite los sets de pruebas del SII, envía sus libros, responde el intercambio y envía las muestras impresas. Los ejemplos de arriba usan el ambiente de certificación para que veas fluir los documentos, y el SDK tiene las piezas para correr también ese proceso:

  • Certificación: el proceso, paso a paso, y lo que el SDK automatiza.
  • Sets de pruebas: los sets de pruebas del SII, parseados y emitidos, con las notas y los códigos del ejemplo de la nota de crédito.
  • Corredor: una corrida reanudable sobre los portales de certificación, que obtiene sus folios con las funciones del ejemplo de folios.
  • Intercambio y muestras impresas: las respuestas del intercambio y los PDF que revisa el SII.
  • Certificación de boletas: la aplicación propia que autoriza las boletas, con el reporte de consumo de folios del ejemplo de la boleta.

Lo que ya se ha enfrentado al SII real, y lo que no, está en Estado.

← AnteriorBoletasSiguiente →Emitir una factura