Connectors

Base: https://api.facturia.cl/v1. Every endpoint in this chapter authenticates with Authorization: Bearer unless stated otherwise, and the error envelope is the one in Errors.

GET /connections

List connector connections for this empresa

Connectors (bank feeds, accounting integrations) linked to the empresa, with each one's last sync and status.

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

Parameters

Responses

POST /connections

Create a Fintoc bank/card connection

Returns status: pending_link with a link_url. Send the user through it once; from then on each sync keeps the foreign-currency movements, converts them into expense objects (source: "fintoc", fx_source: "card_rate") and lets the tipo-46 detector run. Credentials stay with Fintoc — Facturia stores a link token, never a bank password. connection.linked fires when the link completes.

IN TEST MODE there is no link to complete, so the connection is born active, link_url is null and connection.linked fires with the 201 — §4.1's "complete in-process simulation", and the only way the connector surface is exercisable before a real bank is involved.

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"}'

Parameters

Body

GET /connections/{connection_id}

Retrieve a connection

One connector's configuration and sync history, without its stored credentials.

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

Parameters

Responses

DELETE /connections/{connection_id}

Disconnect (revokes the link, stops ingestion)

Expenses already created from this connection are kept.

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

Parameters

Responses

POST /connections/{connection_id}/sync

Force a movement sync (async)

422 connection_not_linked on a connection that is not active: tax_bank_sync only looks at linked rows, so queueing one would be a job that runs, does nothing, and reports succeeded.

In TEST MODE the job comes back already succeeded — there is no bank to call and no worker to wait for, so a queued job would never move (§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)"

Parameters

Responses

GET /tax/statements

List uploaded cartolas

Bank or card statements imported for the empresa, the raw material tax:write imports feed into the expense ledger and its suggestions.

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

Parameters

Responses

POST /tax/statements

Upload a cartola (CSV/XLSX) to create expenses

Asynchronous. The returned job's result carries rows_read, expenses_created, duplicates_skipped and per-row errors[]. Deduplication is by (empresa, date, amount_original, currency, provider) plus external_id where present, so re-uploading an overlapping cartola is safe.

202 when this upload created the import; 200 with the ORIGINAL job when the exact same BYTES were uploaded before for this empresa (a sha256 taken before anything touches storage) — no second storage object, no second parse. Same body either way.

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=…"

Parameters

Body (multipart/form-data)