Usage
The immutable usage ledger: how much you issued and for which empresa. It is a report, not a meter — the plan is flat, with unlimited documents.
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.
| Method | Path | What it does |
|---|---|---|
GET | /usage | Usage summary for a billing period |
GET | /usage/records | The immutable usage ledger |
GET /usage
Usage summary for a billing period
Current-period request and emission counts against the account's plan limits.
curl -sS https://api.facturia.cl/v1/usage \
-H "Authorization: Bearer $FACTURIA_KEY"Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
period | query | — | Period | Tax period, YYYY-MM, America/Santiago. |
group_by | query | — | empresa · tipo_dte · metric |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | The usage summary. | UsageSummary |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |
GET /usage/records
The immutable usage ledger
One record per accepted document. A document is recorded when the SII accepts it — rejected, failed and sandbox documents never appear here. Corrections are compensating records with negative quantity, never updates. This is a report, not a meter: the plan is flat and unlimited, so nothing here is priced per document.
curl -sS https://api.facturia.cl/v1/usage/records \
-H "Authorization: Bearer $FACTURIA_KEY"Parameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
limit | query | — | integer | |
cursor | query | — | string | Opaque cursor from a previous response's next_cursor. |
period | query | — | Period | Tax period, YYYY-MM, America/Santiago. |
metric | query | — | document_accepted · received_document · f29_filing · empresa_active | |
empresa_rut | query | — | Rut |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | A list of usage records. | lista de UsageRecord |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
429 | Too many requests. | ErrorResponse |
default | An error not otherwise enumerated for this operation, in the same §5.5 envelope as every other refusal. Branch on error.code, never on the HTTP status alone or on error.message — a code this operation has not been seen to throw yet is still safer to route on than a string meant for a human. | ErrorResponse |