Cuenta y llaves
La cuenta autenticada, la llave en uso y el minteo de llaves con una llave root.
Base: https://api.facturia.cl/v1. Todos los endpoints de este capítulo se autentican con Authorization: Bearer salvo que se diga lo contrario, y el sobre de error es el de Errores.
| Método | Ruta | Qué hace |
|---|---|---|
GET | /account | Devuelve la cuenta y la llave en uso |
GET | /api_keys | Lista las llaves de API (solo metadatos; los secretos nunca se devuelven) |
POST | /api_keys | Mintea una llave de API (solo con llave root) |
DELETE | /api_keys/{key_id} | Revoca una llave de API de inmediato (solo con llave root) |
POST | /api_keys/{key_id}/roll | Emite un secreto de reemplazo para una llave (solo con llave root) |
GET /account
Devuelve la cuenta y la llave en uso
curl -sS https://api.facturia.cl/v1/account \
-H "Authorization: Bearer $FACTURIA_KEY"Respuestas
| Código | Significado | Cuerpo |
|---|---|---|
200 | La cuenta. | Account |
401 | Llave ausente, mal formada o revocada. | ErrorResponse |
GET /api_keys
Lista las llaves de API (solo metadatos; los secretos nunca se devuelven)
Una llave root ve todas las llaves de la cuenta. Una llave común se ve solo a sí misma.
curl -sS https://api.facturia.cl/v1/api_keys \
-H "Authorization: Bearer $FACTURIA_KEY"Parámetros
| Parámetro | En | Requerido | Tipo | Notas |
|---|---|---|---|---|
limit | query | — | integer | |
cursor | query | — | string | Cursor opaco tomado del next_cursor de una respuesta anterior. |
Respuestas
| Código | Significado | Cuerpo |
|---|---|---|
200 | Una lista de llaves de API. | lista de ApiKey |
401 | Llave ausente, mal formada o revocada. | ErrorResponse |
POST /api_keys
Mintea una llave de API (solo con llave root)
Requiere una llave root (sk_live_root_… / sk_test_root_…) con el scope keys:write.
Las barreras se aplican en el servidor: las empresas de la llave nueva deben ser un subconjunto de la
lista de la llave que la mintea y sus scopes un subconjunto de los suyos (si no, 403 privilege_escalation);
el modo se hereda; y una llave root no puede mintear otra llave root. El secret se devuelve una sola vez.
curl -sS -X POST https://api.facturia.cl/v1/api_keys \
-H "Authorization: Bearer $FACTURIA_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"cliente — Comercial Andina","scopes":["documents:read","documents:write"]}'Parámetros
| Parámetro | En | Requerido | Tipo | Notas |
|---|---|---|---|---|
Idempotency-Key | header | — | string | Llave que genera el cliente, única por operación lógica, retenida 24 h y con alcance (cuenta, empresa, endpoint). Un replay devuelve la respuesta original con Facturia-Idempotent-Replay: true. Misma llave y cuerpo distinto → 409. |
Cuerpo
| Campo | Tipo | Requerido | Notas |
|---|---|---|---|
name | string | sí | |
mode | live · test | — | |
scopes | documents:read · documents:write · received:read · received:write · empresas:read · empresas:write · folios:write · tax:read · tax:write · webhooks:read · webhooks:write · usage:read · keys:write[] | sí | |
empresas | Rut[] | — | Un subconjunto de la lista blanca de la llave que la mintea. Un solo RUT la convierte en token de empresa. |
| Respuestas |
| Código | Significado | Cuerpo |
|---|---|---|
201 | La llave minteada, con su secreto. | ApiKeyWithSecret |
400 | Entrada mal formada o incompleta. | ErrorResponse |
403 | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse |
DELETE /api_keys/{key_id}
Revoca una llave de API de inmediato (solo con llave root)
curl -sS -X DELETE https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9 \
-H "Authorization: Bearer $FACTURIA_KEY"Parámetros
| Parámetro | En | Requerido | Tipo | Notas |
|---|---|---|---|---|
key_id | path | sí | string |
Respuestas
| Código | Significado | Cuerpo |
|---|---|---|
204 | Revocada. La revocación es inmediata e irrecuperable. | — |
403 | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse |
404 | No existe ese objeto bajo esta llave. | ErrorResponse |
POST /api_keys/{key_id}/roll
Emite un secreto de reemplazo para una llave (solo con llave root)
El secreto anterior sigue funcionando 24 horas, así que puedes desplegar sin corte.
curl -sS -X POST https://api.facturia.cl/v1/api_keys/key_01K2QWB7T4N9/roll \
-H "Authorization: Bearer $FACTURIA_KEY"Parámetros
| Parámetro | En | Requerido | Tipo | Notas |
|---|---|---|---|---|
key_id | path | sí | string |
Respuestas
| Código | Significado | Cuerpo |
|---|---|---|
200 | La llave con su secreto nuevo. | ApiKeyWithSecret |
403 | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse |