API de Node (dte-sdk/node)

Los adaptadores que necesitan Node: el transporte node:https, que presenta certificados cliente y deja ajustar TLS, la captura HTTP, el archivo de envíos, la caché de tokens y sesiones y el registro de folios en disco, y la búsqueda de archivos CAF en disco, con el alcance de cada uno en el registro. Cargan módulos node: en el primer uso, nunca al importar. Cada adaptador se conecta a un puerto de la entrada raíz (transport, capture, archive, tokenCache) o del portal (sessionCache, el registro de folios); la búsqueda de archivos CAF es un conjunto de funciones que llamas tú.

import {
  createNodeHttpsTransport,
  createDirectoryCapture,
  createDirectoryUploadArchive,
  createDirectoryTokenCache,
  createDirectoryFolioRegistry,
  cafFileScope,
  findCafFiles,
  findLatestCafFile,
  resolveCafFile,
} from 'dte-sdk/node'

Un cliente armado con los adaptadores de Node:

import { createSiiClient } from 'dte-sdk'
import { createNodeHttpsTransport, createDirectoryCapture, createDirectoryUploadArchive } from 'dte-sdk/node'
 
const sii = createSiiClient({
  environment: 'certification',
  certificate,
  companyRut: '76543210-3',
  transport: createNodeHttpsTransport(),
  capture: createDirectoryCapture({ dir: './sii-capture' }),
  archive: createDirectoryUploadArchive({ dir: './sii-uploads' }),
})

El segundo parámetro de cada fábrica (load o loadModules) existe solo para que los tests del propio SDK reemplacen los módulos de Node; se omite de las firmas de abajo. Los archivos que escriben la captura y el archivo de envíos usan los modos por defecto de Node (se aplica el umask del proceso); no fijan permisos explícitos. Deja los directorios donde solo tu servicio pueda leerlos. La caché de tokens y el registro de folios son la excepción: fijan ellos mismos 0700 y 0600. Para el almacén del runner de certificación, que sí fija 0700 y 0600, ver dte-sdk/portal.

Transporte#

createNodeHttpsTransport devuelve un HttpTransport sobre node:https. La verificación del servidor está activada por defecto. Todos los demás campos TLS son salidas opt-in: tls.ca suma certificados de CA a las raíces públicas incluidas en Node y nunca las reemplaza (la solución correcta para un proxy corporativo o una CA privada), y tls.rejectUnauthorized: false desactiva la verificación, algo que no debes hacer contra el SII. tls.clientCertificate recibe el privateKeyPem y el chainPem de un Certificate, para TLS mutuo (el login al portal). Una petición que no se puede armar (una URL que no se interpreta, una cabecera que Node rechaza) falla con TRANSPORT_FAILED, como cualquier otra falla previa al intercambio. Si node:https no se puede cargar, la primera petición falla con TRANSPORT_UNAVAILABLE.

// Transporte sobre `node:https`, cargado en el primer uso (nunca al importar). Verifica el
// certificado del servidor por defecto; ver `NodeTlsOptions` para los ajustes opt-in.
// `loadModules` existe solo para tests.
function createNodeHttpsTransport(options?: NodeHttpsTransportOptions): HttpTransport

Campos de NodeTlsOptions

Campos de NodeHttpsTransportOptions

Captura#

createDirectoryCapture es un puerto HttpCapture que escribe un archivo JSON por intento HTTP y agrega una línea por intento a un índice. El cliente tacha cada intercambio antes de que llegue al puerto: tokens, semillas, cookies de sesión del portal, conversationId, RSASK y llaves privadas PEM pasan a [redacted], y los cuerpos se cortan a 512 KiB. Los RUT y el XML se conservan, porque el soporte del SII los necesita para diagnosticar un envío. Nunca lanza: una falla al escribir va a logger.warn.

// Escribe `<dir>/<prefijo><seq>-<operación>-<estado|ERR>.json` por intercambio y agrega una línea
// a `<dir>/index.jsonl`. Nunca lanza: las fallas van a `logger.warn`. `loadModules` existe solo
// para tests.
function createDirectoryCapture(options: DirectoryCaptureOptions): HttpCapture

Campos de DirectoryCaptureOptions

Lo que escribe bajo dir (se crea en el primer uso):

<dir>/
  index.jsonl
  <prefix>0001-<operation>-<status>.json
  <prefix>0002-<operation>-<status>.json

index.jsonl tiene una línea por intento. <operation> es el nombre de la operación (por ejemplo uploadEnvelope) y <status> es el estado HTTP, o ERR si no llegó respuesta. Cada línea de index.jsonl es un objeto JSON con seq, startedAt, operation, method, url, status (null si no hubo respuesta), durationMs y file. El número de secuencia lleva cuatro dígitos y cada instancia del adaptador lo mantiene en memoria, así que vuelve a 1 en un proceso nuevo: usa un dir nuevo, o un prefix, por corrida o por réplica si quieres mantener separados los archivos anteriores.

Archivo de envíos#

createDirectoryUploadArchive es un puerto UploadArchive. De cada envío que obtuvo respuesta del SII guarda los bytes exactos enviados y un registro del intercambio. Nunca lanza: una falla va a logger.warn.

// Escribe los bytes enviados como `<nombre>.xml` y el registro sin ellos como `<nombre>.json` bajo
// `<dir>/<ambiente>/<aaaa-mm>/` (`nombre` según `uploadRecordName`). Nunca lanza. `loadModules` es
// para tests.
function createDirectoryUploadArchive(options: DirectoryUploadArchiveOptions): UploadArchive

Campos de DirectoryUploadArchiveOptions

Lo que escribe:

<dir>/<environment>/<yyyy-mm>/<name>.xml
<dir>/<environment>/<yyyy-mm>/<name>.json

<environment> es certification o production, y <yyyy-mm> es el mes UTC del envío. <name> es <trackId>-<kind>; para una respuesta que informa un duplicado es <trackId>-<kind>-duplicate-<aaaammddHHMMSS>, así no reemplaza el registro del envío original; y para un envío sin TrackID es rejected-<aaaammddHHMMSS>-<kind>. <kind> es dte, receipt, book o folioConsumption. El registro .json tiene los campos de UploadRecord salvo xml, y su response.raw tiene los tokens y semillas tachados. El archivo .xml contiene los documentos que enviaste, con los datos de tus clientes.

Caché de tokens#

createDirectoryTokenCache es un TokenCache guardado en disco. Sirve como tokenCache del cliente del SII y como sessionCache del cliente del portal, así un reinicio reutiliza el token o la sesión del portal en vez de volver a loguearse, cosa que el SII raciona por RUT. Los procesos del mismo usuario comparten las entradas. Guarda un token (o, en el portal, las cookies de la sesión) y su expiración, en un archivo JSON por clave bajo dir. Los tokens y las sesiones del portal son credenciales: dale un directorio propio.

// Una caché de tokens en disco: un archivo JSON por clave bajo `dir`, escrito de forma atómica (un
// archivo temporal propio, creado en exclusiva, y renombre) y legible solo por el dueño. La entrada
// nombra su clave, así dos claves que comparten nombre de archivo nunca reciben el token de la otra.
// Solo se lee un archivo regular del usuario del proceso, y la lectura nunca espera por lo que no es
// un archivo. Nunca lanza: una falla al leer o escribir es un fallo de caché, reportado a `logger`
// con la operación y nunca con el token. `loadModules` existe solo para tests.
function createDirectoryTokenCache(options: DirectoryTokenCacheOptions): TokenCache

Campos de DirectoryTokenCacheOptions

import { createSiiClient } from 'dte-sdk'
import { createDirectoryTokenCache } from 'dte-sdk/node'
 
const sii = createSiiClient({
  environment: 'certification',
  certificate,
  companyRut: '76543210-3',
  tokenCache: createDirectoryTokenCache({ dir: './sii-tokens', logger: console }),
})

La misma llamada sirve al cliente del portal: createPortalClient({ …, sessionCache: createDirectoryTokenCache({ dir: './sii-sessions' }) }).

Lo que hace con los archivos bajo dir (se crea en el primer uso con modo 0700; un directorio que ya existe conserva sus permisos):

• Un archivo por clave. <clave>.json, con cada carácter de la clave que no sea letra, dígito, _ o - reemplazado por -. Cada archivo se crea con modo 0600 y además guarda la clave a la que pertenece: dos claves que dan el mismo nombre de archivo (a:b y a-b, o A y a en un sistema de archivos que no distingue mayúsculas) nunca reciben el token de la otra; la entrada de otra clave es un fallo de caché.
• Solo se leen tus propios archivos regulares. El archivo se abre sin bloquear y se lee por el mismo manejador que lo revisa, y se rechaza (fallo de caché) a menos que sea un archivo regular del usuario del proceso: un dispositivo, un directorio, una tubería o un archivo que otro usuario dejó en dir nunca se lee. En Windows, donde los archivos no tienen ese modo y no hay ids de usuario, deciden los permisos de dir y no se revisa el dueño.
• Una falla es un fallo de caché. Un archivo que no existe, uno que no es una entrada, una escritura que falla: get responde null y set y delete no hacen nada, y la falla va a logger.warn como token cache failed con la operation y el reason. El motivo nunca lleva el token ni un error de parseo, porque una entrada del portal guarda las cookies de la sesión.

Los procesos que usan una misma sesión del portal a la vez necesitan además un lock compartido: la caché comparte la sesión, no el turno para usarla. Ver dte-sdk/portal. El tipo TokenCache y la caché en memoria están en dte-sdk.

Registro de folios#

createDirectoryFolioRegistry devuelve un FolioRegistry (folios reservados, enviados y anulados) guardado en un archivo JSON, legible solo por el dueño. Es para un solo proceso. Conserva el directorio entre reinicios: si lo pierdes, se repiten folios ante el SII.

// Un registro en un archivo JSON, escrito de forma atómica (un archivo temporal propio, creado en
// exclusiva, y renombre), así un lector nunca ve medio libro, y legible solo por el dueño, como la
// caché de tokens, porque el libro guarda los RUT de las empresas, sus track ids y lo que quien
// llama guarda en `extra` (en Windows, donde los archivos no tienen ese modo, deciden los permisos
// de `dir`). Es para un solo proceso. `load` existe solo para tests.
function createDirectoryFolioRegistry(options: DirectoryFolioRegistryOptions): FolioRegistry

Campos de DirectoryFolioRegistryOptions

El registro es un solo archivo, <dir>/folios.json. El directorio se crea con modo 0700; uno que ya existe conserva sus permisos. Cada guardado escribe un archivo temporal propio a su lado (folios.json.<uuid>.tmp), creado en exclusiva con modo 0600, y lo renombra sobre folios.json, así un lector nunca ve medio libro y nunca se escribe a través de lo que ya esté en ese nombre, ni siquiera de un enlace simbólico. Si la escritura o el renombre fallan, el archivo temporal se borra. Un folios.json escrito antes de la 0.5.0, con los modos por defecto, queda solo para el dueño en su siguiente guardado. En Windows, donde los archivos no tienen ese modo, deciden los permisos de dir. Si node:fs no se puede cargar, las operaciones del registro fallan con TRANSPORT_UNAVAILABLE. El tipo FolioRegistry y el registro en memoria están en dte-sdk/portal.

Archivos CAF#

Un directorio con los archivos CAF que te entregó el SII, donde se busca el que se usará para emitir. Las tres funciones de búsqueda solo leen: reservar el folio le toca al registro, y pedir un CAF nuevo al SII cuando no se encuentra ninguno te toca a ti. cafFileScope no lee nada: da el alcance de un archivo en el registro. El XML del CAF contiene la clave privada del CAF, así que el directorio es un secreto (ver Seguridad).

// Todos los archivos CAF utilizables de un tipo y empresa bajo un directorio, del más nuevo al más
// viejo (por fecha de modificación, luego ruta). Utilizable quiere decir que se parsea como CAF, su
// `TD` es el tipo, su `RE` es la empresa (leído del archivo, nunca de dónde está) y no ha vencido,
// con el margen de un día de `isCafExpired`; con `includeExpired` vienen también los vencidos,
// marcados `expired`. Cada archivo se lee en la codificación que nombra su declaración XML:
// ISO-8859-1 como tal, UTF-8 o ninguna como UTF-8 estricto, así que un archivo cuyos bytes no son
// esa codificación, o que nombra otra, se salta en vez de leerse mal. Una carpeta o archivo que no
// se pueda leer se salta, y un directorio que no existe da una lista vacía.
function findCafFiles(options: FindCafFilesOptions): Promise<readonly CafFile[]>
 
// El archivo CAF utilizable más nuevo de un tipo y empresa bajo un directorio (ver `findCafFiles`),
// o null; nunca uno vencido, diga lo que diga `includeExpired`.
function findLatestCafFile(options: FindCafFilesOptions): Promise<CafFile | null>
 
// El archivo CAF utilizable más nuevo, nunca uno vencido, que todavía tiene `required` folios
// libres, o null si ninguno los tiene. Con un registro los folios libres son `registry.remaining`
// para el alcance del archivo (`cafFileScope`: empresa, tipo, rango, `environment` y la huella de su
// contenido), que vuelve como `scope`; sin registro, todo el rango. Solo lee.
function resolveCafFile(options: ResolveCafFileOptions): Promise<ResolvedCafFile | null>
 
// El alcance en el registro de un archivo CAF, para reservar y contar sus folios: la empresa (`RE`),
// el tipo (`TD`) y el rango (`RNG`) de su CAF, el ambiente indicado y la `cafFingerprint` de su
// texto, para que dos archivos de un mismo rango nunca compartan entrada. Es el alcance que devuelve
// `resolveCafFile`. Coincide con el archivo en disco solo si recibe el texto que guarda ese archivo.
function cafFileScope(file: Pick<CafFile, 'xml' | 'caf'>, environment: Environment): FolioScope

Campos de FindCafFilesOptions

Campos de CafFile

Campos de ResolveCafFileOptions

Los campos de FindCafFilesOptions más estos:

Campos de ResolvedCafFile

Los campos de CafFile más estos:

Lo que hace la búsqueda:

• Recorre dir y sus carpetas hasta cinco niveles más abajo, y mira solo los archivos .xml.
• Cada archivo se lee en la codificación que nombra su declaración XML. Uno que declara ISO-8859-1, como escribe el SII sus archivos CAF, se lee como tal, así que una Ñ o un acento en el nombre de la empresa llega intacto a RS y el bloque <CAF> conserva el texto que firmó el SII. Uno que declara UTF-8, o ninguna codificación, se lee como UTF-8 estricto. Un archivo cuyos bytes no son la codificación que nombra, o que nombra otra, se salta en vez de leerse mal, y una marca de orden de bytes UTF-8 se descarta. Antes de la 0.7.0 todo archivo se leía como UTF-8, y un CAF guardado tal como lo entregó el SII, con una Ñ o un acento, hacía fallar el chequeo del SII de cada timbre hecho con él.
• Un archivo cuenta solo si se parsea como CAF de ese type cuyo RE es issuerRut. La empresa se lee del archivo y nunca de la carpeta: una carpeta compartida puede tener archivos CAF de otras empresas, y un timbre firmado con uno hace que el SII rechace el sobre entero.
• Un CAF vencido, con el margen de un día de isCafExpired, se deja fuera. Con includeExpired: true, findCafFiles también lo lista, con expired: true, para que puedas decir por qué un archivo no se usa; findLatestCafFile y resolveCafFile nunca toman uno.
• Una carpeta o archivo que no se pueda leer se salta. Un dir que no existe da una lista vacía.
• El resultado va del más nuevo al más viejo por fecha de modificación, luego por ruta.

Un archivo sin declaración XML y con bytes ISO-8859-1 ya no se encuentra: declara su codificación, como lo hace el archivo del SII, o guárdalo como UTF-8.

cafFileScope es el alcance que arma resolveCafFile. Cualquier cosa con el texto de un CAF y el CAF parseado de él también tiene uno, como un ObtainedCaf del portal, pero es el alcance del archivo guardado solo si recibe el texto que guarda el archivo: una app que reescribe un CAF descargado antes de guardarlo, su declaración por ejemplo, toma el alcance del texto que guardó.

Cada función lanza un DteError ante una opción inválida, antes de leer nada:

import { createDirectoryFolioRegistry, resolveCafFile } from 'dte-sdk/node'
 
const registry = createDirectoryFolioRegistry({ dir: './folios' })
const file = await resolveCafFile({
  dir: './cafs',
  type: 33,
  issuerRut: '76543210-3',
  required: 1,
  registry,
  environment: 'production',
})
if (file === null) throw new Error('No CAF with free folios: request one')
const folio = await registry.reserve(file.scope!) // file.caf va a issueDocument