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.

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.

curl -sS https://api.facturia.cl/v1/tax/purchases \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

GET /tax/sales

RCV — registro de ventas

El Registro de Ventas sincronizado desde el SII, filtrable por periodo.

curl -sS https://api.facturia.cl/v1/tax/sales \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

curl -sS https://api.facturia.cl/v1/tax/summary \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

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

Cuerpo

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.

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

Cuerpo

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.

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

Cuerpo

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ó.

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

Cuerpo

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).

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

Cuerpo

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.

curl -sS https://api.facturia.cl/v1/tax/f29/proposals \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

curl -sS https://api.facturia.cl/v1/tax/f29/proposals/2026-07 \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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\}.

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

Respuestas

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.

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

Cuerpo

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.

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

Respuestas

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.

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

Cuerpo

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ó.

curl -sS https://api.facturia.cl/v1/tax/f29/filings \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

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

Cuerpo

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.

curl -sS https://api.facturia.cl/v1/tax/f29/filings/f29fil_01K2RD9K3M8T \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

curl -sS https://api.facturia.cl/v1/tax/expenses \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

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

Cuerpo

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.

curl -sS https://api.facturia.cl/v1/tax/suggestions \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

curl -sS https://api.facturia.cl/v1/tax/suggestions/sug_01K2RE2X7Q9V \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Respuestas

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.

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

Respuestas

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.

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

Cuerpo