POST/v1/finance/report

Get a financial summary report

finance_report

Returns the totals of the organization's invoices or payments, grouped by up to three dimensions (category, group, supplier's type of business, supplier, buyer, counterparty, direction, currency, month, quarter, year), with the measures invoiced, paid, unpaid and tax. Totals include only documents visible to the user (the collections and categories of their data profile, and the “answer only from verified cards” setting); request filters narrow this scope but never widen it.

In reporting mode (the default), amounts are converted to the organization's reporting currency at the rate on the document date, and amounts without a rate are listed in conversion.unconverted. In original mode, amounts in different currencies are not added up, and the currency becomes a dimension of the row. If there are more rows than limit, truncated is true, and totals still cover all rows. Requires a data profile with access to financial data (finance.forbidden).

The report, the invoice and payment lists and their exports are read operations even though they use POST: they are available in “View as” mode and to API keys with the read scope (and, as before, to keys with the write scope).

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Header parameters

X-View-Asstring
For API keys with the admin role only. Makes the request as the data profile <profile>[:viewer|verifier|editor], for example employee:viewer. The installation key cannot use this header (403).

Cookie parameters

kb_view_asstring
Cookie of the “View as” mode for a session. POST /auth/view-as sets it and DELETE /auth/view-as clears it.

Request body

application/json

Object: FinanceReportRequest

basisstring
invoices: invoices, credit notes and receipts. payments: the payment log (cash flow). With payments, the only measure is paid, and the direction dimension and total show money movement, in or out, while a transfer between your own legal entities is internal.
Allowed values: invoicespayments
Default: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Defaults to invoiced (paid for payments).
currency_modeFinanceCurrencyMode
date_basisstring
Which date sets the period and the from/to filter: the document date or the payment date.
Allowed values: documentpayment
Default: "document"
filtersFinanceFilter
order_bystring
Measure or dimension to sort by. By default, the first measure in descending order.
order_descboolean
Default: true
limitinteger
Default: 1000≥ 1, ≤ 10000
languagestring
Language of category and group labels, en|ru. Defaults to en.

Responses

200The report

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: FinanceReport

currency_modeFinanceCurrencyModerequired
currencystring
Reporting currency (reporting mode).
rowsarray of FinanceReportRowrequired
totalsarray of FinanceReportTotalrequired
Totals over all rows before truncation, one record per currency (for a report split by direction, per currency and direction, FinanceReportTotal.direction).
truncatedbooleanrequired
limitintegerrequired
total_rowsintegerrequired
Number of grouped rows before truncation.
conversionFinanceConversion
warningsarray of string
Warning codes: profile_missing, the organization's company details are not set, so invoice direction defaults to in; catalog_missing, the company directory is not loaded; fx_rate_missing, some amounts have no exchange rate (conversion.unconverted); fx_rate_stale, some rates are outdated; enrichment_pending, some documents are still being processed and are not included in the totals. Show an unknown code with a generic message.

400The request is invalid: a parameter value or the state of the object does not allow the action (`detail` is a message).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

Retry-After
Number of seconds to wait before you retry the request.
RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

503A service that this request depends on is temporarily unavailable. Retry later.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Safe retries

Send an Idempotency-Key header (for example a UUID) with each POST and PATCH. A retry with the same key within 24 hours returns the saved response instead of running the request again.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← finance · API reference

curl -X POST 'https://api.sursa.com/v1/finance/report' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"basis":"invoices","group_by":["category"],"measures":["invoiced"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Try it

API key

The key stays in the memory of this tab and is sent only to https://api.sursa.com.

Requests act on the real data of your organization.

X-View-As header

Idempotency-Key

A new key is generated for each request when this is empty.

Request body (JSON)