# Cuenta y llaves (/docs/referencia/cuenta) 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](/docs/errores). | Método | Ruta | Qué hace | | -------- | ------------------------------------------------------- | ------------------------------------------------------------------------- | | `GET` | [`/account`](#get-account) | Devuelve la cuenta y la llave en uso | | `GET` | [`/api_keys`](#get-api-keys) | Lista las llaves de API (solo metadatos; los secretos nunca se devuelven) | | `POST` | [`/api_keys`](#post-api-keys) | Mintea una llave de API (solo con llave root) | | `DELETE` | [`/api_keys/{key_id}`](#delete-api-keys-key-id) | Revoca una llave de API de inmediato (solo con llave root) | | `POST` | [`/api_keys/{key_id}/roll`](#post-api-keys-key-id-roll) | Emite un secreto de reemplazo para una llave (solo con llave root) | ## `GET /account` [#get-account] **Devuelve la cuenta y la llave en uso** La cuenta autenticada y la credencial en uso — email, plan, empresas\_ready/total, y los scopes, el modo y la lista de empresas de la llave que llama. ```bash curl -sS https://api.facturia.cl/v1/account \ -H "Authorization: Bearer $FACTURIA_KEY" ``` **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La cuenta. | Account | | `400` | Código `empresa_header_forbidden` — esta operación es de nivel cuenta; un header `Facturia-Empresa` en ella se rechaza en vez de ignorarse en silencio. | ErrorResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `GET /api_keys` [#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. ```bash 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 | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /api_keys` [#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. ```bash 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` · `mandato:write` · `mandato:attest` · `onboarding:write` · `onboarding:attest`\[] | 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 | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `DELETE /api_keys/{key_id}` [#delete-api-keys-key-id] **Revoca una llave de API de inmediato (solo con llave root)** Revoca una llave de inmediato y sin vuelta atrás. Requiere una llave root o una sesión de cuenta (`403 root_key_required`) — una llave normal no puede revocar llaves, ni siquiera a sí misma. ```bash 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. | — | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `404` | No existe ese objeto bajo esta llave. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse | ## `POST /api_keys/{key_id}/roll` [#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 ventana de caída. La rotación es un compare-and-swap sobre el hash actual de la llave, así que dos rotaciones de la misma llave nunca pueden aterrizar las dos: gana exactamente una y la perdedora responde `409 api_key_roll_conflict`, cuyo secreto es el que está vivo. Rota una vez por llave. ```bash 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 | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `409` | Conflicto de estado: reutilización de idempotencia, `external_id` duplicado o artefacto no listo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse |