# Impuestos (/docs/referencia/impuestos) 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` | [`/tax/purchases`](#get-tax-purchases) | RCV — registro de compras | | `GET` | [`/tax/sales`](#get-tax-sales) | RCV — registro de ventas | | `GET` | [`/tax/summary`](#get-tax-summary) | Totales agregados del RCV para un período (las entradas del F29) | | `POST` | [`/tax/sync`](#post-tax-sync) | Fuerza una resincronización del RCV (asíncrona) | | `POST` | [`/tax/purchases/characterize`](#post-tax-purchases-characterize) | Caracteriza hasta 500 entradas de compra en una sola llamada | | `POST` | [`/tax/purchases/{entry_id}/characterize`](#post-tax-purchases-entry-id-characterize) | Caracteriza una entrada de compra (escribe en el registro del SII) | | `POST` | [`/tax/purchases/{entry_id}/characterize/revert`](#post-tax-purchases-entry-id-characterize-revert) | Deshace la última caracterización asentada de una compra | | `POST` | [`/tax/purchases/{entry_id}/estado_contable`](#post-tax-purchases-entry-id-estado-contable) | Mueve una entrada entre REGISTRO / PENDIENTE / NO\_INCLUIR | | `GET` | [`/tax/f29/proposals`](#get-tax-f29-proposals) | Lista los períodos que tienen una propuesta calculada | | `GET` | [`/tax/f29/proposals/{period}`](#get-tax-f29-proposals-period) | Propuesta de F29 calculada para un período | | `GET` | [`/tax/f29/proposals/{period}/upload_file`](#get-tax-f29-proposals-period-upload-file) | Descarga el .txt en formato SII de esta propuesta | | `POST` | [`/tax/f29/proposals/{period}/public_links`](#post-tax-f29-proposals-period-public-links) | Crea un enlace sin autenticación al .txt de carga de la propuesta | | `DELETE` | [`/tax/f29/proposals/{period}/public_links`](#delete-tax-f29-proposals-period-public-links) | Revoca todos los enlaces públicos de esta propuesta | | `POST` | [`/tax/f29/proposals/{period}/recompute`](#post-tax-f29-proposals-period-recompute) | Recalcula la propuesta, con la opción de sobrescribir códigos | | `GET` | [`/tax/f29/filings`](#get-tax-f29-filings) | Lista las declaraciones de F29 | | `POST` | [`/tax/f29/filings`](#post-tax-f29-filings) | Declara el F29 de un período (job asíncrono) | | `GET` | [`/tax/f29/filings/{filing_id}`](#get-tax-f29-filings-filing-id) | Devuelve una declaración | | `GET` | [`/tax/expenses`](#get-tax-expenses) | Lista los cargos en moneda extranjera ingresados | | `POST` | [`/tax/expenses`](#post-tax-expenses) | Ingresa un cargo que podría requerir una factura de compra tipo 46 | | `GET` | [`/tax/suggestions`](#get-tax-suggestions) | Lista las sugerencias tributarias | | `GET` | [`/tax/suggestions/{suggestion_id}`](#get-tax-suggestions-suggestion-id) | Devuelve una sugerencia | | `POST` | [`/tax/suggestions/{suggestion_id}/confirm`](#post-tax-suggestions-suggestion-id-confirm) | Confirma una sugerencia (en `emit_46`, emite el documento) | | `POST` | [`/tax/suggestions/{suggestion_id}/dismiss`](#post-tax-suggestions-suggestion-id-dismiss) | Descarta una sugerencia | ## `GET /tax/purchases` [#get-tax-purchases] **RCV — registro de compras** El Registro de Compras sincronizado desde el SII, filtrable por periodo, con el `estado_contable` de cada entrada y el resultado de `characterize` si lo tiene. ```bash curl -sS https://api.facturia.cl/v1/tax/purchases \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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. | | `estado_contable` | query | — | `REGISTRO` · `PENDIENTE` · `NO_INCLUIR` · `RECLAMADO` | | | `tipo_dte` | query | — | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | | | `counterparty_rut` | query | — | Rut | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Entradas de compra del RCV, con metadatos de frescura de la sincronización. | RcvEntryList | | `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 /tax/sales` [#get-tax-sales] **RCV — registro de ventas** El Registro de Ventas sincronizado desde el SII, filtrable por periodo. ```bash curl -sS https://api.facturia.cl/v1/tax/sales \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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. | | `tipo_dte` | query | — | `33` · `34` · `39` · `41` · `46` · `52` · `56` · `61` | | | `counterparty_rut` | query | — | Rut | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Entradas de venta del RCV. | RcvEntryList | | `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 /tax/summary` [#get-tax-summary] **Totales agregados del RCV para un período (las entradas del F29)** Los totales del periodo entre compras y ventas — las cifras con que se arma una propuesta de F29, antes de aplicar cualquier caracterización. ```bash curl -sS https://api.facturia.cl/v1/tax/summary \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `period` | query | sí | Period | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Agregación por dirección y tipo de documento. | TaxSummary | | `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 | ## `POST /tax/sync` [#post-tax-sync] **Fuerza una resincronización del RCV (asíncrona)** Dispara una nueva lectura de los registros de compras y ventas desde el SII para la empresa, para UN período. Devuelve un `job` (`type: rcv_sync`) para consultar en `GET /jobs/\{job_id\}`; el registro se actualiza solo cuando termina con éxito, y `result` trae entonces lo que se leyó. **`period` por omisión es el mes anterior** (America/Santiago), y el job siempre informa el período que leyó en `result.period`. La sincronización diaria lee los últimos tres meses, y el primer barrido después de la primera sincronización exitosa de una empresa rellena los doce meses anteriores; lo más antiguo NUNCA fue leído salvo que alguien lo haya pedido acá — un `sync.last_synced_at` en `null` en `GET /tax/sales?period=…` es cómo se nota. Para llegar más atrás, llama una vez por período; el bucket es de 10 solicitudes por minuto por empresa. **Forzar es forzar.** Una llamada mientras una sincronización del mismo período sigue en cola o corriendo se adjunta a ese job en vez de encolar otro; una llamada después de que terminó encola una lectura fresca, haya hecho lo que haya hecho la sincronización diaria esta mañana. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/sync \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"period":"2026-07"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | -------------- | ------ | --------- | ------------------------------------------------------------------ | | `period` | Period | — | Período tributario `YYYY-MM` (America/Santiago). Ej.: `"2026-07"`. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `202` | Job de sincronización aceptado. | Job | | `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 | ## `POST /tax/purchases/characterize` [#post-tax-purchases-characterize] **Caracteriza hasta 500 entradas de compra en una sola llamada** Caracteriza entradas del Registro de Compras en bloque (`entry_ids[]` más el `estado_contable`/tratamiento tributario compartido), para el caso común de dejar listo un periodo completo de una vez. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/characterize \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"entries":[{"id":"rcv_01K2RB7Q2M4X","tipo_compra":"del_giro"}]}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | -------------- | ---------------------------- | --------- | ----- | | `entries` | object + Characterization\[] | sí | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Resultados entrada por entrada. | object | | `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 | ## `POST /tax/purchases/{entry_id}/characterize` [#post-tax-purchases-entry-id-characterize] **Caracteriza una entrada de compra (escribe en el registro del SII)** Caracteriza una entrada del Registro de Compras — su `estado_contable` y si su IVA es recuperable — sobreescribiendo la propuesta del SII cuando la contabilidad propia de la empresa dice otra cosa. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/characterize \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"tipo_compra":"del_giro","iva_uso_comun":true}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entry_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | ------------------------- | -------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | | `tipo_compra` | `del_giro` · `supermercado` · `activo_fijo` · `iva_uso_comun` · `no_recuperable` | — | | | `iva_uso_comun` | boolean | — | | | `iva_no_recuperable_code` | integer,null | — | Código de motivo del SII, obligatorio cuando `tipo_compra` es `no_recuperable`. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La entrada actualizada. | RcvEntry | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | 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 /tax/purchases/{entry_id}/characterize/revert` [#post-tax-purchases-entry-id-characterize-revert] **Deshace la última caracterización asentada de una compra** Encola una caracterización NUEVA que restablece el `previous_tipo_compra` registrado en la última acción asentada de esta compra, ligada a ella por `reverts`. No edita ni borra la original: una escritura a un registro tributario que ocurrió, ocurrió, y su fila es la evidencia. Deshacer una escritura al SII es, en sí, otra escritura al SII, así que pasa por la misma puerta de opt-in y por la misma confirmación en dos tiempos. `409 characterization_nothing_to_revert` cuando no hay ninguna acción asentada, o cuando la última no registró un valor anterior. Volver a `no_recuperable` necesita un `iva_no_recuperable_code`: el SII no acepta uno sin motivo, y el motivo que usó la caracterización anterior solo es recuperable si una acción previa sobre el mismo documento lo registró. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/characterize/revert \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"iva_no_recuperable_code":1,"confirmation_id":"…"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entry_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | ------------------------- | --------------------------- | --------- | ----------------------------------------------------------------------- | | `iva_no_recuperable_code` | `1` · `2` · `3` · `4` · `9` | — | Obligatorio solo cuando el valor que se restablece es `no_recuperable`. | | `confirmation_id` | string | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `202` | La acción de reversa encolada. | CharacterizationAction | | `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 | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | 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 /tax/purchases/{entry_id}/estado_contable` [#post-tax-purchases-entry-id-estado-contable] **Mueve una entrada entre REGISTRO / PENDIENTE / NO\_INCLUIR** Registra un estado contable LOCAL para la compra. Se escribe en `estado_contable_override` y nunca sobre `estado_contable`, que pertenece al registro del propio SII y se refresca en cada sincronización. La propuesta de F29 ignora el override salvo que la empresa tenga encendida la automatización `honor_estado_contable_override`; el `estado_contable_effective` de la respuesta dice qué valor va a usar la propuesta. Cada escritura queda registrada con la llave que la hizo y con el valor del SII que no reemplazó. Cambiar la caracterización de una entrada ante el SII es otro acto, con otro endpoint (`POST /tax/purchases/\{entry_id\}/characterize`). ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/purchases/rcv_01K2RB7Q2M4X/estado_contable \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"estado_contable":"REGISTRO"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entry_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | ----------------- | ----------------------------------------------------- | --------- | ----- | | `estado_contable` | `REGISTRO` · `PENDIENTE` · `NO_INCLUIR` · `RECLAMADO` | sí | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La entrada actualizada. | RcvEntry | | `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 /tax/f29/proposals` [#get-tax-f29-proposals] **Lista los períodos que tienen una propuesta calculada** UNA ADICIÓN al §12.3, que documenta solo la lectura por período. Sin esto, quien concilia un año —o un panel que dibuja doce meses— tiene que adivinar qué períodos existen y sondear uno por uno: doce peticiones, once de ellas `404`. Las filas omiten `validation` y `filing_id`: los dos son una consulta extra por propuesta, y quien recorre un año está preguntando «qué meses están calculados», que es lo que ya responde `status`. Para eso lee la propuesta individual. ```bash curl -sS https://api.facturia.cl/v1/tax/f29/proposals \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 propuestas de F29, del período más nuevo al más antiguo. | lista de F29Proposal | | `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 /tax/f29/proposals/{period}` [#get-tax-f29-proposals-period] **Propuesta de F29 calculada para un período** La calcula Facturia desde el RCV sincronizado más los parámetros de PPM y remanente de la empresa. El SII prellena su propio F29 en su portal, pero no publica una API para eso. ```bash curl -sS https://api.facturia.cl/v1/tax/f29/proposals/2026-07 \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | path | sí | Period | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La propuesta. | F29Proposal | | `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 | ## `GET /tax/f29/proposals/{period}/upload_file` [#get-tax-f29-proposals-period-upload-file] **Descarga el .txt en formato SII de esta propuesta** El `.txt` del SII listo para subir de este periodo de F29, generado desde la misma propuesta que devuelve `GET /tax/f29/proposals/\{period\}`. ```bash curl -sS https://api.facturia.cl/v1/tax/f29/proposals/2026-07/upload_file \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | path | sí | Period | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | Archivo de carga de formato fijo, listo para subir a mano si lo prefieres. | text/plain | | `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 | ## `POST /tax/f29/proposals/{period}/public_links` [#post-tax-f29-proposals-period-public-links] **Crea un enlace sin autenticación al .txt de carga de la propuesta** `upload_file_url` necesita una llave, lo que lo vuelve inservible como `resource_link` de MCP: la mayoría de los hosts MCP no pueden adjuntar el token OAuth de quien llama al resolverlo. Esto crea el mismo tipo de enlace firmado, inadivinable y con expiración que reciben los artefactos de un documento (§9.6), sirviendo exactamente los mismos bytes ISO-8859-1. `tax:read`, no `tax:write`: crear un enlace no publica nada ni cambia ninguna posición tributaria. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/f29/proposals/2026-07/public_links \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Content-Type: application/json" \ -d '{"artifacts":["upload_file"],"expires_in_days":90}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | path | sí | Period | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------------- | ---------------- | --------- | ---------------------------------------------------------------------- | | `artifacts` | `upload_file`\[] | — | Por defecto: `["upload_file"]`. | | `expires_in_days` | integer,null | — | Por defecto: `90`. | | `expires_in_seconds` | integer,null | — | Acotado entre 30 s y 365 días. Gana cuando se mandan las dos unidades. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | El enlace recién creado. Guárdalo: la mitad secreta se almacena hasheada. | PublicLinks | | `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 | | `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 | ## `DELETE /tax/f29/proposals/{period}/public_links` [#delete-tax-f29-proposals-period-public-links] **Revoca todos los enlaces públicos de esta propuesta** Revoca todos los enlaces públicos vigentes acuñados para el archivo de carga de esta propuesta de F29. ```bash curl -sS -X DELETE https://api.facturia.cl/v1/tax/f29/proposals/2026-07/public_links \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | path | sí | Period | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `204` | Revocados. Las URL existentes dejan de resolver de inmediato. | — | | `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 | ## `POST /tax/f29/proposals/{period}/recompute` [#post-tax-f29-proposals-period-recompute] **Recalcula la propuesta, con la opción de sobrescribir códigos** Reconstruye la propuesta de F29 desde los registros y las caracterizaciones anotadas desde el último cálculo. No declara nada ante el SII. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/f29/proposals/2026-07/recompute \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Content-Type: application/json" \ -d '{"overrides":[]}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `period` | path | sí | Period | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | --------- | --------- | ----- | | `overrides` | object\[] | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La propuesta recalculada. | F29Proposal | | `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 /tax/f29/filings` [#get-tax-f29-filings] **Lista las declaraciones de F29** Las declaraciones de F29 registradas para la empresa, de la más nueva a la más antigua, cada una con el periodo y la propuesta desde la que se declaró. ```bash curl -sS https://api.facturia.cl/v1/tax/f29/filings \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `limit` | query | — | integer | | | `cursor` | query | — | string | Cursor opaco tomado del `next_cursor` de una respuesta anterior. | | `period[gte]` | query | — | string | | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `200` | Una lista de declaraciones. | lista de F29Filing | | `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 | ## `POST /tax/f29/filings` [#post-tax-f29-filings] **Declara el F29 de un período (job asíncrono)** No existe webservice del SII para declarar un F29. Facturia automatiza el flujo «Upload» del SII — una sesión autenticada con certificado que sube un .txt de formato fijo — y lo modela como un job. `confirm_total_payable` debe ser igual a la cifra de la propuesta. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/f29/filings \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"period":"2026-07","confirm_total_payable":1373000}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | ----------------------- | ------- | --------- | ----------------------------------------------------------------------------- | | `period` | Period | sí | Período tributario `YYYY-MM` (America/Santiago). Ej.: `"2026-07"`. | | `proposal_id` | string | — | | | `confirm_total_payable` | integer | sí | Barrera contra declarar la cifra equivocada. Debe coincidir con la propuesta. | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `202` | Declaración aceptada y encolada. | F29Filing | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | 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 /tax/f29/filings/{filing_id}` [#get-tax-f29-filings-filing-id] **Devuelve una declaración** Una declaración de F29: el periodo, los totales declarados, y el acuse del SII si se capturó uno. ```bash curl -sS https://api.facturia.cl/v1/tax/f29/filings/f29fil_01K2RD9K3M8T \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `filing_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La declaración. | F29Filing | | `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 | ## `GET /tax/expenses` [#get-tax-expenses] **Lista los cargos en moneda extranjera ingresados** Las entradas del libro de gastos importadas desde un banco o feed contable conectado, filtrable por periodo. ```bash curl -sS https://api.facturia.cl/v1/tax/expenses \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `200` | Una lista de gastos. | lista de ExpenseCreateRequest + object | | `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 | ## `POST /tax/expenses` [#post-tax-expenses] **Ingresa un cargo que podría requerir una factura de compra tipo 46** Importa entradas al libro de gastos directamente (fuera de una sincronización de `connections`), para una fuente que la empresa todavía no tiene como feed automático. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/expenses \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"provider":"fintoc","amount_original":1050,"currency":"USD","date":"2026-07-31"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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 | | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | object | sí | | | `description` | string | — | | | `amount_original` | number | sí | | | `currency` | string | sí | Ej.: `"USD"`. | | `date` | string | sí | | | `fx_rate` | number | — | OBLIGATORIO cada vez que `currency` no es `CLP`; omitirlo devuelve `400 fx_rate_required`. Facturia nunca inventa un tipo de cambio: esa cifra fija la base en pesos de un documento tributario. | | `fx_source` | `card_rate` · `sii_observado` · `custom` | — | `card_rate` (el tipo de cambio de liquidación que aplicó tu emisor de tarjeta) es la recomendación documentada. SALVEDAD: cuál tipo de cambio es definitivamente correcto para el tipo 46 sobre servicios digitales extranjeros está en revisión con un contador y no lo zanja ningún pronunciamiento citable; el valor que envíes se guarda textual y queda visible en el documento. | | `external_id` | string | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `201` | El gasto guardado; puede aparecer una sugerencia después, de forma asíncrona. | Expense | | `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 /tax/suggestions` [#get-tax-suggestions] **Lista las sugerencias tributarias** Sugerencias de categorización que Facturia dedujo desde cartolas y gastos importados, a la espera de un `confirm` o un `dismiss`. ```bash curl -sS https://api.facturia.cl/v1/tax/suggestions \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `limit` | query | — | integer | | | `cursor` | query | — | string | Cursor opaco tomado del `next_cursor` de una respuesta anterior. | | `type` | query | — | `emit_46` · `missing_characterization` · `folios_low` · `unclaimed_credit` | | | `status` | query | — | `open` · `confirmed` · `auto_confirmed` · `dismissed` · `expired` | | | `period` | query | — | Period | Período tributario, `YYYY-MM`, America/Santiago. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `200` | Una lista de sugerencias. | lista de Suggestion | | `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 /tax/suggestions/{suggestion_id}` [#get-tax-suggestions-suggestion-id] **Devuelve una sugerencia** Una sugerencia: qué propone, y la evidencia (entradas que calzan, confirmaciones previas) desde la que se dedujo. ```bash curl -sS https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `suggestion_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La sugerencia. | Suggestion | | `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 | ## `POST /tax/suggestions/{suggestion_id}/confirm` [#post-tax-suggestions-suggestion-id-confirm] **Confirma una sugerencia (en `emit_46`, emite el documento)** Acepta una sugerencia, aplicando la categorización que propone a las entradas que nombra. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V/confirm \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Idempotency-Key: $(uuidgen)" ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `suggestion_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | | `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`. | **Respuestas** | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `201` | La sugerencia, con el documento resultante cuando se emitió uno. | object | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `422` | Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada. | 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 /tax/suggestions/{suggestion_id}/dismiss` [#post-tax-suggestions-suggestion-id-dismiss] **Descarta una sugerencia** Rechaza una sugerencia sin aplicarla. Facturia no vuelve a sugerir la misma categorización para las mismas entradas. ```bash curl -sS -X POST https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V/dismiss \ -H "Authorization: Bearer $FACTURIA_KEY" \ -H "Facturia-Empresa: $EMPRESA" \ -H "Content-Type: application/json" \ -d '{"reason":"not_digital_service","note":"…"}' ``` **Parámetros** | Parámetro | En | Requerido | Tipo | Notas | | ------------------ | ------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `suggestion_id` | path | sí | string | | | `Facturia-Empresa` | header | — | string | La empresa destino: RUT canónico (`77928532-4`) o id de empresa (`emp_…`). Obligatorio en toda llamada con alcance de empresa, salvo que la llave sea un token de empresa. Este header es el ÚNICO mecanismo: no hay parámetro `?empresa=` ni campo `empresa` en el cuerpo. Omitido donde se requiere → `400 empresa_required`; fuera de la lista blanca → `403 empresa_not_allowed`. | **Cuerpo** | Campo | Tipo | Requerido | Notas | | -------------- | ----------------------------------------------------------------------- | --------- | ----- | | `reason` | `not_digital_service` · `already_declared` · `not_applicable` · `other` | — | | | `note` | string | — | | | **Respuestas** | | | | | Código | Significado | Cuerpo | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `200` | La sugerencia descartada. | Suggestion | | `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 |