API reference

This reference is generated from public-api-openapi.yaml on every build, so it cannot drift from the contract. The prose specification governs wherever the two disagree.

https://api.facturia.cl/v1

TLS 1.2+ only. No unversioned root, no unencrypted port. Every response carries Facturia-Request-Id; quote it in support.

The raw contract

This page is the human reading of it. The OpenAPI 3.1 document it comes from, version 1.0.0, is published verbatim to generate clients from:

There are two documents because there are two surfaces: /v1 authenticates with an sk_ key, and a freshly created account has none yet. The cold start answers on a different base URL, with an account session instead of a key, so folding it into the same file would declare URLs and credentials that do not exist. Generate a client from the second one to get the key, and one from the first to use the product.

No path reaches the published file without having been probed against the real router: if the contract declared an endpoint the API does not mount, this site’s build fails before publishing it.

Generate a typed client

We publish no npm or pip package: the API is HTTP and nothing else, and an in-house SDK is a layer that lags behind the contract. What we do publish is the contract, and a typed client comes out of it in one line. There are two commands because there are two documents: the cold-start one gets you the key, the /v1 one uses the product.

TypeScript

npx openapi-typescript https://docs.facturia.cl/openapi-bootstrap.yaml -o bootstrap.d.ts
npx openapi-typescript https://docs.facturia.cl/openapi.yaml -o facturia.d.ts

It emits types only, no runtime. For calls, fetch with those types is enough; if you would rather have a client with methods, openapi-fetch consumes the same facturia.d.ts.

Python

pipx run openapi-python-client generate --url https://docs.facturia.cl/openapi-bootstrap.yaml
pipx run openapi-python-client generate --url https://docs.facturia.cl/openapi.yaml

# uvx openapi-python-client generate --url …   # lo mismo, si usas uv / same thing, with uv

Both documents go through both Python generators whole: openapi-python-client emits all 11 cold-start operations and all 122 /v1 ones without dropping a single response or schema, and openapi-generator-cli -g python finishes on both without an exception. It was not so until 2026-09-07 — the envelope's nullable data clashed with each operation's typed data and all five /account/* responses came out untyped, the one that hands over data.api_key.secret included; and SendJob, StatementImportJob, RcvEntry, RcvEntryList and AutomationSettings vanished from the client. Those were shapes in the document, not limits of the generator, and they are fixed (#476) without changing one byte of what goes over the wire.

The one exception left: the four binary artifacts (GET /documents/{document_id}/pdf and /xml, and their two twins under /received_documents) answer application/pdf and application/xml, and openapi-python-client only types JSON bodies. The method is generated all the same and response.content carries the bytes; if you want the type, hand it a config.yml with content_type_overrides: {"application/pdf": "application/octet-stream", "application/xml": "text/plain"}. We do not fix this in the document because the declared Content-Type is the one the server really sends.

Both documents are OpenAPI 3.1. A generator that only understands 3.0 will trip over the nullable types (type: [integer, "null"]), which is the correct 3.1 shape — use a version that supports 3.1 rather than converting the document.

Versioning inside /v1 is additive (§5.8), so a regenerated client never loses a method: it only gains new fields and new enum values. A client that breaks on an unknown field has a bug, and that is the only compatibility rule we ask for.

Chapters

Every endpoint

Webhooks

The OpenAPI also describes the outgoing deliveries. Their shape, their signature and their retry schedule are in Webhooks.