List fiscal invoices

get

https://api.cardda.com/v1/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

_start

integer

Defaults to 0

Page offset

_end

integer

Defaults to 10

Page limit

_order

string

enum

Defaults to ASC

Order to apply

Allowed:

_field

string

Field to order by

company_id

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.

number

string

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

document_type

string

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_id

string

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

receiver_id

string

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

issuer_name

string

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

receiver_name

string

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

issue_type

string

enum

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

Allowed:

payment_status

string

enum

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

Allowed:

service_invoice_status

string

enum

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).

Allowed:

currency

string

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

total_amount

string

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_period

string

^(0[1-9]|1[0-2])/[0-9]{4}$

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

issue_date

string

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_date

string

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_date

string

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.

cancellation_date

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_id

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_at

string

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_at

string

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).

Headers

company-id

uuid

required

UUID of the company on whose behalf the request is made. Fiscal-invoice endpoints
authorize the caller against this company (and read/write its data). SII-key
endpoints never filter their results by this header. On the SII-key list,
however, belonging to the header company is one of the ways a caller is authorized
to make the call (alongside being Cardda staff or passing their own user_id), so
the header is not merely ignored there. On the other SII-key endpoints the header
plays no part in authorization. See The company-id header
for details on how to obtain a value for this header and the error responses to
expect when it is missing or invalid.

Responses

401

Unauthorized — missing or invalid bearer token, company-id header not
set, or the caller is not a member of the company referenced by
company-id. Authorization failures surface as 401 (not 403): Pundit
renders 401 with an empty body.

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