Fiscal Invoice

List fiscal invoices

Returns a paginated list of fiscal invoices (DTEs — Documentos Tributarios Electrónicos) the company has issued or received in Chile via the SII.

Cardda mirrors the company's SII inbox/outbox locally, so this endpoint serves as the integrator-facing source of truth for VAT recovery, accounts payable / receivable reconciliation, and month-end reporting. The data is updated automatically from the SII; you should treat it as read-mostly.

Scoping

The company-id header gates access (you must be a member of the company it references, otherwise 401), but it does not narrow the result set. Results span the fiscal invoices of every company the caller is a member of. To restrict the list to a single company, pass an explicit company_id filter (query parameter) — see below.

When you'll use this endpoint

Build accounts-payable dashboards (filter issue_type=received).
Build accounts-receivable dashboards (filter issue_type=issued).
Sync to your accounting/ERP — pull every invoice updated since the last sync watermark.
Find pending payments (payment_status=non_paid plus an expiration_date filter).

Identifier format

Fiscal-invoice ids are strings, not UUIDs, and follow the composite pattern id = "#{issuer_id}-#{document_type}-#{number}", where issuer_id is the issuer's RUT and already contains its own hyphen before the verifier digit (e.g. 76123456-7). The full id therefore looks like 76123456-7-33-1234 — split it as (issuer_id="76123456-7", document_type="33", number="1234"), not as four --separated tokens. This is the value to store and the value to pass to GET /v1/fiscal_invoices/{fiscal_invoice_id}. Unique lookups should combine issuer_id, document_type, and number.

Heads-up: the invoice_id field on a card transaction is not a fiscal-invoice id. It is a UUID pointing to a separate, legacy Invoice model kept for backwards compatibility, and is unrelated to SII DTEs.

Document types

Chilean SII codes used in document_type:

Code	Name	Notes
33	Factura electrónica	Standard sales invoice (afecta IVA).
34	Factura exenta electrónica	Exempt invoice.
39	Boleta electrónica	Receipt-style document, retail.
41	Boleta exenta electrónica	Receipt, exempt.
43	Liquidación-factura	Settlement invoice for consignment.
46	Factura de compra electrónica	Buy-invoice (tax-withheld imports).
52	Guía de despacho	Shipment doc (DTE, but not a tax doc).
56	Nota de débito electrónica	Increases the value of a referenced invoice.
61	Nota de crédito electrónica	Decreases / reverses a referenced invoice.
110	Factura de exportación electrónica	Export invoice.
111	Nota de débito de exportación	Export debit note.
112	Nota de crédito de exportación	Export credit note.

Common queries

# Most-used pattern (real production traffic): incremental sync of credit notes.
# Walk one 100-row page at a time — _end - _start is capped at 2 000 server-side
# (anything larger returns 416). See https://docs.cardda.com/docs/pagination for the iteration recipe.
GET /v1/fiscal_invoices?\
  _start=0&_end=100&\
  _order=ASC&_field=updated_at&\
  updated_at={"$gt":"2026-05-03T00:00:00.000Z"}&\
  document_type=61

# All invoices ever received from a single supplier
GET /v1/fiscal_invoices?\
  issuer_id=76123456-7&issue_type=received

# Unpaid invoices (account payable backlog)
GET /v1/fiscal_invoices?\
  issue_type=received&payment_status=non_paid

# All invoices by document type group (debit + credit notes)
GET /v1/fiscal_invoices?document_type={"$in":[56,61]}

# Last 7 days of issued invoices, sorted newest-first
GET /v1/fiscal_invoices?\
  issue_type=issued&\
  created_at={"$gte":"2026-04-22T00:00:00Z"}&\
  _order=DESC&_field=created_at

Timezone gotcha

The Chilean SII timestamps are in Chile local time (UTC−3 / UTC−4 depending on DST). When you filter by created_at, updated_at, issue_date, reception_date, etc., the server treats values as UTC. To filter "since 2026-01-01 00:00 Chile time", convert: 2026-01-01T03:00:00Z. Plan accordingly during DST transitions.

get/v1/fiscal_invoices

Request

Base URL
https://api.cardda.com
URL
https://api.cardda.com/v1/fiscal_invoices
Auth
HTTP bearer

Query parameters

company_idstring uuid

Narrows the result set to a single company. Unlike the company-id header (which only gates access), this filter actually restricts the rows returned — without it, results span every company the caller is a member of. Must be a company the caller belongs to.

numberstring

SII folio number (the formal "número de factura"). Combine with issuer_id and document_type for unique lookup.

document_typestring

Chilean SII document type code. See the table above for the catalog. Accepts a plain integer (document_type=33) or a JSON-encoded operator object for multi-type queries (document_type={"$in":[56,61]}). Schema is type: string so both forms validate.

issuer_idstring

Tax id of the issuer. For received invoices this is the supplier's RUT; for issued invoices this is your company's RUT.

receiver_idstring

Tax id of the receiver. For received invoices this is your company's RUT; for issued invoices this is the customer's RUT.

issuer_namestring

Free-form name of the issuer (as it appears on the DTE). Useful with $regex.

receiver_namestring

Free-form name of the receiver. Useful with $regex.

issue_type'received' | 'issued'

Whether the invoice was issued by your company (issued) or received from a counterpart (received).

payment_status'paid' | 'non_paid'

Cardda-side payment status (computed from associated payments).

service_invoice_status'VIG' | 'ANUL'

Status of the SII service-invoice acceptance lifecycle (only relevant for invoices from the is_services_invoice=true flow). Values are VIG (vigente — in force) or ANUL (anulado — annulled).

currencystring

ISO-4217 currency of the invoice. Most CL invoices are CLP; export invoices are USD.

total_amountstring

Invoice total (minor units). Accepts a plain integer (total_amount=1000000) or a JSON-encoded operator object for comparators ({"$gte":1000000}). Schema is type: string so both forms validate; see Filters.

tax_periodstring

Tax period in MM/YYYY format (matches the schema field; canonical value parsed from the SII XML). Useful for monthly VAT reports.

issue_datestring

SII issue date (when the issuer dated the document). UTC ISO-8601; remember the timezone gotcha described above. Accepts either a single date-time string or a JSON-encoded operator object ({"$gte":"...","$lt":"..."}) — schema is type: string (no format) so both forms validate.

reception_datestring

When the SII received the document. May lag issue_date by a few hours. Accepts a single date-time string or a JSON-encoded operator object ({"$gte":"...","$lt":"..."}) — schema is type: string (no format) so both forms validate.

expiration_datestring

Payment due date. Useful to find invoices about to go overdue — expiration_date={"$lt":"2026-05-15T00:00:00Z"} plus payment_status=non_paid. Accepts a single date-time string or a JSON-encoded operator object — schema is type: string (no format) so both forms validate.

string date-time

'null'

string

JSON-encoded operator object ({"$gte":"..."}, etc.).

When the invoice was cancelled (if it was); stored as null for active invoices. Because query-string values are always strings, pass the literal string cancellation_date=null to filter for active invoices. Otherwise, accepts a single date-time string or a JSON-encoded operator object ({"$gte":"...","$lt":"..."}).

counterpart_idstring uuid

UUID of the counterpart (people row) Cardda associates with this invoice. For received invoices this is the supplier's people row; for issued, the customer's.

created_atstring

When the row was created in Cardda's database. Useful for incremental sync of new invoices. Accepts a single date-time string or a JSON-encoded operator object — schema is type: string (no format).

updated_atstring

When the row was last updated. The recommended cursor for incremental sync — track the max updated_at seen and re-pull on each sync tick with updated_at={"$gt":"<watermark>"}. Accepts a single date-time string or a JSON-encoded operator object — schema is type: string (no format).

Parameters

#/paths/~1v1~1sii~1keys/get/parameters/0 (unresolved $ref)

#/paths/~1v1~1sii~1keys/get/parameters/1 (unresolved $ref)

#/paths/~1v1~1sii~1keys/get/parameters/2 (unresolved $ref)

#/paths/~1v1~1sii~1keys/get/parameters/3 (unresolved $ref)

#/paths/~1v1~1sii~1keys/get/parameters/4 (unresolved $ref)

Response

Paginated list of fiscal invoices. Headers include X-Total-Count and Content-Range for offset pagination — see Pagination.

idstring required

Unique identifier of the fiscal invoice

document_typenumber required

Type of document (e.g. 33 for invoice, 34 for exempt invoice, 39 for electronic receipt)

company_idstring uuid required

ID of the company associated with this invoice

numberstring required

Number of the invoice

issuer_idstring

ID of the entity that issued the invoice, tax identification number for Chilean subjects

receiver_idstring

ID of the entity receiving the invoice, tax identification number for Chilean subjects

issue_type'received' | 'issued' required

Whether the invoice was received or issued by the company

total_amountnumber required

Total amount of the invoice

net_amountnumber

Net amount of the invoice

currencystring

Currency of the invoice (e.g., CLP)

tax_periodstring

Tax period (e.g., MM/YYYY)

expiration_datestring date-time nullable

Expiration date of the invoice

created_atstring date-time

Date and time when the record was synced from IRS

updated_atstring date-time

Date and time when the record was last updated

cancellation_datestring date-time nullable

Date and time when the invoice was cancelled (null if not cancelled)

is_services_invoiceboolean nullable

Whether the invoice corresponds to a services invoice

service_invoice_status'VIG' | 'ANUL' nullable

SII service-invoice acceptance status synced from the upstream document. VIG (vigente) means the document is in force; ANUL (anulado) means it was annulled. Populated only for invoices in the is_services_invoice=true flow; null for other invoices or while the backfill has not yet run.

payment_statusstring nullable

Status of payment (e.g., paid, non_paid)

tradableobject nullable

The ERP payout item (Erp::Payouts::Tradable — a payable, receivable, credit note, etc.) Cardda derives from this invoice, serialized inline via the tradable method. null until a tradable has been created for the invoice.

due_datestring date-time nullable

Payment due date, taken from the linked tradable (tradable&.due_date). null when there is no tradable or it has no due date. Rendered via a serializer method, not a stored column.

sii_event_statusstring nullable

The action the SII recorded for this document from an accept/reject event (e.g. ACD, RCD); null until an event is submitted. See POST /v1/fiscal_invoices/{id}/accept_sii_event and /reject_sii_event.

sii_event_state'idle' | 'submitting' | 'submitted'

Idempotency state of the SII acceptance/rejection lifecycle: idle (default), submitting (event in flight), submitted (recorded).

issuer_namestring

Name of the entity that issued the invoice

receiver_namestring

Name of the entity receiving the invoice

raw_xmlstring

Raw XML content of the invoice

counterpart_idstring uuid

UUID of the counterpart Person row Cardda associates with this invoice (the supplier for received invoices, the customer for issued).

issue_datestring date-time required

Date when the invoice was issued

reception_datestring date-time

Date when the invoice was received in the system

iva_amountnumber

IVA (VAT) amount

operationstring

Type of operation (e.g., purchase)

Changes

No recorded changes to this operation across all 1 revision of this API.