Referencia de la API

Esta referencia se genera desde public-api-openapi.yaml en cada build, así que no puede desviarse del contrato. La especificación en prosa manda donde ambas difieran.

https://api.facturia.cl/v1

Solo TLS 1.2+. No hay raíz sin versionar ni puerto sin cifrar. Cada respuesta lleva Facturia-Request-Id; cítalo en soporte.

El contrato en crudo

Esta página es la lectura humana. El documento OpenAPI 3.1 del que sale, versión 1.0.0, se publica tal cual para generar clientes:

Son dos documentos porque son dos superficies: /v1 se autentica con una llave sk_, y una cuenta recién creada no tiene ninguna. El arranque en frío responde en otra URL base, con una sesión de cuenta en vez de una llave, así que meterlo en el mismo archivo declararía URLs y credenciales que no existen. Genera un cliente del segundo para conseguir la llave, y uno del primero para usar el producto.

Ninguna ruta llega al archivo publicado sin haber sido probada contra el router real: si el contrato declarara un endpoint que la API no monta, el build de este sitio falla antes de publicarlo.

Generar un cliente tipado

No publicamos un paquete de npm ni de pip: la API es HTTP y nada más, y un SDK propio es una capa que se queda atrás del contrato. Lo que sí publicamos es el contrato, y de ahí sale un cliente tipado con una línea. Son dos comandos porque son dos documentos: el del arranque en frío consigue la llave, el de /v1 usa el producto.

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

Emite solo tipos, sin runtime. Para las llamadas, fetch con esos tipos basta; si prefieres un cliente con métodos, openapi-fetch consume el mismo 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

Los dos documentos pasan enteros por los dos generadores de Python: openapi-python-client genera las 11 operaciones del arranque en frío y las 122 de /v1 sin descartar ninguna respuesta ni ningún esquema, y openapi-generator-cli -g python termina sin excepción sobre ambos. Hasta el 2026-09-07 no era así — el data nullable del sobre chocaba con el data tipado de cada operación y las cinco respuestas de /account/* salían sin tipo, justo la que entrega data.api_key.secret; y SendJob, StatementImportJob, RcvEntry, RcvEntryList y AutomationSettings desaparecían del cliente. Eran formas del documento, no límites del generador, y están corregidas (#476) sin cambiar un byte de lo que viaja por el cable.

La única excepción que queda: los cuatro artefactos binarios (GET /documents/{document_id}/pdf y /xml, y sus dos gemelos en /received_documents) responden application/pdf y application/xml, y openapi-python-client solo tipa cuerpos JSON. El método se genera igual y response.content trae los bytes; si quieres el tipo, pásale un config.yml con content_type_overrides: {"application/pdf": "application/octet-stream", "application/xml": "text/plain"}. No lo arreglamos en el documento porque el Content-Type declarado es el que el servidor manda de verdad.

Los dos documentos son OpenAPI 3.1. Un generador que solo entiende 3.0 va a tropezar con los tipos nullable (type: [integer, "null"]), que es la forma correcta en 3.1 — usa una versión que soporte 3.1 en vez de convertir el documento.

El versionado es aditivo dentro de /v1 (§5.8), así que un cliente regenerado nunca pierde un método: gana campos y valores de enum nuevos. Un cliente que se cae con un campo desconocido tiene un bug, y esa es la única regla de compatibilidad que pedimos.

Capítulos

Todos los endpoints

Webhooks

El OpenAPI también describe los envíos salientes. Su forma, su firma y su calendario de reintentos están en Webhooks.