Purchase and sales register

The RCV (Registro de Compras y Ventas) is the SII's own record of what you bought and sold. dte-sdk/portal reads it on the same certificate session as the rest of the portal, changes how a purchase is classified, and downloads the XML of your issued or received documents from the MIPYME backup. It also holds, as data, what the register does with each of its document codes. This page covers what each function reads, which SII service it calls, and the traps: a refused month that reads as empty, writes that change the real register, and a known defect in the backup.

Basic usage#

You need a portal client first: see SII portal and folios.

import {
  changePurchaseType,
  downloadMipymeBackup,
  fetchPurchaseDocument,
  fetchRegisterSummary,
  listPeriodDocuments,
  listPurchaseTypes,
  moveVatToCommonUse,
} from 'dte-sdk/portal'
 
// Every document of October 2026 that the company received, one row each
const { summary, documents } = await listPeriodDocuments(portal, { period: '2026-10', direction: 'received' })
 
// The official totals of the purchases book, per document type
const { rows, header } = await fetchRegisterSummary(portal, { period: '2026-10', operation: 'purchase' })
 
// How a purchase is classified, and changing it
const types = await listPurchaseTypes(portal)
const key = { type: 33, folio: 1234, period: '2026-10', counterpartyRut: '12345678-5' }
const purchase = await fetchPurchaseDocument(portal, key) // null when the SII has no data for that key
await changePurchaseType(portal, { ...key, purchaseType: '4' }) // an id from listPurchaseTypes
 
// The full XML of the documents, in pieces of at most 20
await downloadMipymeBackup(portal, {
  from: '2026-10-01',
  to: '2026-10-31',
  direction: 'received',
  onChunk: async ({ from, to, xml }) => saveBackup(`${from}_${to}.xml`, xml),
})

saveBackup is yours. The backup holds your real documents: store them with the care you give any tax record.

What do I need?#

The register has three services behind it, plus the backup. Each function reads one of them:

The register host depends on the client's environment (www4c.sii.cl for certification, www4.sii.cl for production). The backup does not: see The MIPYME backup.

All of these functions take the same last, optional overrides argument as the rest of the portal ({ signal, timeoutMs, retry }), and the optional companyRut that replaces the client's.

Read the register#

Documents of a period#

const { summary, documents } = await listPeriodDocuments(portal, {
  period: '2026-10', // YYYY-MM
  direction: 'issued', // the default; or 'received'
})
 
summary[0].type // 33
summary[0].documentCount
documents[0].folio
documents[0].totalAmount

It asks for the summary per document type, then makes one detail call per row, at the same time. It returns:

• summary: one PeriodSummaryRow per document type and section: type, typeDescription, section, documentCount, exemptAmount, netAmount, vatAmount, totalAmount. The section is S1 sales, S2 purchase invoices, S3 settlements, S4 exports or S5 dispatch guides.
• documents: every document of the summary's types, as a PeriodDocument: type, typeDescription, folio, issueDate, receivedDate, counterpartyRut, counterpartyName, the four amounts, eventOrder (the last event: 2 acknowledged, 3 accepted, 4 claimed) and eventDescription.

This is not the official register. It lists what the SII holds per document, with no time of day and no XML, and it leaves out what the SII aggregates (receipts, for one). counterpartyRut is the other party, not validated: in received documents it holds the issuer.

The official totals#

const { rows, header } = await fetchRegisterSummary(portal, {
  period: '2026-10',
  operation: 'purchase', // or 'sale'
  accountingStatus: 'registered', // the default; 'pending', 'notIncluded' or 'claimed'
})
 
rows[0].type
rows[0].documentCount
rows[0].commonUseVat
rows[0].nonRecoverableVat
header?.updatedAt
header?.proportionalityFactor

These are the official totals of the period by document type and accounting status, including what the SII aggregates, such as receipts. rows are RegisterSummaryRow: type, typeName, documentCount, exemptAmount, netAmount, vatAmount, commonUseVat, nonRecoverableVat, totalAmount. header is null or has updatedAt (when the register last changed), proportionalityFactor and raw (the header as the SII sent it). The factor is a number from 0 to 1. The SII reportedly sends it as a text with spaces and a decimal comma (" 1,0000", "0,8532"), and that form is read too. A value outside 0 to 1 is not a factor: proportionalityFactor is null and the value stays in raw.

Document codes and accounting statuses#

Each row of the official totals carries a document type. What the register does with each one is data in the package, since 0.2.0: registerDocumentCode(code) gives one of the register's 49 document codes, or undefined, and REGISTER_DOCUMENT_CODES lists them all. Nothing here calls the SII.

import { REGISTER_ACCOUNTING_STATUSES, fetchRegisterSummary, registerDocumentCode } from 'dte-sdk/portal'
 
const creditNote = registerDocumentCode(61)
creditNote?.name // 'Nota de Crédito Electrónica'
creditNote?.operations // ['purchase', 'sale']
creditNote?.sign // -1: it subtracts from the totals
registerDocumentCode(71) // undefined: not a code of the register
 
const { rows } = await fetchRegisterSummary(portal, { period: '2026-10', operation: 'purchase' })
for (const row of rows) {
  const code = row.type === null ? undefined : registerDocumentCode(row.type)
  if (code?.sign === -1) {
    // A credit note or a decrease: it subtracts from the period's totals
  }
}
 
// Every accounting status the purchases side can hold; sales hold only 'registered'
for (const accountingStatus of REGISTER_ACCOUNTING_STATUSES.purchase) {
  await fetchRegisterSummary(portal, { period: '2026-10', operation: 'purchase', accountingStatus })
}

Each entry says which sides of the register show the code (operations), whether it is a DTE (electronic), whether it reaches the register at all (inRegister, false for the dispatch guides 50 and 52), its sign in the totals (-1 for credit notes and decreases), whether the register lists it document by document (perDocument, false for receipts and the other codes it holds only as a monthly summary line) and whether the buyer withholds the VAT (buyerWithholdsVat: 29, 45 and 46). REGISTER_ACCOUNTING_STATUSES gives all four statuses for purchases and only registered for sales, since no SII source describes other states of a sale.

Where the SII states a value, the catalog follows it. The few it does not state are inferred, and the JSDoc of each says so: that the dispatch guides stay outside the register, the sign of each code (the F29's: credit notes subtract), and that 906 is summary only. The amounts of codes 40, 43 and 103 may arrive negative and carry their own sign. The catalog has not been checked against a real register with documents in it yet. The API reference groups the 49 codes by what the catalog says of them.

Purchases: types and detail#

const types = await listPurchaseTypes(portal)
// [{ id, description, interchangeable }, ...]: the types of purchase the SII lets a document have
 
const purchase = await fetchPurchaseDocument(portal, {
  type: 33,
  folio: 1234,
  period: '2026-10',
  counterpartyRut: '12345678-5', // the RUT of the issuer
})
purchase?.purchaseType // the current type of purchase

listPurchaseTypes is measured against the real SII. Its interchangeable flag says that the SII's own client offers moving VAT between recoverable and common use for that type. It does not mean the type can be changed.

fetchPurchaseDocument returns the document as the register holds it, including its current purchaseType, commonUseVat and nonRecoverableVat, or null when the SII has no data for that key. The key is type, folio, period (YYYY-MM) and counterpartyRut, the issuer of the purchase.

Traps when reading#

• A refused month reads as empty. The SDK does not look at the response codes of these services. So listPeriodDocuments and fetchRegisterSummary cannot tell a month the SII refuses to show from a month with no movement: both come back with no rows. Do not treat an empty answer as proof that nothing happened.
• raw holds each row exactly as the SII sent it. The field names of the typed fields come from the SII's own client code and have not been seen with real documents. If one is absent or unreadable, the typed field is null, and whatever the SII sent is still in raw. Read raw when a null surprises you.
• Numbers may be null. Every amount can be null. Do not do arithmetic on an amount without checking it.
• No retries by default. A read makes one attempt per call. Pass { retry: { ... } } as the overrides to repeat each call. A read that meets an expired session or a page it cannot read starts over once with a fresh session.

listPeriodDocuments and fetchRegisterSummary throw INVALID_DATE for a period that is not YYYY-MM, INVALID_OPTION for an unknown direction, operation or accountingStatus, MISSING_FIELD without a company, INVALID_RUT, and SII_PORTAL_UNEXPECTED_PAGE for an answer that is not JSON.

Change the register#

Three functions change how a purchase is recorded.

import { changePurchaseType, fetchPurchaseDocument, moveVatToCommonUse, moveVatToRecoverable } from 'dte-sdk/portal'
 
const key = { type: 33, folio: 1234, period: '2026-10', counterpartyRut: '12345678-5' }
 
// Change the type of purchase: an id from listPurchaseTypes
await changePurchaseType(portal, { ...key, purchaseType: '4' })
 
// Move VAT from recoverable to common use: pass the FINAL amount of each bucket
await moveVatToCommonUse(portal, { ...key, commonUseVat: 19000 })
 
// The inverse
await moveVatToRecoverable(portal, { ...key, commonUseVat: 0, recoverableVat: 19000 })

• One attempt, and only the SII's OK confirms. Each write is a single attempt: the SDK cannot tell whether a lost answer means the change was applied, so it never repeats it, and overrides.retry does not reach a write. Anything other than the SII's OK throws SII_PORTAL_REJECTED with details.rejection equal to purchaseChangeNotConfirmed, and details.portalMessage when the SII said something.
• After purchaseChangeNotConfirmed, read before you retry. The change may have applied. Call fetchPurchaseDocument and compare purchaseType or the VAT amounts with what you wanted. Only retry if it did not change.
• VAT amounts are final amounts, not deltas. commonUseVat and recoverableVat are the value of each bucket after the change. To move a document's whole VAT to common use, pass the total as commonUseVat and leave recoverableVat out. To move it all back, pass commonUseVat: 0 and the total as recoverableVat. An amount you leave out goes empty.
• A write throws INVALID_DATE, MISSING_FIELD or INVALID_RUT for a bad key, and SII_PORTAL_UNEXPECTED_PAGE for an answer it cannot read.

The MIPYME backup#

The SII keeps a backup of the XML of the documents a company issued and received, in its MIPYME service. downloadMipymeBackup lists a date range, splits it, downloads each piece and gives you the XML. Use it when you need the full document, which the register does not hold.

import { downloadMipymeBackup } from 'dte-sdk/portal'
 
const backup = await downloadMipymeBackup(portal, {
  from: '2026-10-01', // YYYY-MM-DD
  to: '2026-10-31',
  direction: 'issued', // the default; or 'received'
  type: 33, // optional: only this document type
  attempts: 3, // tries per listing and per download; 3 by default
  onChunk: async ({ from, to, total, xml }) => {
    await saveBackup(`${from}_${to}.xml`, xml)
  },
})
 
backup.total // documents counted
backup.chunks // [{ from, to, total, type? }], newest first

The result is a MipymeBackup: total is the sum of the pieces' totals (the documents the listings counted), and chunks are the pieces, newest first. Each MipymeBackupChunk has from, to, total, type (only when a day had to be split by document type) and xml. With onChunk, the xml is absent from chunks, so a long history does not stay in memory. Use onChunk for long histories.

How the range is split#

The SII allows at most 20 documents per download: 20 answer XML, 21 answer an error page. So the SDK plans first and downloads after.

1. It asks the SII how many documents the whole range holds. Up to 20, it is one piece.
2. Above 20, it splits the range in halves, by day, and plans each half the same way.
3. When a stretch cannot be split by day any more and still holds more than 20, it splits that day by document type, asking for the count of each type in a fixed list of types.

The whole plan comes first. If a day cannot be downloaded, the call throws before any download, so you never get half a backup without knowing it:

• backupDayOverLimit: one day and one document type exceed 20 documents. It cannot be split further. details has the day, the type and the number listed.
• backupDayUnknownTypes: one day exceeds 20 documents and has documents of types the SDK cannot separate, so the day cannot be covered. details has the day, the number listed and the number covered.

Both are SII_PORTAL_REJECTED, with the key in details.rejection.

What the backup reads#

• It reads production from any client. The service exists only in production, so downloadMipymeBackup reads real documents even from a client created with environment: 'certification'. If a development or test environment stores what it downloads, that environment needs its own gate: the SDK will not stop it.
• It needs only the certificate. It does not require the company to be enrolled as an issuer.

Refusals#

The backup answers with pages, and the SDK reads them into SII_PORTAL_REJECTED refusals:

backupNoData is final. backupCaptcha and backupIndeterminate mean "try later": do not retry them in a loop, because that makes a captcha worse. The portal's session errors (SII_PORTAL_SESSION_LIMIT, SII_PORTAL_BLOCKED and the rest) are described in SII portal and folios, and portalRejectionMessage(rejection) gives the Spanish explanation of any of these keys.

Next steps#

• SII portal and folios: the session, the lock and the cache these functions share.
• Books: the purchase and sales book (IECV), which the RCV replaced in production from period 2017-08.
• Errors: DteError and its codes.
• API reference for dte-sdk/portal: every signature and type.