Перейти к содержанию
Sursa для разработчиков

POST/v1/finance/report

Получить сводный финансовый отчёт

finance_report

Возвращает итоги по счетам или платежам организации, сгруппированные по трём измерениям максимум (категория, группа, вид деятельности поставщика, поставщик, покупатель, контрагент, направление, валюта, месяц, квартал, год), с показателями invoiced, paid, unpaid и tax. В итоги входят только документы, видимые пользователю (коллекции и категории его профиля доступа и настройка «отвечать только по подтверждённым карточкам»); фильтры запроса сужают эту область, но никогда не расширяют.

В режиме reporting (по умолчанию) суммы пересчитываются в отчётную валюту организации по курсу на дату документа, а суммы без курса перечисляются в conversion.unconverted. В режиме original суммы в разных валютах не складываются, а валюта становится измерением строки. Если строк больше, чем limit, truncated равно true, а totals всё равно охватывают все строки. Нужен профиль доступа с доступом к финансовым данным (finance.forbidden).

Отчёт, списки счетов и платежей и их выгрузки — операции чтения, хотя и используют POST: они доступны в режиме «Смотреть как» и ключам API с областью read (и, как раньше, ключам с областью write).

Аутентификация

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры заголовков

  • X-View-Asstring

    Только для ключей API с ролью admin. Выполняет запрос от имени профиля доступа <profile>[:viewer|verifier|editor], например employee:viewer. Ключ установки этот заголовок использовать не может (403).

Параметры cookie

  • kb_view_asstring

    Cookie режима «Смотреть как» для сессии. 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Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`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