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.

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.

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

Parámetros

Respuestas

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.

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

Cuerpo

GET /connections/{connection_id}

Devuelve una conexión

La configuración y el historial de sincronización de un conector, sin sus credenciales guardadas.

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

Parámetros

Respuestas

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

Respuestas

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

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

Respuestas

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.

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

Parámetros

Respuestas

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.

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

Cuerpo (multipart/form-data)