Přejít na obsah
Sursa Developers

POST/v1/finance/report

Získat souhrnný finanční report

finance_report

Vrací součty faktur nebo plateb organizace, seskupené až podle tří dimenzí (kategorie, skupina, druh činnosti dodavatele, dodavatel, odběratel, protistrana, směr, měna, měsíc, čtvrtletí, rok), s ukazateli invoiced, paid, unpaid a tax. Součty zahrnují jen dokumenty viditelné pro uživatele (kolekce a kategorie jeho datového profilu a nastavení „odpovídat jen z ověřených karet“); filtry požadavku tento rozsah zužují, ale nikdy nerozšiřují.

V režimu reporting (výchozí) se částky přepočítají na vykazovací měnu organizace kurzem ke dni dokumentu a částky bez kurzu se uvedou v conversion.unconverted. V režimu original se částky v různých měnách nesčítají a měna se stane dimenzí řádku. Je-li řádků více než limit, má truncated hodnotu true a totals přesto pokrývají všechny řádky. Vyžaduje datový profil s přístupem k finančním datům (finance.forbidden).

Report, seznamy faktur a plateb a jejich exporty jsou operace čtení, přestože používají POST: jsou dostupné v režimu „View as“ a klíčům API s rozsahem read (a stejně jako dříve i klíčům s rozsahem write).

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

  • X-View-Asstring

    Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

Parametry cookie

  • kb_view_asstring

    Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Tělo požadavku

application/json

Objekt: FinanceReportRequest

  • basisstring

    invoices: faktury, dobropisy a účtenky. payments: protokol plateb (peněžní tok). S payments je jediným ukazatelem paid a dimenze direction i součet ukazují pohyb peněz, in nebo out, zatímco převod mezi vašimi vlastními právnickými osobami je internal.

    Povolené hodnoty: invoicespayments

    Výchozí: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Výchozí hodnota je invoiced (paid pro payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Které datum určuje období a filtr from/to: datum dokladu, nebo datum platby.

    Povolené hodnoty: documentpayment

    Výchozí: "document"

  • filtersFinanceFilter
  • order_bystring

    Ukazatel nebo dimenze, podle které se řadí. Ve výchozím nastavení první ukazatel sestupně.

  • order_descboolean

    Výchozí: true

  • limitinteger

    Výchozí: 1000≥ 1, ≤ 10000

  • languagestring

    Jazyk popisků kategorií a skupin, en|ru. Výchozí hodnota je en.

Odpovědi

200Report

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: FinanceReport

  • currency_modeFinanceCurrencyModepovinné
  • currencystring

    Vykazovací měna (režim reporting).

  • rowsarray of FinanceReportRowpovinné
  • totalsarray of FinanceReportTotalpovinné

    Součty přes všechny řádky před zkrácením, jeden záznam pro každou měnu (u přehledu rozděleného podle směru pro každou měnu a směr, FinanceReportTotal.direction).

  • truncatedbooleanpovinné
  • limitintegerpovinné
  • total_rowsintegerpovinné

    Počet seskupených řádků před zkrácením.

  • conversionFinanceConversion
  • warningsarray of string

    Kódy upozornění: profile_missing – firemní údaje organizace nejsou vyplněné, proto je směr faktur ve výchozím stavu in; catalog_missing – adresář společností není načtený; fx_rate_missing – u některých částek chybí směnný kurz (conversion.unconverted); fx_rate_stale – některé kurzy jsou zastaralé; enrichment_pending – některé dokumenty se ještě zpracovávají a v součtech nejsou zahrnuty. Neznámý kód zobrazte s obecnou zprávou.

400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

503Služba, na které tento požadavek závisí, je dočasně nedostupná. Zopakujte požadavek později.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← finance · Reference API