Documents

A document starts as plain data that you describe in readable English (issuer.businessName, items[0].unitPrice) and ends as the XML the SII expects. createDocument is the first step: it validates what you give it, normalizes RUTs and text, numbers the lines, computes the totals and returns a Document. issueDocument runs the whole pipeline (create, stamp, sign) in one call. buildDocumentXml and the codec (toSiiDocument, fromSiiDocument) turn the model into SII tags and back.

Everything on this page lives in the dte-sdk entry point and runs on Node, Bun and Deno.

Create a document#

import { createDocument } from 'dte-sdk'
 
const document = createDocument({
  type: 33,
  folio: 1,
  issuer: {
    rut: '76543210-3',
    businessName: 'Comercial Andina SpA',
    businessActivity: 'Software',
    address: 'Av. Los Aromos 1540',
    commune: 'Santiago',
    activityCode: 620200,
  },
  receiver: {
    rut: '12.345.678-5',
    businessName: 'Comercializadora Rapel Ltda',
    businessActivity: 'Comercio',
    address: 'Pasaje Los Olmos 88',
    commune: 'Providencia',
  },
  items: [
    { name: 'Plan anual', quantity: 1, unitPrice: 100000 },
    { name: 'Horas de consultoría', quantity: 3, unitPrice: 15000, discountPercent: 10 },
  ],
})
 
document.id // 'DTE_T33F1'
document.header.receiver.rut // '12345678-5'
document.items[1] // { lineNumber: 2, name: 'Horas de consultoría', quantity: 3, unitPrice: 15000, discountPercent: 10, discountAmount: 4500, amount: 40500 }
document.header.totals // { netAmount: 140500, vatRate: 19, vatAmount: 26695, totalAmount: 167195 }

createDocument is pure: the same input gives the same output, it never mutates its argument, and it touches no network, file or secret. The folio is not checked against a CAF here; that happens when you stamp the document (see Stamp).

Issue in one call#

issueDocument takes a DocumentInput (or a Document you already created), a parsed CAF and a certificate, and returns a signed document:

import { readFileSync } from 'node:fs'
import { issueDocument, loadCertificateFromPkcs12, parseCaf } from 'dte-sdk'
 
const certificate = loadCertificateFromPkcs12(readFileSync('firma.pfx'), process.env.PFX_PASSWORD!)
const caf = parseCaf(readFileSync('caf-33.xml', 'utf8'))
 
const signed = issueDocument({ document: input, caf, certificate })
 
signed.xml // signed <DTE> with its TED, no XML declaration
signed.ted // the electronic stamp
signed.signedAt // Chile time of the signature

The result is a SignedDocument: a Document plus ted, xml, signedAt and signature. The steps it runs are the ones documented on Stamp and Sign; call them separately when you need to stop in the middle (to inspect the TED, for example).

Document types#

The SDK supports nine TipoDTE codes. DOCUMENT_TYPES names them in English, DOCUMENT_TYPE_VALUES lists them in ascending order, and isDocumentType(value) is a type guard.

The columns are the answers of the helpers of the same name:

documentTypeName(type, variant) returns the official Spanish name. The variant is 'long' (the default, as in the table), 'short' (uppercase, no accents: NOTA CREDITO) or 'printed' (uppercase, as the SII printed-samples manual writes it: NOTA DE CRÉDITO ELECTRÓNICA).

The DocumentInput model#

DocumentInput is what you give to createDocument. Required fields are in bold in the first table; everything else is optional. Fields named after SII tags in the tables below are the tags the codec writes (TipoDTE, MntTotal…), so you can follow a field from your input to the XML.

Issuer#

The issuer is the company that issues the document (Emisor). The RUT may come in any shape (76.543.210-3, 76543210-3, 765432103); rut.ts validates it and the document keeps it as 76543210-3.

Receiver#

On a receipt (39, 41) you can leave receiver out. The document then carries the generic final consumer: RUT 66666666-6, name Consumidor Final, address Sin Direccion, commune Santiago. A receiver you do give on a receipt is kept as it is, with only what you wrote (its name stays required).

Items#

Each entry of items is a LineItemInput. The SDK numbers the lines from 1 (NroLinDet) and computes amount (MontoItem) unless you give it.

How the line amount is computed (rounding per line, discounts, surcharges) is on Totals.

An item is exempt when you set exempt: true, set an exemptIndicator, or when the document type itself is exempt (34 and 41 give every line IndExe=1 unless you set another indicator). The SDK does not check codes or additionalTaxCodes for length: they are written as you give them.

Prices with decimals need unitPriceDecimals, because the amount is always whole pesos but the SII reads PrcItem as written:

{ name: 'Tornillo', quantity: 3, unit: 'UN', unitPrice: 12.5, unitPriceDecimals: 2 }
// PrcItem is written as 12.50, MontoItem as 38 (round(3 × 12.5) = round(37.5))

Credit and debit notes with references#

references links the document to others. For credit and debit notes (61, 56) it is how you say which document you are cancelling or correcting.

import { createDocument, REFERENCE_CODES } from 'dte-sdk'
 
const creditNote = createDocument({
  type: 61,
  folio: 1,
  issuer,
  receiver,
  items: [{ name: 'Plan anual', quantity: 1, unitPrice: 100000 }],
  references: [
    {
      documentType: 33,
      folio: 1,
      date: '2026-11-01',
      code: REFERENCE_CODES.cancels,
      reason: 'Anula factura',
    },
  ],
})
 
creditNote.references
// [{ lineNumber: 1, documentType: 33, folio: '1', date: '2026-11-01', code: 1, reason: 'Anula factura' }]
creditNote.header.totals // { netAmount: 100000, vatRate: 19, vatAmount: 19000, totalAmount: 119000 }

A credit note that does not give the right to reduce the VAT debit sets options: { noDebitReduction: 1 } (IndNoRebaja).

References of a receipt#

Receipts have their own schema for Referencia: no date, no global flag and no other-issuer RUT, and CodRef is the company's own free text. That is why a receipt uses receiptReferences instead of references, and the two never mix: references on a receipt, or receiptReferences on any other type, throws INVALID_OPTION with details.field naming the field.

const receipt = createDocument({
  type: 39,
  folio: 5,
  issuer,
  items: [{ name: 'Café', unitPrice: 1500 }],
  pricesIncludeVat: true,
  receiptReferences: [{ code: 'SET', reason: 'CASO-1' }],
})
 
receipt.receiptReferences // [{ lineNumber: 1, code: 'SET', reason: 'CASO-1' }]

All four are optional, and empty texts are dropped.

Global discounts and surcharges#

globalAdjustments are discounts or surcharges over the whole document (DscRcgGlobal):

globalAdjustments: [
  { kind: 'discount', valueType: 'percent', value: 10, description: 'Descuento cliente' },
]

The totals take them into account; see Totals.

Subtotals#

subtotals is a list of SubtotalInfo (SubTotInfo) that the SDK writes as given, without computing anything: number (NroSTI), totalAmount (ValSubtotSTI) and, optionally, description (GlosaSTI), order (OrdenSTI), netAmount, vatAmount, additionalTaxAmount, exemptAmount and the lines (LineasDeta) they include.

Commissions (settlement invoice 43)#

A settlement invoice (43) is issued by an agent on behalf of a principal. Every line needs settledDocumentType, and commissions carries the commission and other-charge lines (Comisiones):

const settlement = createDocument({
  type: 43,
  folio: 1,
  issuer,
  receiver,
  items: [{ name: 'Venta liquidada', unitPrice: 10000, settledDocumentType: '33' }],
  commissions: [
    { kind: 'commission', description: 'Comisión 10%', rate: 10, netValue: 1000, vatValue: 190 },
  ],
})

calculateTotals does not derive the commission totals, own VAT (IVAProp) or third-party VAT (IVATerc) of a settlement invoice. Compute them yourself and pass them in totals (see Explicit totals). The signed element of a settlement invoice is Liquidacion, not Documento.

Transport (dispatch guide 52)#

A dispatch guide (52) says what moves, where and why. Two header options give the reason and who dispatches (options.transferType, options.dispatchType), and transport carries the vehicle, the carrier, the driver and the destination:

import { createDocument, DISPATCH_TYPES, TRANSFER_TYPES } from 'dte-sdk'
 
const guide = createDocument({
  type: 52,
  folio: 1,
  issuer,
  receiver,
  items: [{ name: 'Pallet', quantity: 4, unit: 'UN', unitPrice: 25000 }],
  options: {
    transferType: TRANSFER_TYPES.sale,
    dispatchType: DISPATCH_TYPES.byIssuerToReceiver,
  },
  transport: {
    licensePlate: 'ABCD12',
    carrierRut: '77654321-7',
    driver: { rut: '10000004-0', name: 'Juan Perez' },
    destinationAddress: 'Pasaje Los Olmos 88',
    destinationCommune: 'Providencia',
  },
})
 
guide.header.options // { transferType: 1, dispatchType: 2 }
guide.header.transport.driver // { rut: '10000004-0', name: 'Juan Perez' }
guide.header.totals // { netAmount: 100000, vatRate: 19, vatAmount: 19000, totalAmount: 119000 }

TRANSFER_TYPES (IndTraslado): sale 1, pendingSale 2, consignment 3, freeDelivery 4, internalTransfer 5, otherNonSale 6, return 7, exportTransfer 8, exportSale 9. DISPATCH_TYPES (TipoDespacho): byReceiver 1, byIssuerToReceiver 2, byIssuerToOther 3.

A guide for a transfer without a price can leave unitPrice out: its totals are { vatRate: 19, totalAmount: 0 }.

Header options#

options holds the optional IdDoc fields. Only the ones you set are written, in schema order. You never need most of them; the useful ones are paymentTerms, dueDate, payments, transferType and dispatchType.

import { createDocument, PAYMENT_TERMS } from 'dte-sdk'
 
createDocument({
  type: 33,
  folio: 3,
  issuer,
  receiver,
  items: [{ name: 'Plan anual', unitPrice: 100000 }],
  options: {
    paymentTerms: PAYMENT_TERMS.credit,
    dueDate: '2026-12-15',
    payments: [{ date: '2026-12-15', amount: 119000, note: 'Pago único' }],
  },
})

The SDK writes the options as you give them, without validating or measuring them. Dates in options are not normalized: write them as YYYY-MM-DD.

VAT-included prices#

When your prices already include VAT, say so with pricesIncludeVat: true. The SDK then derives net and VAT from the gross amount and, on every type but receipts, writes MntBruto=1 (options.grossAmounts). Receipts do not carry MntBruto, but the totals are derived the same way:

const receipt = createDocument({
  type: 39,
  folio: 1,
  issuer,
  items: [{ name: 'Café', quantity: 2, unitPrice: 1500 }],
  pricesIncludeVat: true,
})
 
receipt.header.receiver // { rut: '66666666-6', businessName: 'Consumidor Final', address: 'Sin Direccion', commune: 'Santiago' }
receipt.header.options // { serviceIndicator: 3 }
receipt.header.totals // { netAmount: 2521, vatAmount: 479, totalAmount: 3000 }

The SDK sets grossAmounts automatically only when the document has an affected amount: an exempt-only invoice with pricesIncludeVat gets no MntBruto.

Withholding (purchase invoice 46)#

A purchase invoice (46) is issued by the buyer, who withholds the VAT instead of paying it to the seller. The issuer is the buyer; the receiver is the seller. VAT is withheld in full by default:

const purchase = createDocument({
  type: 46,
  folio: 1,
  issuer,
  receiver: {
    rut: '77654321-7',
    businessName: 'Distribuidora Maipo Ltda',
    businessActivity: 'Reciclaje',
    address: 'Camino Lo Boza 410',
    commune: 'Pudahuel',
  },
  items: [{ name: 'Chatarra', quantity: 10, unitPrice: 1000 }],
})
 
purchase.header.totals
// {
//   netAmount: 10000,
//   vatRate: 19,
//   vatAmount: 1900,
//   withholdings: [{ taxCode: 15, rate: 19, amount: 1900 }],
//   totalAmount: 10000,
// }

totalAmount leaves out the withheld VAT. Pass withholdVat: false to issue a 46 without withholding, and withholdVat: true on a debit or credit note that affects a purchase invoice, so the note withholds the VAT the same way. On any other type withholdVat defaults to false.

Explicit totals#

totals replaces the computed totals with the object you give (a Totals). Use it when you need amounts the SDK does not derive (commission totals of a settlement invoice, IVAProp, IVATerc, MontoPeriodo, SaldoAnterior, VlrPagar) or a VAT rate other than 19. The SDK trusts it: it does not check the object against the lines. See Totals for the fields.

What validation does#

createDocument fails early instead of letting the SII reject the whole envelope later (the SII rejects an envelope when one of its documents fails the schema). Among other things, it:

1. Checks the type (INVALID_DOCUMENT_TYPE) and the folio, a positive integer (INVALID_FOLIO).
2. Takes the issue date as given or today in Chile, and requires it to be a real date (INVALID_DATE).
3. Normalizes every RUT with rut.ts (INVALID_RUT, with details.field such as issuer.rut or references[0].otherRut). The check digit is validated; the value is never copied into the error message.
4. Sanitizes free text: removes apostrophes and double quotes (they break the SII signature checks), turns typographic dashes and ellipsis into ASCII, drops everything outside ISO-8859-1 (emoji, curly quotes) and trims. "Premium" — grande becomes Premium - grande.
5. Enforces the schema lengths of the sanitized text (FIELD_TOO_LONG).
6. Requires what the type needs: the receiver (MISSING_FIELD, details.field: 'receiver'), its address and commune on every type but receipts, at least one item, an item name, the issuer business name, activity, address and commune, and settledDocumentType on every line of a 43.
7. Rejects non-finite numbers in amounts (INVALID_AMOUNT) and a unitPriceDecimals outside 0 to 6 (INVALID_OPTION).
8. Numbers items, references, adjustments and commissions from 1.
9. Computes line amounts and totals (see Totals), applies the receipt defaults and sets MntBruto.

import { createDocument, isDteError } from 'dte-sdk'
 
try {
  createDocument({ ...input, items: [{ name: 'x'.repeat(81), unitPrice: 1 }] })
} catch (error) {
  if (isDteError(error) && error.code === 'FIELD_TOO_LONG') {
    error.message // 'Field exceeds the maximum length allowed by the SII schema (field=NmbItem, maxLength=80, length=81)'
    error.details // { field: 'NmbItem', maxLength: 80, length: 81, value: 'xxxxxxxx…' }
  }
}

Messages never include RUTs, names or item text; the offending value lives in details. If you log details, keep in mind that it can hold personal data. See Errors.

Field limits#

FIELD_LIMITS is the table of xs:maxLength values that createDocument enforces, keyed by SII tag:

FIELD_LIMITS also lists CorreoRecep (80) and GlosaSTI (40), but createDocument does not check the receiver email or the subtotal description today. Fields that are not free text (phone, email, activityCode, codes, options, subtotals) are written as you give them.

Issue date and the clock#

issueDate accepts YYYY-MM-DD, DD-MM-YYYY and DD/MM/YYYY (the way the SII portal and resolutions show dates) and is stored as YYYY-MM-DD. When you omit it, the SDK uses today's date in Chile (America/Santiago, with daylight saving), never the time zone of the process. That matters on a server in UTC: at 23:30 in Chile on 15 November the UTC date is already the 16th.

Every function that depends on the time takes the clock as an option, so tests are deterministic:

const document = createDocument(input, { now: new Date('2026-11-15T18:30:00Z') })
document.header.issueDate // '2026-11-15'

issueDocument takes the same now and passes it to the stamp and the signature, so one now fixes FchEmis, TSTED and TmstFirma together. timestamp overrides the stamp and signature times with a string you choose (YYYY-MM-DDTHH:MM:SS).

Render the XML#

buildDocumentXml(document, options?) renders the unsigned <DTE> XML:

import { buildDocumentXml, documentElementName } from 'dte-sdk'
 
const xml = buildDocumentXml(document)
documentElementName(33) // 'Documento'
documentElementName(43) // 'Liquidacion'

What it does:

• Declares the namespaces on the DTE root (http://www.sii.cl/SiiDte and xsi), so the signature digest inherits them.
• Puts the ID attribute (DTE_T33F1) on the signed element: Documento, or Liquidacion for a settlement invoice (43). documentElementName(type) returns that name.
• Writes the sections in schema order (Encabezado, Detalle, SubTotInfo, DscRcgGlobal, Referencia, Comisiones, TED) and leaves out the empty ones.
• Puts a line break after each of those sections. The SII rejects any line longer than about 4,090 characters (CHR-00002), so a receipt with many lines would fail otherwise. The breaks sit inside the signed element and the digest covers them.
• Escapes text values as XML entities.

You rarely call it yourself: signDocument calls it for you. It is useful to look at what would be signed, or to archive a draft.

The codec: SII tags and the English model#

The English model and the SII tags are two shapes of the same data. toSiiDocument maps a Document to the structure with the official tags in schema order (SiiDocumento: Encabezado.IdDoc.TipoDTE, Totales.MntTotal…), and fromSiiDocument maps it back:

import { fromSiiDocument, toSiiDocument } from 'dte-sdk'
 
const sii = toSiiDocument(document)
sii.Encabezado.Totales.MntTotal // 167195
sii.Detalle[0].NmbItem // 'Plan anual'
 
fromSiiDocument(sii) // a Document again

toSiiDocument is the only place that knows the tag names; buildDocumentXml always renders from its output. fromSiiDocument is for DTE you receive and for interoperability: it validates every RUT with rut.ts on the way in (INVALID_RUT). A receipt maps its references to and from receiptReferences. One thing does not survive the round trip: unitPriceDecimals, because a written 12.50 reads back as the number 12.5.

Next steps#

• Totals: how line amounts, VAT, exempt lines and withholding are computed.
• Stamp: put the TED on the document with a CAF.
• Sign: load the certificate and sign.
• Examples: invoice, credit note and receipt.