Conectores

Las fuentes de primera parte que alimentan el libro de gastos: Fintoc y la carga de cartolas.

Base: https://api.facturia.cl/v1. Todos los endpoints de este capítulo se autentican con Authorization: Bearer salvo que se diga lo contrario, y el sobre de error es el de Errores.

Método	Ruta	Qué hace
`GET`	`/connections`	Lista las conexiones de conectores de esta empresa
`POST`	`/connections`	Crea una conexión bancaria o de tarjeta con Fintoc
`GET`	`/connections/{connection_id}`	Devuelve una conexión
`DELETE`	`/connections/{connection_id}`	Desconecta (revoca el enlace y detiene la ingesta)
`POST`	`/connections/{connection_id}/sync`	Fuerza una sincronización de movimientos (asíncrona)
`GET`	`/tax/statements`	Lista las cartolas cargadas
`POST`	`/tax/statements`	Carga una cartola (CSV/XLSX) para crear gastos

`GET /connections`

Lista las conexiones de conectores de esta empresa

curl -sS https://api.facturia.cl/v1/connections \
  -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 conexiones.	lista de Connection

`POST /connections`

Crea una conexión bancaria o de tarjeta con Fintoc

Devuelve status: pending_link con un link_url. Manda a la persona por ahí una vez; de ahí en adelante cada sincronización se queda con los movimientos en moneda extranjera, los convierte en objetos expense (source: "fintoc", fx_source: "card_rate") y deja correr el detector de tipo 46. Las credenciales quedan en Fintoc — Facturia guarda un token de enlace, nunca una clave bancaria.

curl -sS -X POST https://api.facturia.cl/v1/connections \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"provider":"fintoc"}'

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`	`fintoc`	sí
`account_types`	`checking` · `credit_card`[]	—
`sync_frequency`	`daily` · `weekly` · `manual`	—	Por defecto: `"daily"`.
Respuestas

Código	Significado	Cuerpo
`201`	La conexión, a la espera del flujo de enlace.	Connection
`400`	Entrada mal formada o incompleta.	ErrorResponse

`GET /connections/{connection_id}`

Devuelve una conexión

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

Parámetros

Parámetro	En	Requerido	Tipo	Notas
`connection_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 conexión.	Connection
`404`	No existe ese objeto bajo esta llave.	ErrorResponse

`DELETE /connections/{connection_id}`

Desconecta (revoca el enlace y detiene la ingesta)

Los gastos ya creados desde esta conexión se conservan.

curl -sS -X DELETE https://api.facturia.cl/v1/connections/con_01K2RJ7B2W4M \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA"

Parámetros

Parámetro	En	Requerido	Tipo	Notas
`connection_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
`204`	Desconectada.	—

`POST /connections/{connection_id}/sync`

Fuerza una sincronización de movimientos (asíncrona)

curl -sS -X POST https://api.facturia.cl/v1/connections/con_01K2RJ7B2W4M/sync \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)"

Parámetros

Parámetro	En	Requerido	Tipo	Notas
`connection_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
`202`	Job de sincronización aceptado.	Job
`422`	Bien formado pero viola una regla del dominio: folios agotados, ventana de acuse cerrada.	ErrorResponse

`GET /tax/statements`

Lista las cartolas cargadas

curl -sS https://api.facturia.cl/v1/tax/statements \
  -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 importaciones de cartola.	lista de Statement

`POST /tax/statements`

Carga una cartola (CSV/XLSX) para crear gastos

Asíncrono. El result del job devuelve rows_read, expenses_created, duplicates_skipped y un errors[] por fila. La deduplicación es por (empresa, fecha, amount_original, currency, provider) más tu external_id cuando existe, así que volver a subir una cartola que se traslapa es seguro.

curl -sS -X POST https://api.facturia.cl/v1/tax/statements \
  -H "Authorization: Bearer $FACTURIA_KEY" \
  -H "Facturia-Empresa: $EMPRESA" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=…" \
  -F "format=…"

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 (multipart/form-data)

Campo	Tipo	Requerido	Notas
`file`	string	sí
`format`	`auto` · `generic_csv` · `santander` · `bci` · `banco_chile` · `itau` · `scotiabank` · `xlsx`	—	Por defecto: `"auto"`.
`default_currency`	string	—	Se aplica a las filas sin columna de moneda.
Respuestas

Código	Significado	Cuerpo
`202`	Job de importación aceptado.	Job
`400`	Entrada mal formada o incompleta.	ErrorResponse

GET /connections

POST /connections

GET /connections/{connection_id}

DELETE /connections/{connection_id}

POST /connections/{connection_id}/sync

GET /tax/statements

POST /tax/statements

En esta página

`GET /connections`

`POST /connections`

`GET /connections/{connection_id}`

`DELETE /connections/{connection_id}`

`POST /connections/{connection_id}/sync`

`GET /tax/statements`

`POST /tax/statements`