Przejdź do treści
Sursa Developers

POST/v1/finance/report

Pobieranie raportu zbiorczego finansów

finance_report

Zwraca sumy faktur lub płatności organizacji pogrupowane według maksymalnie trzech wymiarów (kategoria, grupa, rodzaj działalności dostawcy, dostawca, nabywca, kontrahent, kierunek, waluta, miesiąc, kwartał, rok), z miarami invoiced, paid, unpaid i tax. Sumy obejmują tylko dokumenty widoczne dla użytkownika (kolekcje i kategorie jego profilu dostępu oraz ustawienie „odpowiadaj tylko na podstawie zweryfikowanych kart”); filtry żądania zawężają ten obszar, ale nigdy go nie poszerzają.

W trybie reporting (domyślnie) kwoty są przeliczane na walutę sprawozdawczą organizacji po kursie z daty dokumentu, a kwoty bez kursu są wymieniane w conversion.unconverted. W trybie original kwoty w różnych walutach nie są sumowane, a waluta staje się wymiarem wiersza. Jeśli wierszy jest więcej niż limit, truncated ma wartość true, a totals nadal obejmują wszystkie wiersze. Wymaga profilu dostępu z dostępem do danych finansowych (finance.forbidden).

Raport, listy faktur i płatności oraz ich eksporty są operacjami odczytu, mimo że używają POST: są dostępne w trybie „View as” i dla kluczy API z zakresem read (oraz, jak dotychczas, dla kluczy z zakresem write).

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry nagłówka

  • X-View-Asstring

    Tylko dla kluczy API z rolą admin. Wykonuje żądanie jako profil dostępu <profile>[:viewer|verifier|editor], np. employee:viewer. Klucz instalacji nie może używać tego nagłówka (403).

Parametry cookie

  • kb_view_asstring

    Plik cookie trybu „View as” dla sesji. POST /auth/view-as go ustawia, a DELETE /auth/view-as usuwa.

Treść żądania

application/json

Obiekt: FinanceReportRequest

  • basisstring

    invoices: faktury, faktury korygujące i paragony. payments: dziennik płatności (przepływy pieniężne). Przy payments jedyną miarą jest paid, a wymiar direction i suma pokazują przepływ pieniędzy, in lub out, natomiast przelew między Twoimi własnymi podmiotami to internal.

    Dozwolone wartości: invoicespayments

    Domyślnie: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Domyślnie invoiced (paid dla payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Która data wyznacza okres i filtr from/to: data dokumentu czy data płatności.

    Dozwolone wartości: documentpayment

    Domyślnie: "document"

  • filtersFinanceFilter
  • order_bystring

    Miara lub wymiar, według których odbywa się sortowanie. Domyślnie pierwsza miara w kolejności malejącej.

  • order_descboolean

    Domyślnie: true

  • limitinteger

    Domyślnie: 1000≥ 1, ≤ 10000

  • languagestring

    Język etykiet kategorii i grup, en|ru. Domyślnie en.

Odpowiedzi

200Raport

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: FinanceReport

  • currency_modeFinanceCurrencyModewymagane
  • currencystring

    Waluta sprawozdawcza (tryb reporting).

  • rowsarray of FinanceReportRowwymagane
  • totalsarray of FinanceReportTotalwymagane

    Sumy ze wszystkich wierszy przed obcięciem, jeden wpis na walutę (w raporcie podzielonym według kierunku – na walutę i kierunek, FinanceReportTotal.direction).

  • truncatedbooleanwymagane
  • limitintegerwymagane
  • total_rowsintegerwymagane

    Liczba zgrupowanych wierszy przed obcięciem.

  • conversionFinanceConversion
  • warningsarray of string

    Kody ostrzeżeń: profile_missing – dane firmy organizacji nie są uzupełnione, więc kierunek faktury domyślnie to in; catalog_missing – katalog firm nie jest załadowany; fx_rate_missing – dla części kwot brak kursu walut (conversion.unconverted); fx_rate_stale – część kursów jest nieaktualna; enrichment_pending – część dokumentów jest jeszcze przetwarzana i nie wchodzi do sum. Nieznany kod wyświetlaj z ogólnym komunikatem.

400Żądanie jest nieprawidłowe: wartość parametru lub stan obiektu nie pozwala na to działanie (`detail` zawiera komunikat).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

  • Retry-After

    Liczba sekund oczekiwania przed ponowieniem żądania.

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

503Usługa, od której zależy to żądanie, jest tymczasowo niedostępna. Ponów żądanie później.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← finance · Dokumentacja API