Перейти до вмісту
Sursa Developers

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

Параметри cookie

  • kb_view_asstring

    Cookie режиму «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Облікові дані не надіслано (ні cookie сесії, ні ключа 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