Meta
Unauthenticated reference data.
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 | /jobs/{job_id} | Retrieve an async job (folio request, send, cesión, RCV sync, import) |
GET | /mandato_terms | The current mandato text and version |
GET | /error_codes | The machine-readable error dictionary (unauthenticated) |
GET /jobs/{job_id}
Retrieve an async job (folio request, send, cesión, RCV sync, import)
One endpoint for every asynchronous operation the API starts. Read type first: it decides
the shape of result and which scope may read the job (the scope that STARTS that kind of
job, plus the read scope for the subject it acts on — a documents:read key may watch a
send, and is refused a tax filing).
Facturia-Poll-After says when to ask again, in seconds, and is ABSENT once status is
succeeded or failed: there is nothing left to observe. Do not poll faster than it says —
nothing on this surface can finish inside the queue's own 10-second claim interval.
mode is on the object, and a job created in the other mode does not exist for this
credential: the answer is 404, not 403 (§4.2).
curl -sS https://api.facturia.cl/v1/jobs/job_01K2R8B4V6WQ2XParameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
job_id | path | yes | string |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | The job. | Job |
400 | empresa_header_forbidden — this operation is account-level (a job belongs to the key's account, not to one empresa); a Facturia-Empresa header on it is refused. | ErrorResponse |
401 | Missing, malformed or revoked key. | ErrorResponse |
403 | Valid key, not permitted — scope, empresa allowlist, or mode. | ErrorResponse |
404 | No such object under this key. | 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 /mandato_terms
The current mandato text and version
The text §7.3 tells you to present before posting an acceptance. Unauthenticated, for the
same reason GET /error_codes is: the body is a constant with no tenant data in it.
READ status FIRST. draft means the text has not finished attorney review and is not yet
binding — do not present it to a representante legal as terms they are signing. It is
derived from the document's own review banner, so it flips to active on the day the
review lands rather than on the day someone remembers to update a constant.
This endpoint hands over the words only. Recording an acceptance is
POST /empresas/\{empresa_id\}/mandato.
annexes[] carries the documents the contract's own header calls «parte integrante» —
prices, personal data, the automation matrix — with their Markdown, because a page that
asks somebody to accept a contract has to be able to show them all of it (ticket #519).
content_hash still covers text alone: those are the bytes an acceptance records.
?version= fetches a specific version. Omit it for the text in force — a caller who
forgets it must never be handed a draft. Use it to read a draft of what comes next before
it binds anyone, and to fetch the exact version an older acceptance recorded (the mandato
receipt's terms_url does precisely that). An unknown value is 400 invalid_field.
curl -sS https://api.facturia.cl/v1/mandato_termsParameters
| Parameter | In | Required | Type | Notes |
|---|---|---|---|---|
version | query | — | string | A version from available_versions. Omitted means the current text. |
Responses
| Code | Meaning | Body |
|---|---|---|
200 | Mandato terms. | object |
400 | Malformed or missing input. | 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 /error_codes
The machine-readable error dictionary (unauthenticated)
Every code this API can put in an error.code, plus the SII rejection codes that appear
inside a document's rejection_reasons[]. Told apart by type: a rejection row is not a
response and carries http_status: null.
retriable is answered about the IDENTICAL request — rate_limit_exceeded is retriable
because waiting fixes it, totals_mismatch is not. Build retry policy on that field rather
than on the status code.
No credential, and no rate limit: the body is a constant with no tenant data in it.
curl -sS https://api.facturia.cl/v1/error_codesResponses
| Code | Meaning | Body |
|---|---|---|
200 | Every Facturia error code, its SII counterpart, and whether it is retriable. | lista de ErrorCode |
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 |