Get folios from the SII

Every document needs a folio, and a folio comes from a CAF (Código de Autorización de Folios): a file with a range of folios and the private key that signs the stamp of each document. You get it at the SII portal. This example does it from code with dte-sdk/portal: it logs in with your certificate, reads who you are for the SII, checks how many folios the SII would give you, requests a CAF, stores it safely, keeps track of the folios with a local registry and issues a document with the first one.

What you'll build#

A program, folios.ts, that:

• opens the portal as the holder of the certificate and reads the profile of the company: name, activity, address and the resolution of the environment,
• reads the folio quota of type 33, without stamping anything,
• requests a CAF of up to 50 folios, and reads how many it was really granted,
• saves the XML with restricted permissions, parses it, and reserves a folio in the local registry,
• issues an invoice with that folio, and closes the portal session.

Sending the invoice is the job of Issue an invoice.

Prerequisites#

• Node 22.12 or later, in an ES module project, with dte-sdk installed. The portal needs Node: fetch cannot present a client certificate. See Installation.
• Your certificate as firma.pfx, with its password in PFX_PASSWORD.
• The certificate must be enabled as a login method at sii.cl. This is a manual step at the SII, in Cambiar Clave y datos de autenticación, option "Utilizando Clave Tributaria o Certificado Digital". Until you do it, every login throws SII_PORTAL_CERT_NOT_ENABLED.
• A company enrolled as an electronic issuer in the environment you use, and the holder of the certificate with permission to request folios for it. Without them the SII refuses with the reasons in the table below.
• The RUTs and names in the example are fictitious: use your own company.

The full program#

import { mkdir, readFile, writeFile } from 'node:fs/promises'
import { isDteError, issueDocument, loadCertificateFromPkcs12, parseCaf } from 'dte-sdk'
import { createDirectoryFolioRegistry } from 'dte-sdk/node'
import {
  closePortalSession,
  createPortalClient,
  fetchIssuerProfile,
  portalRejectionMessage,
  queryFolioQuota,
  requestCaf,
  type PortalRejection,
} from 'dte-sdk/portal'
 
const COMPANY_RUT = '76543210-3'
const TYPE = 33
const WANTED = 50 // folios we would like
const LEAST = 10 // fewer than this is not worth a CAF: it would sit unused and lower the next quota
 
const certificate = loadCertificateFromPkcs12(await readFile('firma.pfx'), process.env.PFX_PASSWORD!)
const portal = createPortalClient({ environment: 'certification', certificate, companyRut: COMPANY_RUT })
const folios = createDirectoryFolioRegistry({ dir: './data/folios' })
 
try {
  // 1. Who we are for the SII in this environment
  const profile = await fetchIssuerProfile(portal)
  console.log(`issuer: ${profile.businessName}, resolution ${profile.resolutionNumber} of ${profile.resolutionDate}`)
 
  // 2. How many folios the SII would give us now. Nothing is stamped yet
  const quota = await queryFolioQuota(portal, { type: TYPE })
  if (quota.blocked) {
    console.log('The SII is not stamping this type now: issue with the folios you already have.')
  } else {
    console.log(
      quota.unrestricted
        ? 'quota: the SII is not rationing this type'
        : `quota: at most ${quota.maxAuthorized}, ${quota.availableFolios} stamped and unused`,
    )
 
    // 3. Ask for the CAF and read how many folios we really got
    const quantity = Math.min(WANTED, quota.maxAuthorized ?? WANTED)
    const obtained = await requestCaf(portal, { type: TYPE, quantity, minQuantity: LEAST })
    const { from, to } = obtained.caf.range
    console.log(`CAF obtained: folios ${from}-${to} (${obtained.granted} granted)`)
 
    // 4. The XML holds the private key of the CAF: a secret. Save it where only this service reads it
    const file = `./secrets/caf-${TYPE}-${from}-${to}.xml`
    await mkdir('./secrets', { recursive: true, mode: 0o700 })
    await writeFile(file, obtained.xml, { encoding: 'latin1', mode: 0o600 })
    console.log(`saved to ${file}`)
 
    // 5. From here on it is the file that counts, as in any later run
    const caf = parseCaf(await readFile(file, 'latin1'))
    const scope = { companyRut: COMPANY_RUT, type: TYPE, range: caf.range, environment: 'certification' } as const
    const folio = await folios.reserve(scope)
    console.log(`registry: folio ${folio} reserved, ${await folios.remaining(scope)} left`)
 
    // 6. Issue with it (sending it is the invoice example)
    const invoice = issueDocument({
      document: {
        type: TYPE,
        folio,
        issuer: {
          rut: profile.rut,
          businessName: profile.businessName,
          businessActivity: profile.businessActivity,
          activityCode: profile.activityCode ?? undefined,
          address: profile.address,
          commune: profile.commune,
          city: profile.city,
        },
        receiver: {
          rut: '12345678-5',
          businessName: 'Comercializadora Rapel Ltda',
          businessActivity: 'Comercio',
          address: 'Pasaje Los Olmos 88',
          commune: 'Providencia',
        },
        items: [{ name: 'Plan anual', quantity: 1, unitPrice: 100000 }],
      },
      caf,
      certificate,
    })
    console.log(`invoice issued: folio ${invoice.header.folio}`, JSON.stringify(invoice.header.totals))
  }
} catch (error) {
  if (!isDteError(error)) throw error
  if (error.code === 'SII_PORTAL_REJECTED') {
    // The SII said no, and the SDK says what it means and what to do
    const rejection = error.details.rejection as PortalRejection
    console.error(portalRejectionMessage(rejection))
    console.error('The portal said:', error.details.portalMessage)
  } else {
    console.error(error.code, error.details)
  }
  process.exitCode = 1
} finally {
  await closePortalSession(portal) // gives the session slot back to the SII
}

Walk-through#

Expected output#

On a successful run in certification, with a company that the SII does not ration and a fresh registry:

issuer: Comercial Andina SpA, resolution 0 of 2026-09-01
quota: the SII is not rationing this type
CAF obtained: folios 1-50 (50 granted)
saved to ./secrets/caf-33-1-50.xml
registry: folio 1 reserved, 49 left
invoice issued: folio 1 {"netAmount":100000,"vatRate":19,"vatAmount":19000,"totalAmount":119000}

The last line is computed by the SDK: 1 × 100000 net, VAT 19000, total 119000. Everything before it comes from the SII and is an example: the name, the resolution, the quota and the range will be yours. With rationing on, the quota line reads quota: at most 30, 0 stamped and unused, and the CAF has at most that many folios.

Pick the CAF of a later run#

A program that runs every day does not request a CAF each time: it picks one it already has. resolveCafFile, from dte-sdk/node, searches a directory (and its folders down to five levels) for the newest CAF file of the type and company that has not expired and still has required free folios in the registry. It returns the file with the scope to reserve from, or null when none has: that is the moment to call requestCaf.

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

The company is read from the file, never from the folder it lies in, so a CAF of another company in the same directory is not returned. The scope it gives includes the cafFingerprint of the file, and a scope without it is another entry of the registry: if you pick files this way, add cafFingerprint: cafFingerprint(obtained.xml) (from dte-sdk/portal) to the scope of step 5 of the program, so both use the same entry, or build that scope with cafFileScope(obtained, 'certification') from dte-sdk/node, the one resolveCafFile returns. Either matches the saved file because the program saves obtained.xml unchanged; a CAF rewritten before it is saved takes its scope from the text saved. findCafFiles lists every usable file, newest first, and findLatestCafFile gives the first one, with no registry. With includeExpired: true, findCafFiles also lists the expired files, marked expired, so you can say why one is not used; the other two never take one.

A registry kept with resolveCafFile before 0.7.0 may hold entries under an old fingerprint: a file saved with a UTF-8 byte order mark, or declared ISO-8859-1 with an Ñ or an accent, is read differently now, and its range would read as free. Move those entries to the new scope before issuing from such a file again, as CAF files explains.

Other ways to get folios#

requestCaf is the direct path. When the SII rations folios or the quantity does not fit, three flows from dte-sdk/portal cover the cases. They take the portal client of the program above and run inside one session.

import { createSiiClient, folioReceived } from 'dte-sdk'
import { requestCafExact, requestCafInBatches, reobtainFolios } from 'dte-sdk/portal'
 
const sii = createSiiClient({ environment: 'certification', certificate, companyRut: COMPANY_RUT })
 
// one CAF for the whole quantity, or nothing
const exact = await requestCafExact(portal, { type: 33, quantity: 50 })
 
// the same, but annulling unused folios if that lifts the limit (cannot be undone)
const forced = await requestCafExact(portal, {
  type: 33,
  quantity: 50,
  allowAnnul: true,
  exclude: [{ from: 1, to: 100 }], // a CAF still in use is never touched
  knownAnnulled: [], // what a previous run returned in knownAnnulled
})
 
// several CAFs when the SII rations by history
const batches = await requestCafInBatches(portal, { type: 33, quantity: 200, maxBatches: 4 })
 
// ranges the SII already authorized, without spending quota
const back = await reobtainFolios(portal, {
  type: 33,
  quantity: 20,
  isFolioFree: async (folio) => (await folioReceived(sii, { type: 33, folio })) === false, // tell the SII which folios are free
})
 
// a refusal is data here: the CAFs already obtained are not lost
for (const result of [exact, forced, batches, back]) {
  console.log(result.complete, result.cafs.length)
}
if (!exact.complete) console.log(exact.rejection, exact.portalMessage)
// a batch cut short by a failure, not by the SII, says so in failure
if (!batches.complete) console.log(batches.rejection ?? batches.failure)
// so do an exact request after its annulment and a re-obtaining; keep knownAnnulled either way
if (forced.failure !== null) console.log(forced.failure, forced.knownAnnulled)
if (back.failure !== null) console.log(back.failure, back.reason)

They return a result instead of throwing the SII's refusals, so the CAFs already obtained are not lost. requestCafExact and requestCafInBatches return complete, cafs (each with its secret xml), granted, rejection (a PortalRejection or null), portalMessage (what the portal said) and failure; save every CAF in cafs before you read rejection. reobtainFolios returns complete, cafs, ranges, expired, available, reason and failure, and a failure while listing the ranges reads as no ranges, with the failure in reason. It logs in on demand like the others. Session, block and transport failures stay errors, except once a flow holds something you must not lose: then requestCafInBatches ends with the CAFs, rejection: null and failure: { code, operation }, reobtainFolios with the CAFs it downloaded and failure, and requestCafExact, once the SII has answered its annulment, with knownAnnulled, rejection: null and failure, so read failure too. The original error goes to the client's logger, its texts redacted and without what a page said or its address. A failed requestCaf may have been granted all the same: check listReobtainableRanges before asking again.

Annulling cannot be undone. requestCafExact annuls only with allowAnnul: true, and the portal counts annulled folios against your quota for six months. exclude protects a CAF still in use, and knownAnnulled must be persisted, whether failure is set or not, and passed back from one run to the next, because the portal keeps listing annulled ranges forever. Do not turn allowAnnul on until you are sure the range is not in use.

What can go wrong#

An SII refusal is SII_PORTAL_REJECTED, with details.rejection (the reason) and details.portalMessage (what the portal said). portalRejectionMessage(rejection) gives the meaning and what to do, in Spanish, for the operator. The composite flows return the same reasons in rejection instead of throwing.

The other codes you can meet:

To get a trace for the SII or for an issue, give the portal client capture: createDirectoryCapture({ dir }) from dte-sdk/node: it writes every exchange with the secrets redacted.

Next steps#

• Issue an invoice to send the invoice you just issued.
• Portal for everything else the portal client does: annulment, the purchase and sales register and the MIPYME backup.
• Certification and its runner, which gets its folios through these same functions.
• Security for how to keep a CAF and a certificate.