PT EN

Extractos bancários

URL base: $BUSINESS_API

Listar extractos bancários

Registos

GET /bank-statements

Returns the tenant's imported bank statements, newest first, with cursor pagination (limit defaults to 20, at most 100). Each statement carries its bank account reference, statement reference and date, currency and line count. Requires payments:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Importar um extracto bancário

Registos

POST /bank-statements

Import a bank statement (lines or csv) and match credits to payments

Stores a statement with its lines, given either as a lines array or as CSV text (columns value_date as YYYY-MM-DD, amount, then optional reference and description; a value_date header row is skipped). bank_account_ref, statement_reference, statement_date and at least one line are required, and amounts are read in the tenant's currency. Each credit line is then matched to a posted payment of the same amount, first by reference or receipt number, then by amount alone when exactly one bank transfer falls within three days; matched payments become reconciled and everything else waits in the unmatched queue. Records a bank_statement.imported event and returns 201 with the statement and its lines.

Corpo application/json

bank_account_refstring · opcional
statement_referencestring · opcional
statement_datestring · opcional
csvstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "bank_account_ref": "bank account ref",
  "statement_reference": "STA-2026-000142",
  "statement_date": "2026-11-19",
  "csv": "csv"
}'
Resposta 200

Success

Listar linhas bancárias por conciliar

Registos

GET /bank-statements/unmatched-lines

Returns the lines of every statement of the tenant that are still unmatched, across all imports, with cursor pagination (limit defaults to 20, at most 100). This is the review queue for credits that could not be matched automatically and for debits, which are never auto-matched. Requires payments:read.

Parâmetros

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/unmatched-lines" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Obter um extracto bancário

Registos

GET /bank-statements/{id}

Returns one imported statement with its bank account reference, statement reference and date, currency, line count and status. Lines are listed separately. Answers 404 when the statement is not in the caller's tenant.

Parâmetros

idstring · caminho · obrigatório

Identifier of the bank statement (prefix stm_).

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Listar linhas de um extracto

Registos

GET /bank-statements/{id}/lines

Returns the lines of one statement in import order with cursor pagination (limit defaults to 20, at most 100). Pass status (unmatched, matched or ignored) to see only lines in that review state. Each line shows its amount, value date, reference and, when matched, the payment and who matched it.

Parâmetros

idstring · caminho · obrigatório

Identifier of the bank statement whose lines to list (prefix stm_).

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/bank-statements/{id}/lines" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Conciliar uma linha com um pagamento

Registos

POST /bank-statements/lines/{id}/match

Links an unmatched line to the payment named in the body, moves that payment from posted to reconciled and records who matched it, with an optional note. The line must be unmatched and the payment posted (409 otherwise), and the amounts must be equal (400 otherwise). Returns the updated line.

Parâmetros

idstring · caminho · obrigatório

Identifier of the unmatched statement line to match (prefix sln_).

Corpo application/json

payment_idstring · opcional
notestring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/match" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "payment_id": "pay_2eUBfC8BJA6JLIoHrQwtN0GL1mW",
  "note": "Leitura confirmada no local."
}'
Resposta 200

Success

Desfazer a conciliação de uma linha

Registos

POST /bank-statements/lines/{id}/unmatch

Returns a matched line to the unmatched queue and moves its payment from reconciled back to posted, clearing who matched it. An optional note query parameter is stored as the review note. A line that is not matched answers 409.

Parâmetros

idstring · caminho · obrigatório

Identifier of the matched statement line to unmatch (prefix sln_).

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/unmatch" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Ignorar uma linha bancária

Registos

POST /bank-statements/lines/{id}/ignore

Marks an unmatched line as ignored, for money that needs no payment such as a bank fee or an internal transfer, and stores the required note. Only an unmatched line can be ignored (409 otherwise), and an empty note answers 400. Returns the updated line.

Parâmetros

idstring · caminho · obrigatório

Identifier of the statement line to ignore (prefix sln_).

Corpo application/json

notestring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/ignore" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Leitura confirmada no local."
}'
Resposta 200

Success

Registar um pagamento a partir de uma linha

Registos

POST /bank-statements/lines/{id}/create-payment

Records a bank transfer payment on the account in the body for the line's amount, dated at the line's value date and referenced with the line's reference (or BANK-<line id> when empty), allocates it to the account's open invoices, reconciles it and matches the line. Only an unmatched credit line qualifies; anything else answers 409. The payment uses an idempotency key derived from the line, so a repeated call does not book a second payment. Returns 201 with the updated line.

Parâmetros

idstring · caminho · obrigatório

Identifier of the unmatched credit statement line (prefix sln_).

Corpo application/json

account_idstring · opcional
notestring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões payments:write · Funções: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/bank-statements/lines/{id}/create-payment" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "note": "Leitura confirmada no local."
}'
Resposta 200

Success