POST/v1/finance/report

Получаване на обобщен финансов отчет

finance_report

Връща общите суми на фактурите или плащанията на организацията, групирани по до три измерения (категория, група, вид дейност на доставчика, доставчик, купувач, контрагент, посока, валута, месец, тримесечие, година), с показателите invoiced, paid, unpaid и tax. Общите суми включват само документите, видими за потребителя (колекциите и категориите от профила му за достъп и настройката „отговаряй само от проверени карти“); филтрите в заявката стесняват този обхват, но никога не го разширяват.

В режим reporting (по подразбиране) сумите се преизчисляват в отчетната валута на организацията по курса към датата на документа, а сумите без курс се изброяват в conversion.unconverted. В режим original сумите в различни валути не се събират и валутата става измерение на реда. Ако редовете са повече от limit, truncated е true, а totals пак обхващат всички редове. Изисква профил за достъп с достъп до финансови данни (finance.forbidden).

Отчетът, списъците с фактури и плащания и експортите им са операции за четене, въпреки че използват POST: те са достъпни в режим „View as“ и за API ключове с обхвата read (и, както преди, за ключове с обхвата write).

Удостоверяване

Изпратете API ключ в заглавката Authorization: Authorization: Bearer <ключ>.

Параметри в заглавката

X-View-Asstring
Само за API ключове с ролята admin. Изпълнява заявката от името на профила за достъп <profile>[:viewer|verifier|editor], например employee:viewer. Ключът на инсталацията не може да използва тази заглавка (403).

Параметри в бисквитка

kb_view_asstring
Бисквитка на режима „View as“ за сесия. POST /auth/view-as я задава, а DELETE /auth/view-as я изчиства.

Тяло на заявката

application/json

Обект: FinanceReportRequest

basisstring
invoices: фактури, кредитни известия и касови бележки. payments: дневникът на плащанията (паричен поток). При payments единственият показател е paid, а измерението direction и общата сума показват движението на парите, in или out, като превод между собствените ви юридически лица е internal.
Допустими стойности: invoicespayments
По подразбиране: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
По подразбиране invoiced (paid за payments).
currency_modeFinanceCurrencyMode
date_basisstring
Коя дата задава периода и филтъра from/to: датата на документа или датата на плащането.
Допустими стойности: documentpayment
По подразбиране: "document"
filtersFinanceFilter
order_bystring
Показател или измерение за сортиране. По подразбиране – първият показател в низходящ ред.
order_descboolean
По подразбиране: true
limitinteger
По подразбиране: 1000≥ 1, ≤ 10000
languagestring
Език на наименованията на категориите и групите, en|ru. По подразбиране en.

Отговори

200Отчетът

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: FinanceReport

currency_modeFinanceCurrencyModeзадължително
currencystring
Отчетна валута (режим reporting).
rowsarray of FinanceReportRowзадължително
totalsarray of FinanceReportTotalзадължително
Общи суми по всички редове преди отрязването, по един запис за всяка валута (при отчет, разделен по посока – за всяка валута и посока, FinanceReportTotal.direction).
truncatedbooleanзадължително
limitintegerзадължително
total_rowsintegerзадължително
Брой на групираните редове преди отрязването.
conversionFinanceConversion
warningsarray of string
Кодове на предупреждения: profile_missing – данните за фирмата на организацията не са зададени, затова посоката на фактурите по подразбиране е in; catalog_missing – справочникът на фирмите не е зареден; fx_rate_missing – за някои суми няма валутен курс (conversion.unconverted); fx_rate_stale – някои курсове са остарели; enrichment_pending – някои документи още се обработват и не са включени в общите суми. Показвайте непознат код с общо съобщение.

400Заявката е невалидна: стойност на параметър или състоянието на обекта не позволява действието (`detail` е съобщение).

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

401Не са изпратени идентификационни данни (нито бисквитка на сесията, нито API ключ) или ключът не е намерен.

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

403Действието не е разрешено: ролята е недостатъчна, няма достъп до колекцията или картата, заявката се изпълнява в режим „View as“ или организацията е спряна или изтрита (`detail` е обект с `code: org_suspended | org_deleted`).

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

429Твърде много заявки (`api.rate_limited`), квотата на организацията за минутата, деня или месеца е изчерпана (`api.quota_exceeded`; `error.details` съдържа `quota`, `limit` и `reset_at`), достигнат е лимит на организацията или услугата за отговори е заета (`answers.engine_busy`). Изчакайте времето от заглавката `Retry-After`.

Заглавки на отговора

Retry-After
Брой секунди, които да изчакате, преди да повторите заявката.
RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

503Услуга, от която зависи тази заявка, временно не е достъпна. Опитайте отново по-късно.

Заглавки на отговора

RateLimit-Policy
Действащите лимити във формата на черновата на IETF draft-ietf-httpapi-ratelimit-headers: разделени със запетая елементи "<name>";q=<quota>;w=<window in seconds>. key е честотата на заявките на API ключа (квотата е пиковото натоварване, прозорецът е времето за пълното ѝ възстановяване; за сесия е user, без идентификационни данни – ip); minute, day и month са квотите на организацията за календарната минута, ден и месец по UTC.
RateLimit
Какво остава от всеки лимит в RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимитът на най-строгия запис в RateLimit-Policy (този с най-малко оставащи заявки).
X-RateLimit-Remaining
Оставащи заявки по най-строгия лимит.
X-RateLimit-Reset
Секунди до нулирането на най-строгия лимит.

application/json

Обект: Error

Кодове на грешки

Кодове, които тази операция може да върне в error.code, освен общите кодове на всяка заявка.

Безопасни повторни опити

Изпращайте заглавката Idempotency-Key (например UUID) с всяка заявка POST и PATCH. Повторен опит със същия ключ в рамките на 24 часа връща запазения отговор, вместо да изпълни заявката отново.

Лимити на честотата

Отговорите съдържат заглавките RateLimit и RateLimit-Policy, както и по-ранните X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Отговорът 429 съдържа Retry-After в секунди: изчакайте и опитайте отново.

← finance · Справочник на API

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"

Изпробвайте

API ключ

Ключът остава само в паметта на този раздел на браузъра и се изпраща единствено до https://api.sursa.com.

Заявките работят с реалните данни на организацията ви.

X-View-As header

Idempotency-Key

Ако полето е празно, за всяка заявка се генерира нов ключ.

Тяло на заявката (JSON)