# Conectores (/docs/referencia/conectores) 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` | [`/connections`](#get-connections) | Lista las conexiones de conectores de esta empresa | | `POST` | [`/connections`](#post-connections) | Crea una conexión bancaria o de tarjeta con Fintoc | | `GET` | [`/connections/{connection_id}`](#get-connections-connection-id) | Devuelve una conexión | | `DELETE` | [`/connections/{connection_id}`](#delete-connections-connection-id) | Desconecta (revoca el enlace y detiene la ingesta) | | `POST` | [`/connections/{connection_id}/sync`](#post-connections-connection-id-sync) | Fuerza una sincronización de movimientos (asíncrona) | | `GET` | [`/tax/statements`](#get-tax-statements) | Lista las cartolas cargadas | | `POST` | [`/tax/statements`](#post-tax-statements) | Carga una cartola (CSV/XLSX) para crear gastos | ## `GET /connections` [#get-connections] **Lista las conexiones de conectores de esta empresa** Los conectores (feeds bancarios, integraciones contables) enlazados a la empresa, con la última sincronización y el estado de cada uno. ```bash 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 | | `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 /connections` [#post-connections] **Crea una conexión bancaria o de tarjeta con Fintoc** Devuelve `status: pending_link` con un `link_url`. Manda al usuario 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 se quedan en Fintoc — Facturia guarda un token de vínculo, nunca una clave bancaria. `connection.linked` dispara cuando el vínculo se completa. EN MODO DE PRUEBA no hay vínculo que completar, así que la conexión nace `active`, `link_url` es `null` y `connection.linked` dispara junto con el `201` — la «simulación completa en proceso» de la §4.1, y la única forma de ejercitar la superficie de conectores antes de que haya un banco de por medio. ```bash 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 | | `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 /connections/{connection_id}` [#get-connections-connection-id] **Devuelve una conexión** La configuración y el historial de sincronización de un conector, sin sus credenciales guardadas. ```bash 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 | | `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 | ## `DELETE /connections/{connection_id}` [#delete-connections-connection-id] **Desconecta (revoca el enlace y detiene la ingesta)** Los gastos ya creados desde esta conexión se conservan. ```bash 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. | — | | `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 /connections/{connection_id}/sync` [#post-connections-connection-id-sync] **Fuerza una sincronización de movimientos (asíncrona)** `422 connection_not_linked` en una conexión que no está `active`: `tax_bank_sync` solo mira filas vinculadas, así que encolar una sería un job que corre, no hace nada y reporta `succeeded`. En MODO DE PRUEBA el job vuelve ya `succeeded` — no hay banco al que llamar ni worker que esperar, así que un job `queued` nunca se movería (§4.1). ```bash 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 — `queued` en modo real, ya `succeeded` en prueba. | Job | | `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/statements` [#get-tax-statements] **Lista las cartolas cargadas** Las cartolas bancarias o de tarjeta importadas para la empresa, la materia prima que las importaciones con `tax:write` alimentan hacia el libro de gastos y sus sugerencias. ```bash 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 | | `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/statements` [#post-tax-statements] **Carga una cartola (CSV/XLSX) para crear gastos** Asíncrono. El `result` del job devuelto trae `rows_read`, `expenses_created`, `duplicates_skipped` y los `errors[]` por fila. La deduplicación es por (empresa, fecha, amount\_original, currency, provider) más `external_id` cuando viene, así que volver a subir una cartola que se traslapa es seguro. `202` cuando esta subida creó la importación; `200` con el job ORIGINAL cuando ya se subieron exactamente los mismos BYTES para esta empresa (un `sha256` tomado antes de que nada toque el almacenamiento): sin un segundo objeto guardado y sin un segundo parseo. El cuerpo es el mismo en los dos casos. ```bash 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 | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `200` | Estos bytes exactos ya se habían subido. El job de importación ORIGINAL. | StatementImportJob | | `202` | Job de importación aceptado. | StatementImportJob | | `400` | Entrada mal formada o incompleta. | ErrorResponse | | `401` | Llave ausente, mal formada o revocada. | ErrorResponse | | `403` | Llave válida pero sin permiso: scope, lista blanca de empresas o modo. | ErrorResponse | | `429` | Demasiadas solicitudes. | ErrorResponse | | `default` | Un error no enumerado aparte para esta operación, en el mismo sobre §5.5 que cualquier otro rechazo. Ramifica por `error.code`, nunca solo por el estado HTTP ni por `error.message` — un código que esta operación aún no se ha visto lanzar sigue siendo más seguro para decidir que un texto pensado para una persona. | ErrorResponse |