--- title: "List fiscal invoices" method: GET path: "/v1/fiscal_invoices" tags: ["Fiscal Invoice"] --- # List fiscal invoices `GET /v1/fiscal_invoices` ## Request - Base URL: `https://api.cardda.com` - URL: `https://api.cardda.com/v1/fiscal_invoices` - Auth: HTTP bearer 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 ```bash # 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. ## Query parameters - `company_id` string, uuid - `number` string - `document_type` string - `issuer_id` string - `receiver_id` string - `issuer_name` string - `receiver_name` string - `issue_type` 'received' | 'issued' - `payment_status` 'paid' | 'non_paid' - `service_invoice_status` 'VIG' | 'ANUL' - `currency` string - `total_amount` string - `tax_period` string - `issue_date` string - `reception_date` string - `expiration_date` string - `cancellation_date` union - string, date-time - 'null' - string: JSON-encoded operator object (`{"$gte":"..."}`, etc.). - `counterpart_id` string, uuid - `created_at` string - `updated_at` string ## 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 `200` Paginated list of fiscal invoices. Headers include `X-Total-Count` and `Content-Range` for offset pagination — see [Pagination](https://docs.cardda.com/docs/pagination). - FiscalInvoice[] - `id` string, required: Unique identifier of the fiscal invoice - `document_type` number, required: Type of document (e.g. 33 for invoice, 34 for exempt invoice, 39 for electronic receipt) - `company_id` string, uuid, required: ID of the company associated with this invoice - `number` string, required: Number of the invoice - `issuer_id` string: ID of the entity that issued the invoice, tax identification number for Chilean subjects - `receiver_id` string: 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_amount` number, required: Total amount of the invoice - `net_amount` number: Net amount of the invoice - `currency` string: Currency of the invoice (e.g., CLP) - `tax_period` string: Tax period (e.g., MM/YYYY) - `expiration_date` string, date-time, nullable: Expiration date of the invoice - `created_at` string, date-time: Date and time when the record was synced from IRS - `updated_at` string, date-time: Date and time when the record was last updated - `cancellation_date` string, date-time, nullable: Date and time when the invoice was cancelled (null if not cancelled) - `is_services_invoice` boolean, 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_status` string, nullable: Status of payment (e.g., paid, non_paid) - `tradable` object, 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_date` string, 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. - `issuer` object, nullable: Compact projection of the issuer `Person` row (only `id`, `name`, `identifier`), included inline on list and detail responses. - `id` string, uuid - `name` string, nullable - `identifier` string: Tax id (RUT) of the issuer. - `receiver` object, nullable: Compact projection of the receiver `Person` row (only `id`, `name`, `identifier`), included inline on list and detail responses. - `id` string, uuid - `name` string, nullable - `identifier` string: Tax id (RUT) of the receiver. - `sii_event_status` string, 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). - `items` object[]: Line items in the invoice - `id` number, required: ID of the item - `name` string, required: Name of the item - `unit` string, nullable: Unit of measurement - `price` number, required: Price per unit - `amount` number, required: Total amount for this item - `discount` number, nullable: Discount amount - `quantity` number, required: Quantity of items - `description` string, required: Description of the item - `issuer_name` string: Name of the entity that issued the invoice - `receiver_name` string: Name of the entity receiving the invoice - `referenced_documents` object[]: Referenced documents - `number` string, required: Reference document number - `document_type` integer, required: Type of referenced document (e.g., 33, 34, 61) - `raw_xml` string: Raw XML content of the invoice - `counterpart_id` string, uuid: UUID of the counterpart `Person` row Cardda associates with this invoice (the supplier for `received` invoices, the customer for `issued`). - `issue_date` string, date-time, required: Date when the invoice was issued - `reception_date` string, date-time: Date when the invoice was received in the system - `iva_amount` number: IVA (VAT) amount - `operation` string: Type of operation (e.g., purchase) ## Other 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. --- [API](https://skmtc.dev/cardda/apis/internal-revenue-service-api.md) - [All operations](https://skmtc.dev/cardda/apis/internal-revenue-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/internal-revenue-service-api/revisions/22003ee905f0?raw)