Tax

Base: https://api.facturia.cl/v1. Every endpoint in this chapter authenticates with Authorization: Bearer unless stated otherwise, and the error envelope is the one in Errors.

GET /tax/purchases

RCV — registro de compras

The purchases ledger (Registro de Compras) synced from the SII, filterable by period, with each entry's estado_contable and any characterize outcome.

curl -sS https://api.facturia.cl/v1/tax/purchases \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/sales

RCV — registro de ventas

The sales ledger (Registro de Ventas) synced from the SII, filterable by period.

curl -sS https://api.facturia.cl/v1/tax/sales \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/summary

Aggregated RCV totals for a period (the F29 inputs)

Period totals across purchases and sales — the numbers an F29 proposal is built from, before any characterization is applied.

curl -sS https://api.facturia.cl/v1/tax/summary \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/sync

Force an RCV resync (async)

Trigger a fresh pull of the purchases and sales ledgers from the SII for the empresa, for ONE period. Returns a job (type: rcv_sync) to poll on GET /jobs/\{job_id\}; the ledger updates only once it succeeds, and result then carries what was read.

period defaults to the previous month (America/Santiago), and the job always reports the period it read in result.period. The daily sync reads the last three months, and the first sweep after an empresa's first successful sync backfills the twelve months before that; anything older has NEVER been read unless somebody asked for it here — a sync.last_synced_at of null on GET /tax/sales?period=… is how you can tell. To reach further back, call this once per period; the bucket is 10 requests per minute per empresa.

Force means force. A call while a sync for the same period is still queued or running attaches to that job rather than queueing a second one; a call after it has finished queues a fresh read, whatever the daily sync did this morning.

curl -sS -X POST https://api.facturia.cl/v1/tax/sync \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"period":"2026-07"}'

Parameters

Body

POST /tax/purchases/characterize

Caracterizar up to 500 purchase entries in one call

Characterize purchase-ledger entries in bulk (entry_ids[] plus the shared estado_contable/tax treatment), for the common case of clearing a whole period at once.

curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/characterize \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"entries":[{"id":"rcv_01K2RB7Q2M4X","tipo_compra":"del_giro"}]}'

Parameters

Body

POST /tax/purchases/{entry_id}/characterize

Caracterizar one purchase entry (writes to the SII registry)

Characterize one purchase-ledger entry — its estado_contable and whether its IVA is recoverable — overriding the SII's own proposal where the empresa's own accounting disagrees.

curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/characterize \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tipo_compra":"del_giro","iva_uso_comun":true}'

Parameters

Body

POST /tax/purchases/{entry_id}/characterize/revert

Undo the last settled caracterización on a purchase

Queues a NEW caracterización restoring the previous_tipo_compra recorded on the last settled action for this purchase, linked to it by reverts. It does not edit or delete the original: a write to a tax register that happened, happened, and its row is the evidence.

An undo of a write to the SII is itself a write to the SII, so it passes the identical opt-in gate and the identical confirmation two-step. 409 characterization_nothing_to_revert when no settled action exists, or when the last one recorded no previous value.

Reverting to no_recuperable needs an iva_no_recuperable_code: the SII does not accept one without a reason, and the reason the earlier characterization used is only recoverable when a prior action on the same document recorded it.

curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/characterize/revert \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"iva_no_recuperable_code":1,"confirmation_id":"…"}'

Parameters

Body

POST /tax/purchases/{entry_id}/estado_contable

Move an entry between REGISTRO / PENDIENTE / NO_INCLUIR

Records a LOCAL bookkeeping estado for the purchase. It is written to estado_contable_override and never over estado_contable, which belongs to the SII's own register and is refreshed by every sync.

The F29 propuesta ignores the override unless the empresa's honor_estado_contable_override automation setting is on; the response's estado_contable_effective says which value the propuesta will use. Every write is recorded with the key that made it and the SII value it did not replace.

Changing an entry's caracterización at the SII is a different act, with a different endpoint (POST /tax/purchases/\{entry_id\}/characterize).

curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/estado_contable \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"estado_contable":"REGISTRO"}'

Parameters

Body

GET /tax/f29/proposals

List the periods that have a computed propuesta

A SPEC ADDITION over §12.3, which documents only the per-period read. Without it a caller reconciling a year, or a dashboard drawing twelve months, has to guess which periods exist and probe each one — twelve requests, eleven of them 404.

The rows omit validation and filing_id: both are one query per proposal, and a caller scanning a year is asking "which months are computed", which status already answers. Read the single propuesta for those.

curl -sS https://api.facturia.cl/v1/tax/f29/proposals \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/f29/proposals/{period}

Computed F29 propuesta for a period

Computed by Facturia from the synced RCV plus the empresa's PPM and remanente parameters. The SII pre-fills its own F29 for its own portal but publishes no API for it.

curl -sS https://api.facturia.cl/v1/tax/f29/proposals/2026-07 \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/f29/proposals/{period}/upload_file

Download the SII-format upload .txt for this proposal

The SII's own upload-ready .txt for this F29 period, generated from the same proposal GET /tax/f29/proposals/\{period\} returns.

curl -sS https://api.facturia.cl/v1/tax/f29/proposals/2026-07/upload_file \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/f29/proposals/{period}/public_links

Mint a no-auth link to the propuesta's upload .txt

upload_file_url needs a bearer key, which makes it useless as an MCP resource_link — most MCP hosts cannot attach the caller's OAuth token when dereferencing one. This mints the same kind of signed, unguessable, expiring link a document's artifacts get (§9.6), serving the identical ISO-8859-1 bytes.

tax:read, not tax:write: minting a link publishes nothing and changes no tax position.

curl -sS -X POST https://api.facturia.cl/v1/tax/f29/proposals/2026-07/public_links \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{"artifacts":["upload_file"],"expires_in_days":90}'

Parameters

Body

DELETE /tax/f29/proposals/{period}/public_links

Revoke every public link for this propuesta

Revoke every live public link minted for this F29 proposal's upload file.

curl -sS -X DELETE https://api.facturia.cl/v1/tax/f29/proposals/2026-07/public_links \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/f29/proposals/{period}/recompute

Recompute the proposal, optionally overriding codes

Rebuild the F29 proposal from the ledgers and any characterizations recorded since it was last computed. Does not file anything with the SII.

curl -sS -X POST https://api.facturia.cl/v1/tax/f29/proposals/2026-07/recompute \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{"overrides":[]}'

Parameters

Body

GET /tax/f29/filings

List F29 filings

F29 filings recorded for the empresa, newest first, each naming the period and the proposal it was filed from.

curl -sS https://api.facturia.cl/v1/tax/f29/filings \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/f29/filings

File the F29 for a period (async job)

There is no SII webservice for filing an F29. Facturia automates the SII "Upload" flow — a certificate-authenticated session submitting a fixed-format .txt — and models it as a job. confirm_total_payable must equal the proposal's figure.

curl -sS -X POST https://api.facturia.cl/v1/tax/f29/filings \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"period":"2026-07","confirm_total_payable":1373000}'

Parameters

Body

GET /tax/f29/filings/{filing_id}

Retrieve a filing

One F29 filing: the period, the filed totals, and the SII's own acknowledgment if one was captured.

curl -sS https://api.facturia.cl/v1/tax/f29/filings/f29fil_01K2RD9K3M8T \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/expenses

List ingested foreign-currency charges

Expense-ledger entries imported from a connected bank or accounting feed, filterable by period.

curl -sS https://api.facturia.cl/v1/tax/expenses \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/expenses

Ingest a charge that may require a tipo-46 factura de compra

Import expense-ledger entries directly (outside a connections sync), for a source the empresa does not have an automatic feed for yet.

curl -sS -X POST https://api.facturia.cl/v1/tax/expenses \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"provider":"fintoc","amount_original":1050,"currency":"USD","date":"2026-07-31"}'

Parameters

Body

GET /tax/suggestions

List tax suggestions

Categorization suggestions Facturia derived from imported statements and expenses, awaiting a confirm or dismiss.

curl -sS https://api.facturia.cl/v1/tax/suggestions \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

GET /tax/suggestions/{suggestion_id}

Retrieve a suggestion

One suggestion: what it proposes, and the evidence (matching entries, prior confirmations) it was derived from.

curl -sS https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parameters

Responses

POST /tax/suggestions/{suggestion_id}/confirm

Act on a suggestion (for emit_46, emits the document)

Accept a suggestion, applying its proposed categorization to the entries it names.

curl -sS -X POST https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V/confirm \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)"

Parameters

Responses

POST /tax/suggestions/{suggestion_id}/dismiss

Dismiss a suggestion

Reject a suggestion without applying it. Facturia does not re-suggest the identical categorization for the same entries.

curl -sS -X POST https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V/dismiss \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Content-Type: application/json" \
  -d '{"reason":"not_digital_service","note":"…"}'

Parameters

Body