API del núcleo (dte-sdk)

import { createDocument, stampDocument, signDocument, createSiiClient, DteError } from 'dte-sdk'

// Error tipado que lanza dte-sdk. El mensaje es genérico (código + claves seguras como el nombre
// del campo); el valor ofensivo, si lo hay, va en `details`, así ningún RUT ni texto libre llega a
// los logs.
class DteError extends Error {
  readonly code: DteErrorCode
  readonly details: DteErrorDetails
  constructor(code: DteErrorCode, details?: DteErrorDetails)
}
 
// Códigos de error estables que lanza dte-sdk. Discrimina por `error.code`, nunca por el texto del
// mensaje.
const DTE_ERROR_CODES: {
  readonly INVALID_RUT: "INVALID_RUT"
  readonly INVALID_DOCUMENT_TYPE: "INVALID_DOCUMENT_TYPE"
  readonly INVALID_FOLIO: "INVALID_FOLIO"
  readonly INVALID_DATE: "INVALID_DATE"
  readonly INVALID_AMOUNT: "INVALID_AMOUNT"
  readonly MISSING_FIELD: "MISSING_FIELD"
  // ... 40 miembros más
}
 
// El código de un valor lanzado cuando es un `DteError`, si no undefined. Para resultados que
// reportan fallas como datos.
function errorCode(error: unknown): DteErrorCode | undefined
 
// Guarda de tipo para `DteError`.
function isDteError(value: unknown): value is DteError

// `TipoDTE` — Códigos de tipo de documento del SII que soporta dte-sdk, por su nombre en inglés.
const DOCUMENT_TYPES: {
  readonly invoice: 33
  readonly exemptInvoice: 34
  readonly receipt: 39
  readonly exemptReceipt: 41
  readonly settlementInvoice: 43
  readonly purchaseInvoice: 46
  readonly dispatchGuide: 52
  readonly debitNote: 56
  readonly creditNote: 61
}
 
// Todos los códigos soportados, ascendentes.
const DOCUMENT_TYPE_VALUES: readonly DocumentType[] = [33, 34, 39, 41, 43, 46, 52, 56, 61]
 
// Guarda de tipo: true cuando `value` es uno de los códigos `TipoDTE` soportados.
function isDocumentType(value: unknown): value is DocumentType
 
// True para boletas (39, 41): no exigen receptor identificado, no llevan `TasaIVA`, van por REST.
function isReceipt(type: DocumentType): boolean
 
// True para los tipos exentos (34, 41): todas las líneas son exentas.
function isExemptType(type: DocumentType): boolean
 
// True para notas de débito y crédito (56, 61), que deben referenciar otro documento.
function isNote(type: DocumentType): boolean
 
// True cuando el tipo exige receptor identificado (todo menos boletas).
function requiresReceiver(type: DocumentType): boolean
 
// True cuando el impreso lleva copia cedible y recuadro de acuse de recibo Ley 19.983 (33, 34, 43,
// 46, 52).
function isTransferable(type: DocumentType): boolean
 
// Nombre oficial del tipo: `long` (por defecto), `short` (mayúsculas sin tildes) o `printed`
// (mayúsculas según el manual de muestras impresas del SII).
function documentTypeName(type: DocumentType, variant?: keyof NameVariants): string
 
// Ambientes del SII: `certification` (maullin, certificación) y `production` (palena, producción).
const ENVIRONMENTS: { readonly certification: "certification"; readonly production: "production" }
 
// Guarda de tipo para `Environment`.
function isEnvironment(value: unknown): value is Environment
 
// `CodRef` — Códigos de referencia de notas de crédito y débito: 1 anula, 2 corrige texto, 3
// corrige montos.
const REFERENCE_CODES: {
  readonly cancels: 1
  readonly correctsText: 2
  readonly correctsAmounts: 3
}
 
// `IndTraslado` — Tipo de traslado de la guía de despacho (1 venta, 2 ventas por efectuar, 3
// consignación, 4 entrega gratuita, 5 traslado interno, 6 otros no venta, 7 devolución, 8 traslado
// para exportación, 9 venta para exportación).
const TRANSFER_TYPES: {
  readonly sale: 1
  readonly pendingSale: 2
  readonly consignment: 3
  readonly freeDelivery: 4
  readonly internalTransfer: 5
  readonly otherNonSale: 6
  readonly return: 7
  readonly exportTransfer: 8
  readonly exportSale: 9
}
 
// `TipoDespacho` — 1 por cuenta del receptor, 2 por cuenta del emisor a instalaciones del
// receptor, 3 por cuenta del emisor a otras instalaciones.
const DISPATCH_TYPES: {
  readonly byReceiver: 1
  readonly byIssuerToReceiver: 2
  readonly byIssuerToOther: 3
}
 
// `IndServicio` — 1 servicios periódicos, 2 servicios periódicos domiciliarios, 3 ventas y
// servicios (el habitual), 4 espectáculos.
const SERVICE_INDICATORS: {
  readonly periodicServices: 1
  readonly periodicHomeServices: 2
  readonly salesAndServices: 3
  readonly shows: 4
}
 
// `FmaPago` — Forma de pago: 1 contado, 2 crédito, 3 sin costo (entrega gratuita).
const PAYMENT_TERMS: { readonly cash: 1; readonly credit: 2; readonly free: 3 }
 
// `IndExe` — 1 no afecto o exento, 2 no facturable, 3 garantía por depósito de envases, 4 no
// constituye venta, 5 ítem a rebajar, 6 no facturable negativo.
const EXEMPT_INDICATORS: {
  readonly exempt: 1
  readonly nonBillable: 2
  readonly containerDeposit: 3
  readonly notASale: 4
  readonly deduction: 5
  readonly nonBillableNegative: 6
}
 
// `TipoImp` — Códigos de impuesto de retención: 15 = IVA retenido total (factura de compra, tipo
// 46).
const WITHHOLDING_TAX_CODES: { readonly totalVatWithholding: 15 }
 
// `TasaIVA` — Tasa de IVA vigente, en porcentaje (19).
const VAT_RATE = 19
 
// RUT del SII, receptor de todo sobre: 60803000-K.
const SII_RUT = '60803000-K'
 
// RUT genérico de consumidor final para boletas sin comprador identificado: 66666666-6.
const FINAL_CONSUMER_RUT = '66666666-6'
 
// `IDK` — Valor que marca un CAF del ambiente de certificación (100).
const CERTIFICATION_KEY_ID = 100

// Convierte un `Document` de dominio a la estructura SII (etiquetas oficiales, orden del esquema).
// Es el único lugar que conoce los nombres de etiqueta; el XML siempre se renderiza desde su
// salida.
function toSiiDocument(doc: Document): SiiDocumento
 
// Convierte un documento en forma SII al modelo de dominio (para DTE recibidos e
// interoperabilidad). Los RUT se validan con rut.ts al entrar.
function fromSiiDocument(sii: SiiDocumento): Document

// Valida un RUT con rut.ts (módulo 11) y lo devuelve en forma SII. Acepta entrada con puntos, con
// guión o compacta.
function toSiiRut(value: string, field?: string): SiiRut
 
// Guarda de tipo: true cuando `value` ya es un RUT válido en forma SII.
function isSiiRut(value: unknown): value is SiiRut
 
// Separa un RUT SII en cuerpo y dígito verificador (lo que piden los campos `rutSender`/`dvSender`
// del SII).
function splitSiiRut(rut: SiiRut): { readonly body: string; readonly verifier: string; }

// Normaliza texto libre para un campo del DTE: quita apóstrofes y comillas dobles (rompen la
// validación de firma del SII), pasa guiones y puntos suspensivos tipográficos a ASCII, elimina
// todo lo que no es ISO-8859-1 (emoji, comillas curvas) y recorta espacios.
function sanitizeText(text: string | null | undefined): string
 
// Pliega texto a ASCII imprimible para el TED (`RSR`, `IT1`): quita diacríticos (á→a, ñ→n),
// expande ligaduras y letras especiales (ß→ss, Æ→AE, Þ→TH) y elimina lo que siga fuera de ASCII.
function foldToAscii(text: string | null | undefined): string
 
// Sanitiza y corta el texto a `maxLength`; con `preserveWords`, retrocede al último espacio si
// queda después del 70 % del límite.
function truncateText(
  text: string | null | undefined,
  maxLength: number,
  preserveWords?: boolean,
): string
 
// Lanza `FIELD_TOO_LONG` cuando el texto (ya sanitizado) supera el `xs:maxLength` del esquema del
// SII. El SII rechaza el sobre COMPLETO cuando un documento falla el schema, por eso se falla
// temprano en vez de truncar en silencio.
function assertMaxLength(value: string, maxLength: number, field: string): void
 
// Codifica texto como bytes ISO-8859-1 (lo que esperan los endpoints de subida del SII). Lanza en
// vez de truncar un code point mayor a U+00FF a su byte bajo, que es como llegaban caracteres de
// control corruptos al SII.
function encodeLatin1(text: string): Uint8Array
 
// Decodifica bytes ISO-8859-1 a string (un carácter por byte).
function decodeLatin1(bytes: Uint8Array): string

// La fecha de hoy en Chile como `AAAA-MM-DD` (formato de `FchEmis`/`FchResol` del SII).
function chileDate(now?: Date): string
 
// Marca de tiempo en hora de Chile `AAAA-MM-DDTHH:MM:SS` sin zona ni milisegundos (`TmstFirma`,
// `TmstFirmaEnv`, `TSTED`). Nunca se arma con `toISOString()`, que siempre es UTC y dejaba los
// sobres ~3 h en el futuro ("Error en Carátula").
function chileTimestamp(now?: Date): string
 
// Descompone un instante (por defecto: ahora) en componentes de hora de Chile con `Intl`, nunca
// con la zona del proceso.
function chileDateTimeParts(now?: Date): ChileDateTimeParts
 
// Normaliza `DD-MM-AAAA`, `DD/MM/AAAA` o `AAAA-MM-DD` (como muestran las fechas el portal y las
// resoluciones del SII) a ISO.
function toIsoDate(value: string, field?: string): string
 
// True cuando `value` es una fecha de calendario real en `AAAA-MM-DD`.
function isIsoDate(value: string): boolean

// Calcula el monto de una línea con redondeo por línea (el SII compara `MontoItem` contra `QtyItem
// × PrcItem`).
function calculateLineAmount(input: LineAmountInput): LineAmount
 
// Calcula `Totales` desde las líneas: neto, exento, IVA (derivado del bruto con
// `pricesIncludeVat`), no facturable, retención en facturas de compra y el total.
function calculateTotals(
  items: readonly Pick<LineItem, "amount" | "exemptIndicator">[],
  options: TotalsOptions,
): Totals

// Construye un `Document` normalizado desde la entrada: valida tipo, folio y fechas, normaliza RUT
// con rut.ts, sanitiza textos y exige los largos del esquema (falla temprano en vez de dejar que
// el SII rechace el sobre entero), numera líneas, calcula montos y totales, aplica los defaults de
// boleta (consumidor final, `IndServicio=3`) y fija `MntBruto=1` cuando los precios incluyen IVA.
function createDocument(input: DocumentInput, options?: CreateDocumentOptions): Document
 
// `xs:maxLength` del esquema del SII por elemento; `createDocument` los exige sobre el texto ya
// sanitizado.
const FIELD_LIMITS: {
  readonly RznSoc: 100
  readonly GiroEmis: 80
  readonly DirOrigen: 70
  readonly CmnaOrigen: 20
  readonly CiudadOrigen: 20
  readonly Sucursal: 20
  // ... 29 miembros más
}
 
// Renderiza el XML `<DTE>` sin firma: namespaces en el raíz (el digest los hereda), `ID` en el
// elemento firmado, secciones en el orden del esquema, el TED textual y un salto de línea entre
// secciones.
function buildDocumentXml(doc: Document, options?: BuildDocumentXmlOptions): string
 
// Nombre del elemento firmado: `Liquidacion` para liquidación factura (43), `Documento` para el
// resto.
function documentElementName(type: DocumentType): "Documento" | "Liquidacion"
 
// Firma un documento timbrado con el certificado del emisor (XMLDSig envuelta sobre
// `Documento`/`Liquidacion`). `TmstFirma` es la hora de Chile de `now`, o `signedAt` tal como se
// entrega.
function signDocument(
  doc: StampedDocument,
  certificate: Certificate,
  options?: { readonly now?: Date; readonly signedAt?: string; },
): SignedDocument
 
// Verifica la firma de un XML `<DTE>` (propio o recibido).
function verifyDocumentSignature(xml: string): SignatureVerification
 
// El flujo completo: crear (si hace falta) → timbrar con el CAF → firmar con el certificado.
function issueDocument(input: IssueDocumentInput): SignedDocument

// Serializa un objeto plano a XML compacto. Las claves son elementos en orden de inserción, las
// claves `@_nombre` son atributos, los arreglos repiten el elemento y los valores se escapan con
// entidades.
function buildXml(value: Readonly<Record<string, unknown>>): string
 
// Parsea XML a objeto plano (valores como string). Lanza `XML_PARSE_FAILED` si no está bien
// formado.
function parseXml(xml: string): ParsedXml
 
// Como `parseXml` pero quita los prefijos de namespace (`SII:RESPUESTA` → `RESPUESTA`), útil para
// respuestas SOAP.
function parseXmlWithoutNamespaces(xml: string): ParsedXml
 
// Texto de la primera ocurrencia de `<tag>…</tag>`, o `null`. Por regex, para respuestas planas
// del SII.
function extractTagContent(xml: string, tag: string): string | null
 
// Decodifica las cinco entidades XML (las respuestas SOAP suelen traer XML escapado).
function decodeXmlEntities(xml: string): string
 
// Escapa el valor de un nodo de texto con las cinco entidades XML (`& < > " '`).
function escapeXmlText(value: string): string
 
// Escapa el valor de un atributo entre comillas dobles.
function escapeXmlAttribute(value: string): string
 
// Quita los espacios de un base64 y lo corta en columnas de `width`.
function wrapBase64(value: string, width?: number): string
 
// Recorta `SignatureValue`, `Modulus` y `X509Certificate` a 64 columnas, la disposición que espera
// el SII.
function formatBase64Columns(xml: string): string

// SHA-1 en base64 de `data` codificado como `encoding` (por defecto UTF-8). Se usa en el
// `DigestValue` de XMLDSig.
function sha1Base64(data: string, encoding?: TextEncoding): string
 
// Firma SHA1withRSA (PKCS#1 v1.5) de `data`, en base64. Determinista: misma clave y bytes, misma
// firma.
function rsaSha1SignBase64(privateKeyPem: string, data: string, encoding?: TextEncoding): string
 
// Verifica una firma SHA1withRSA en base64 contra una clave pública dada como módulo/exponente.
// Nunca lanza: entrada malformada es `false`.
function rsaSha1VerifyBase64(
  publicKey: RsaPublicKeyParts,
  data: string,
  encoding: TextEncoding,
  signatureBase64: string,
): boolean
 
// Módulo y exponente públicos de una clave privada PEM (PKCS#1 o PKCS#8).
function rsaPublicKeyParts(privateKeyPem: string): RsaPublicKeyParts
 
// Módulo y exponente públicos de un certificado PEM.
function rsaPublicKeyPartsFromCertificatePem(certificatePem: string): RsaPublicKeyParts
 
// Parsea un certificado PEM a los campos que dte-sdk necesita.
function parseCertificatePem(certificatePem: string): ParsedCertificate
 
// Cuerpo base64 de un certificado PEM (sin cabeceras ni espacios).
function certificateBase64(certificatePem: string): string

// True cuando `now` pasó `notAfter` menos `marginDays`.
function isCertificateExpired(
  certificate: Pick<Certificate, "notAfter">,
  options?: { readonly now?: Date; readonly marginDays?: number; },
): boolean
 
// Días enteros hasta `notAfter` (negativo una vez vencido).
function daysUntilExpiry(
  certificate: Pick<Certificate, "notAfter">,
  options?: { readonly now?: Date; },
): number
 
// Construye un `Certificate` desde strings PEM (p. ej. tras `openssl pkcs12 -nodes`). Verifica que
// la llave corresponda al certificado y que esté vigente ahora: no vencido (`CERT_EXPIRED`) y no
// antes de su `notBefore` (`CERT_NOT_YET_VALID`, `details.validFrom`). `allowExpired` carga ambos.
function loadCertificateFromPem(
  input: PemCertificateInput,
  options?: LoadCertificateOptions,
): Certificate
 
// Carga un PKCS#12 (`.pfx`/`.p12`) como `Certificate`: archivos legacy (3DES/RC2) y modernos
// (PBES2/AES), bolsas de llave cifradas o planas, detección de la hoja por llave, cadena ordenada
// hoja → raíz, RUT desde el certificado. Igual que el cargador PEM, lanza `CERT_EXPIRED` pasado
// `notAfter` y `CERT_NOT_YET_VALID` antes de `notBefore`; `allowExpired` carga ambos.
function loadCertificateFromPkcs12(
  bytes: Uint8Array,
  password: string,
  options?: LoadCertificateOptions,
): Certificate

// Parsea un archivo CAF XML tal como se descarga del SII. Valida estructura, tipo, rango y llaves
// (la llave privada `RSASK` debe ser el par de la clave pública `RSAPK` que firmó el SII), y que el
// texto tenga un `<CAF` y un `</CAF`, para que el bloque `<CAF>` que se guarda para el TED sea el
// CAF del que se leen sus campos. Las referencias numéricas de carácter (`&#209;`, `&#xD1;`) de sus
// campos se decodifican como las decodifica un DOM. Lanza `CAF_INVALID`, también para llaves que
// no son par, un DOCTYPE u otro `<CAF` o `</CAF` en cualquier parte del texto, como en un
// comentario.
function parseCaf(xml: string): Caf
 
// Instante de vencimiento de un CAF: seis meses después de `authorizationDate` (Res. Ex. SII
// 58/2017) para facturas y notas (33, 46, 56, 61), a medianoche de Chile continental (UTC-4). Un
// día que el sexto mes no tiene es su último día: un CAF autorizado el 31-08-2026 vence el
// 28-02-2027, no en marzo. `null` para tipos que no vencen o sin fecha.
function cafExpiresAt(caf: Pick<Caf, "documentType" | "authorizationDate">): Date | null
 
// True si el CAF venció o vence dentro de `marginMs` (por defecto un día: el SII rechaza cada
// documento timbrado con un CAF vencido con `CAF-3-517`, y el sobre puede recibirse después de
// timbrado).
function isCafExpired(
  caf: Pick<Caf, "documentType" | "authorizationDate">,
  options?: { readonly now?: Date; readonly marginMs?: number; },
): boolean
 
// True cuando `folio` es un entero dentro del rango del CAF.
function isFolioInRange(caf: Pick<Caf, "range">, folio: number): boolean
 
// Lanza `FOLIO_OUT_OF_RANGE` salvo que `folio` esté dentro del rango del CAF.
function assertFolioInRange(caf: Pick<Caf, "range" | "documentType">, folio: number): void
 
// Cantidad de folios que autoriza el CAF.
function availableFolios(caf: Pick<Caf, "range">): number
 
// Firma SHA1withRSA (base64) de `data` con la llave privada del CAF sobre sus bytes ISO-8859-1, la
// codificación en que el TED se transmite e imprime.
function signWithCaf(caf: Pick<Caf, "privateKeyPem">, data: string): string
 
// Verifica una firma tipo TED con la clave pública del CAF (`RSAPK`).
function verifyWithCaf(caf: Pick<Caf, "publicKey">, data: string, signatureBase64: string): boolean
 
// Las llaves del SII que firman el `DA` de cada CAF, por `IDK`: 100 para el ambiente de
// certificación y 300 para producción. Cada una es la llave RSA de 512 bits de un certificado
// autofirmado del SII cuyo número de serie es el `IDK`, de CryptoSys y de LibreDTE, los mismos
// bytes en ambos.
const SII_CAF_KEYS: SiiCafKeys
 
// El ambiente de la llave del SII que nombra un CAF en su `IDK`: `certification` para 100,
// `production` para 300, null para otra.
function cafEnvironment(keyId: number): Environment | null
 
// Verifica la firma del SII sobre un CAF (`FRMA`, SHA1withRSA sobre el `DA`) con la llave del SII
// que nombra su `IDK`. Recibe un archivo CAF tal como lo emite el SII o el bloque `<CAF>` que trae
// un TED. `unchecked` si no se conoce llave para ese `IDK`; `invalid` para un CAF del otro ambiente
// que `environment` (producción por defecto), sea cual sea su firma, y para una `FRMA` vacía, sea
// cual sea su llave. Lanza `CAF_INVALID` si el texto no es XML, trae un DOCTYPE o no tiene un solo
// `CAF` con un `DA` y una `FRMA`.
function verifyCafSignature(cafXml: string, options?: CafSignatureOptions): VerificationStatus

// Timbra un documento con un CAF: verifica tipo, emisor, rango de folios y vencimiento, arma el
// `DD` exacto y lo firma con la llave del CAF (SHA1withRSA sobre bytes Latin-1).
function stampDocument(doc: Document, caf: Caf, options?: StampOptions): StampedDocument
 
// Verifica un XML `TED` contra la clave pública del CAF: true solo si los bytes del `<DD>`
// coinciden con la firma `FRMT`.
function verifyTed(tedXml: string, caf: Pick<Caf, "publicKey">): boolean
 
// El string `<DD>…</DD>` exacto que se firma y se imprime en el PDF417.
function buildDdString(fields: Omit<Ted, "signature" | "xml">): string
 
// Envuelve un `DD` y su firma en el elemento `TED`.
function buildTedXml(dd: string, signature: string): string
 
// Pliega el texto a ASCII y después lo corta a 40, como exigen `RSR` e `IT1` (el plegado puede
// alargar el texto).
function tedText(text: string): string

// Arma `SignedInfo`. `referenceId` es el `ID` del elemento firmado, o `''` para referenciar el
// documento completo (`URI=""`).
function buildSignedInfo(
  referenceId: string,
  digestValue: string,
  options?: { readonly expandTags?: boolean; readonly includeXsi?: boolean; },
): string
 
// Arma el elemento `Signature` a partir del `SignedInfo` guardado, la firma recortada y el
// material de clave.
function buildSignatureXml(
  signedInfo: string,
  signatureValue: string,
  keyInfo: { readonly modulus: string; readonly exponent: string; readonly certificate: string; },
): string
 
// Firma `elementTag` con una firma XMLDSig envuelta (C14N 1.0, RSA-SHA1) y devuelve el XML con la
// `Signature` insertada justo antes de `</rootTag>`.
function signEnveloped(
  input: SignEnvelopedInput,
): { readonly xml: string; readonly signature: XmlSignature; }
 
// Firma el elemento raíz completo con una firma XMLDSig envuelta (`Reference URI=""`, transformada
// enveloped-signature, C14N 1.0, RSA-SHA1) e inserta `Signature` justo antes del cierre del raíz.
function signRootElement(
  input: SignRootElementInput,
): { readonly xml: string; readonly signature: XmlSignature; }
 
// Verifica la firma envuelta que es hija directa de `rootTag`: ubica el elemento firmado por el
// `ID` que nombra `Reference/@URI` (ver `referencedElement`), recalcula su digest y comprueba
// `SignatureValue` con el `X509Certificate` que viene en `KeyInfo`. Solo pasa la firma que esto
// calcula: una `Reference`, con el único `DigestValue`, con SHA-1 y sin transformadas salvo
// enveloped-signature o C14N 1.0 (si no, `digestValid: false`), bajo C14N 1.0 y RSA-SHA1 (si no,
// `signatureValid: false`).
function verifyEnveloped(
  xml: string,
  target: { readonly elementTag: string; readonly rootTag: string; },
): SignatureVerification

// Agrupa documentos firmados bajo una carátula: valida el tipo de sobre, normaliza RUT y fecha de
// resolución, cuenta documentos por tipo (`SubTotDTE`, con 33/61/56 primero en `EnvioDTE`) y
// genera el id del set.
function createEnvelope(input: CreateEnvelopeInput): Envelope
 
// `PREFIJO_dd_mm_aaaa_hh_mm_ss_mmm` en hora de Chile.
function generateSetId(prefix: string, now?: Date): string
 
// Renderiza el sobre sin firma: prólogo ISO-8859-1, raíz con schemaLocation, `SetDTE` con
// `Caratula` y los documentos firmados uno por línea (conservan sus namespaces: los digests
// dependen de ellos).
function buildEnvelopeXml(envelope: Envelope): string
 
// Elemento raíz de cada tipo de sobre.
function envelopeRootName(kind: Envelope["kind"]): "EnvioDTE" | "EnvioBOLETA"
 
// Firma el `SetDTE` con el certificado de quien envía.
function signEnvelope(envelope: Envelope, certificate: Certificate): SignedEnvelope
 
// Verifica la firma del `SetDTE` de un XML `EnvioDTE`/`EnvioBOLETA`.
function verifyEnvelopeSignature(xml: string): SignatureVerification

// Verifica los documentos de un `DTE`, `EnvioDTE` o `EnvioBOLETA` tal como llega de un proveedor,
// y la firma del propio sobre. Cada documento se lee desde su elemento en la entrada parseada,
// nunca de un trozo del texto: su firma se chequea sobre formas escritas desde ese elemento, y sus
// campos y su timbre se leen de él. Se chequea: su firma XMLDSig; su TED, cuya `FRMT` debe
// verificar con la llave del CAF que trae el TED y cuyo `DD` debe coincidir con el encabezado; ese
// CAF contra el documento (el emisor, el tipo, el folio dentro del rango); y la firma del SII
// sobre el CAF (`FRMA`) con la llave del SII de su `IDK` (`SII_CAF_KEYS`, o `siiKeys`), solo para
// los CAF de `environment` (producción por defecto).
function verifyReceivedDocuments(
  xml: string,
  options?: VerifyReceivedDocumentsOptions,
): ReceivedDocumentsVerification

// `TipoOperacion` — Lado del libro de compras y ventas, con su valor en el SII.
const BOOK_OPERATIONS: { readonly sale: "VENTA"; readonly purchase: "COMPRA" }
 
// `TipoLibro` — Tipo de libro de compras y ventas, con su valor en el SII.
const BOOK_KINDS: {
  readonly monthly: "MENSUAL"
  readonly special: "ESPECIAL"
  readonly rectification: "RECTIFICA"
}
 
// `TipoEnvio` — Cómo llega un libro al SII: de una vez, por segmentos, el cierre de los segmentos
// o un ajuste posterior.
const BOOK_SUBMISSIONS: {
  readonly total: "TOTAL"
  readonly partial: "PARCIAL"
  readonly final: "FINAL"
  readonly adjustment: "AJUSTE"
}
 
// `TpoDoc` — Tipos de documento que admite el esquema del libro (`DoctoType` de
// `LibroCV_v10.xsd`), electrónicos o no.
const BOOK_DOCUMENT_TYPES: readonly [
  29, 30, 32, 33, 34, 35, 38, 39, 40, 41, 43, 45, 46, 48, 53, 55, 56, 60, 61, 101, 102, 103, 104,
  105, 106, 108, 109, 110, 111, 112, 175, 180, 185, 500, 501, 900, 901, 902, 903, 904, 905, 906,
  907, 909, 910, 911, 914, 918, 919, 920, 921, 922, 924
]
 
// Guarda de tipo para `BookDocumentType`.
function isBookDocumentType(value: unknown): value is BookDocumentType
 
// Tipos que el formato excluye del detalle: se informan en `summaryOnlyTotals` (boletas, ajustes
// de tipo de cambio, pasajes sin factura, otros registros no documentados).
const SUMMARY_ONLY_DOCUMENT_TYPES: readonly [35, 38, 39, 41, 48, 105, 500, 501, 919, 920, 922, 924]
 
// `CodIVANoRec` — Por qué no se puede recuperar el IVA de una compra.
const NON_RECOVERABLE_VAT_CODES: {
  readonly nonTaxableOperations: 1
  readonly lateRegistration: 2
  readonly rejectedExpenses: 3
  readonly freeDeliveries: 4
  readonly other: 9
}
 
// `TpoOper` — Operación de una línea del libro de guías. En el esquema `TpoOper` llega hasta 7,
// así que los valores 8 y 9 de `IndTraslado` no se pueden informar en una línea.
const GUIDE_TRANSFER_TYPES: {
  readonly sale: 1
  readonly pendingSale: 2
  readonly consignment: 3
  readonly demonstration: 4
  readonly internalTransfer: 5
  readonly otherTransfer: 6
  readonly returnGuide: 7
}
 
// `Anulado` — Por qué se marca una línea de guía: anulada antes de llegar al SII, anulada después
// o productos recibidos en parte.
const GUIDE_VOID_CODES: { readonly folio: 1; readonly guide: 2; readonly partialReceipt: 3 }

// El `EnvioLibro` de un libro de compras y ventas con las etiquetas oficiales, en el orden del
// esquema.
function toSiiPurchaseSalesBook(book: PurchaseSalesBook): SiiEnvioLibro
 
// El `EnvioLibro` de un libro de guías con las etiquetas oficiales, en el orden del esquema.
function toSiiGuideBook(book: GuideBook): SiiEnvioLibroGuia
 
// El `DocumentoConsumoFolios` de un reporte con las etiquetas oficiales, en el orden del esquema.
function toSiiFolioConsumption(report: FolioConsumption): SiiDocumentoConsumoFolios
 
// Suma resúmenes por tipo de documento y, dentro de cada tipo, suma IVA no recuperable y otros
// impuestos por código. Las filas conservan el orden en que aparecen por primera vez, y una fila
// presente en un solo lado se conserva.
function accumulateBookTotals(
  base: readonly BookTotals[],
  delta: readonly BookTotals[],
): readonly BookTotals[]

// Arma un libro de compras y ventas (IECV): valida la carátula y las zonas de su envío, normaliza
// las líneas y calcula los resúmenes.
function createPurchaseSalesBook(input: PurchaseSalesBookInput): PurchaseSalesBook
 
// Renderiza el XML `LibroCompraVenta` sin firma.
function buildPurchaseSalesBookXml(book: PurchaseSalesBook): string
 
// Firma el `EnvioLibro` con el certificado de quien envía (XMLDSig envuelta, `URI="#ID"`).
function signPurchaseSalesBook(
  book: PurchaseSalesBook,
  certificate: Certificate,
): SignedPurchaseSalesBook
 
// Verifica la firma de un XML `LibroCompraVenta`.
function verifyPurchaseSalesBookSignature(xml: string): SignatureVerification

// Arma un libro de guías: valida la carátula y las zonas de su envío, normaliza las líneas y
// calcula los resúmenes. `TasaImp` e `IVA` se emiten siempre, en 0 si faltan.
function createGuideBook(input: GuideBookInput): GuideBook
 
// Renderiza el XML `LibroGuia` sin firma.
function buildGuideBookXml(book: GuideBook): string
 
// Firma el `EnvioLibro` con el certificado de quien envía (XMLDSig envuelta, `URI="#ID"`).
function signGuideBook(book: GuideBook, certificate: Certificate): SignedGuideBook
 
// Verifica la firma de un XML `LibroGuia`.
function verifyGuideBookSignature(xml: string): SignatureVerification
 
// Suma dos resúmenes de libro de guías, los traslados por operación. Sirve para arrastrar los
// totales del período de envíos anteriores.
function accumulateGuideTotals(base: GuideTotals, delta: GuideTotals): GuideTotals

// Arma un reporte de consumo de folios (RCOF, hoy Resumen de Ventas Diarias): un resumen por cada
// tipo de boleta presente, primero el 39, o uno de tipo 39 en ceros para un día sin ventas.
function createFolioConsumption(input: FolioConsumptionInput): FolioConsumption
 
// Renderiza el XML `ConsumoFolios` sin firma.
function buildFolioConsumptionXml(report: FolioConsumption): string
 
// Firma el `DocumentoConsumoFolios` con el certificado de quien envía (XMLDSig envuelta,
// `URI="#ID"`).
function signFolioConsumption(
  report: FolioConsumption,
  certificate: Certificate,
): SignedFolioConsumption
 
// Verifica la firma de un XML `ConsumoFolios`.
function verifyFolioConsumptionSignature(xml: string): SignatureVerification
 
// Ordena folios y agrupa los consecutivos en rangos; un folio solo tiene `from` igual a `to`.
function compactFolioRanges(folios: readonly number[]): readonly FolioRange[]

// Deriva una línea del libro desde un documento. La contraparte es el receptor si el dueño del
// libro emitió el documento y el emisor en caso contrario, lo que cubre ventas, compras recibidas
// y facturas de compra (46) en cualquier lado.
function bookEntryFromDocument(
  document: Document,
  options: BookEntryFromDocumentOptions,
): BookEntryInput
 
// Deriva una línea del libro de guías desde una guía de despacho (52). El traslado es venta por
// defecto, y el receptor y los montos viajan solo en ventas; una guía no venta informa únicamente
// su total.
function guideEntryFromDocument(document: Document): GuideEntryInput
 
// Deriva una línea del reporte de consumo de folios desde una boleta (39 o 41).
function folioConsumptionEntryFromDocument(document: Document): FolioConsumptionEntry

// Hosts base de los web services DTE por ambiente: maullin (certificación) y palena (producción).
const SII_HOSTS: Readonly<Record<Environment, string>> = {
  certification: 'maullin.sii.cl',
  production: 'palena.sii.cl',
}
 
// Endpoints SOAP / CGI por ambiente (semilla, token, DTEUpload, estados).
const SOAP_ENDPOINTS: Readonly<Record<Environment, SoapEndpoints>>
 
// Endpoints REST de boletas por ambiente (apicert/pangal en certificación, api/rahue en
// producción).
const REST_ENDPOINTS: Readonly<Record<Environment, RestEndpoints>>
 
// URLs del servicio de Registro de Aceptación/Reclamo (WSRECLAMO v1.2); las llamadas SOAP se
// envían por POST aquí.
const CLAIM_WS_ENDPOINTS: Readonly<Record<Environment, string>>
 
// WSDL del web service de Registro de Aceptación/Reclamo.
const CLAIM_WSDL_ENDPOINTS: Readonly<Record<Environment, string>>
 
// User-Agent que espera el CGI de subida del SII (rechaza cadenas de navegador modernas).
const UPLOAD_USER_AGENT = 'Mozilla/4.0 ( compatible; PROG 1.0; Windows NT)'

// Logger por defecto: descarta todo.
const silentLogger: Logger

// Clave de caché `${ambiente}:${canal}:${huella}`: dos empresas, dos ambientes o dos canales nunca
// comparten token.
function tokenCacheKey(
  environment: Environment,
  channel: TokenChannel,
  certificate: Pick<Certificate, "certificateBase64">,
): string
 
// Caché de tokens en memoria (por proceso).
function createMemoryTokenCache(): TokenCache

// Valores por defecto medidos contra el SII: 6 intentos, 2 s creciendo ×1,8, tope 15 s, jitter ±20
// %.
const DEFAULT_RETRY_POLICY: RetryPolicy = {
  maxAttempts: 6,
  initialDelayMs: 2000,
  maxDelayMs: 15000,
  backoffMultiplier: 1.8,
  jitterRatio: 0.2,
}
 
// True para errores que conviene reintentar: fallas de transporte, timeouts, páginas ilegibles del
// SII, errores de consulta de `QueryEst*`, HTTP 429/405/5xx y el estado de subida "sistema
// bloqueado".
function isRetryableError(error: unknown): boolean

// Transporte por defecto sobre `globalThis.fetch` (Node ≥ 20, Deno, Bun) o un `fetch` inyectado.
// No sigue redirecciones: el SII nunca redirige una llamada bien formada y seguirla ocultaría una
// página de error.
function createFetchTransport(options?: { readonly fetch?: FetchLike; }): HttpTransport

// Tachado puro de un intercambio completo (URL, cabeceras, cuerpos y el motivo del error); el
// cliente lo aplica antes de llamar al puerto y los adaptadores pueden reutilizarlo.
function redactExchange(exchange: HttpExchange): HttpExchange
 
// Captura en memoria: `exchanges()` devuelve una copia de lo capturado hasta ahora.
function createMemoryCapture(): { readonly capture: HttpCapture; readonly exchanges: () => readonly HttpExchange[]; }

// Archivo en memoria: `records()` devuelve una copia de lo archivado hasta ahora.
function createMemoryUploadArchive(): { readonly archive: UploadArchive; readonly records: () => readonly UploadRecord[]; }

// Valida y completa las opciones en un `SiiClient` congelado. Los RUT pasan por rut.ts; los
// números deben ser positivos; el transporte por defecto es `fetch`, la caché por defecto en
// memoria, el logger por defecto silencioso.
function createSiiClient(options: SiiClientOptions): SiiClient

// Arma un sobre SOAP 1.1 (texto UTF-8) con una operación rpc y sus parámetros como hijos sin
// calificar.
function buildSoapEnvelope(input: SoapEnvelopeInput): string
 
// Interpreta una respuesta SOAP sin parseo XML completo: las respuestas del SII son planas y a
// veces traen entidades sueltas.
function parseSoapResponse(xml: string): SoapResponse
 
// Bytes `multipart/form-data`: los campos en orden y luego la parte archivo, como los espera el
// CGI de subida del SII.
function buildMultipartBody(input: MultipartBodyInput): Uint8Array

// Pide una semilla al SII por el canal indicado (SOAP `CrSeed` o REST
// `boleta.electronica.semilla`). La semilla es un string de 12 dígitos vigente dos minutos; nunca
// se cachea.
function getSeed(sii: SiiClient, channel: TokenChannel, overrides?: CallOverrides): Promise<string>
 
// Firma una semilla para `GetTokenFromSeed` / el endpoint REST de token: declaración XML, un salto
// de línea y luego `<getToken><item><Semilla>…</Semilla></item><Signature…/></getToken>` sin salto
// final (el endpoint REST es estricto con esta disposición).
function signSeed(
  seed: string,
  certificate: Pick<Certificate, "privateKeyPem" | "publicKey" | "certificateBase64">,
): string
 
// Devuelve un token vigente para el canal: el de la caché mientras no venza, si no semilla →
// semilla firmada → token, guardado en caché por `tokenTtlMs`. El token DTEWS y el token REST son
// cosas distintas.
function getToken(sii: SiiClient, channel: TokenChannel, overrides?: CallOverrides): Promise<string>
 
// Olvida el token en caché de un canal (la próxima operación vuelve a autenticarse).
function invalidateToken(sii: SiiClient, channel: TokenChannel): Promise<void>

// Sube un sobre firmado: `EnvioDTE` por `DTEUpload` (multipart ISO-8859-1), `EnvioBOLETA` por la
// API REST de boletas en producción o `DTEUpload` en certificación (`channel` lo fuerza).
function uploadEnvelope(
  sii: SiiClient,
  input: UploadEnvelopeInput,
  overrides?: CallOverrides,
): Promise<UploadReceipt>
 
// Sube un libro firmado por `DTEUpload`, como `LibroGuia.xml` si es un `LibroGuia` y como
// `LibroCV.xml` en otro caso, salvo que `fileName` diga otra cosa; el XML debe declarar
// ISO-8859-1, igual que en `uploadEnvelope` (si no, `INVALID_OPTION { field: 'xml' }`).
function uploadBook(
  sii: SiiClient,
  input: UploadXmlInput,
  overrides?: CallOverrides,
): Promise<UploadReceipt>
 
// Sube un Reporte de Consumo de Folios firmado (`ConsumoFolios`) por `DTEUpload` como
// `ConsumoFolios.xml`, salvo que `fileName` diga otra cosa; el XML debe declarar ISO-8859-1, igual
// que en `uploadEnvelope` (si no, `INVALID_OPTION { field: 'xml' }`).
function uploadFolioConsumption(
  sii: SiiClient,
  input: UploadXmlInput,
  overrides?: CallOverrides,
): Promise<UploadReceipt>

// Estado de un envío por TrackID: `QueryEstUp` por el canal `soap` (por defecto) o el estado de
// envío REST de boletas por `rest`.
function queryUploadStatus(
  sii: SiiClient,
  input: QueryUploadStatusInput,
  overrides?: CallOverrides,
): Promise<UploadStatus>
 
// Sondea `queryUploadStatus` cada `intervalMs` hasta que el estado deje de ser `pending`, hasta
// `timeoutMs`.
function waitForUploadStatus(
  sii: SiiClient,
  input: WaitForUploadStatusInput,
  overrides?: CallOverrides,
): Promise<UploadStatus>
 
// Estado de un documento: `QueryEstDte` (SOAP, por defecto en todos los tipos salvo boletas) o el
// endpoint REST por documento de boletas (por defecto en 39 y 41; la API REST responde unos diez
// minutos después del envío).
function queryDocumentStatus(
  sii: SiiClient,
  input: QueryDocumentStatusInput,
  overrides?: CallOverrides,
): Promise<DocumentStatus>
 
// Si el SII ya tiene un documento con este tipo y folio: `QueryEstDte` (siempre SOAP), consultando
// como la propia empresa (`RutConsultante`), con el receptor consumidor final, la fecha de hoy en
// Chile y monto 1, responde primero por existencia del folio.
function folioReceived(
  sii: SiiClient,
  input: FolioReceivedInput,
  overrides?: CallOverrides,
): Promise<boolean | null>