# Consumo (/docs/referencia/consumo)

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`  | [`/usage`](#get-usage)                 | Resumen de consumo de un período de facturación |
| `GET`  | [`/usage/records`](#get-usage-records) | El libro de consumo inmutable                   |

## `GET /usage` [#get-usage]

**Resumen de consumo de un período de facturación**

Los conteos de solicitudes y emisiones del periodo actual, frente a los límites del plan de la cuenta.

```bash
curl -sS https://api.facturia.cl/v1/usage \
  -H "Authorization: Bearer $FACTURIA_KEY"
```

**Parámetros**

| Parámetro  | En    | Requerido | Tipo                              | Notas                                            |
| ---------- | ----- | --------- | --------------------------------- | ------------------------------------------------ |
| `period`   | query | —         | Period                            | Período tributario, `YYYY-MM`, America/Santiago. |
| `group_by` | query | —         | `empresa` · `tipo_dte` · `metric` |                                                  |

**Respuestas**

| Código    | Significado                                                                                                                                                                                                                                                                                                               | Cuerpo        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `200`     | El resumen de consumo.                                                                                                                                                                                                                                                                                                    | UsageSummary  |
| `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 |

## `GET /usage/records` [#get-usage-records]

**El libro de consumo inmutable**

Un registro por documento aceptado. Un documento se anota cuando el SII lo acepta —
los rechazados, los fallidos y los del sandbox no aparecen nunca aquí. Las correcciones son
registros compensatorios con cantidad negativa, jamás actualizaciones. Esto es un reporte y no un
medidor: el plan es plano y con documentos ilimitados, así que ningún número de acá cambia lo que pagas.

```bash
curl -sS https://api.facturia.cl/v1/usage/records \
  -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. |
| `period`      | query | —         | Period                                                                      | Período tributario, `YYYY-MM`, America/Santiago.                 |
| `metric`      | query | —         | `document_accepted` · `received_document` · `f29_filing` · `empresa_active` |                                                                  |
| `empresa_rut` | query | —         | Rut                                                                         |                                                                  |

**Respuestas**

| Código    | Significado                                                                                                                                                                                                                                                                                                               | Cuerpo               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `200`     | Una lista de registros de consumo.                                                                                                                                                                                                                                                                                        | lista de UsageRecord |
| `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        |