Preskočiť na obsah
Sursa Developers

POST/v1/finance/report

Získať súhrnný finančný report

finance_report

Vráti súčty faktúr alebo platieb organizácie zoskupené podľa najviac troch dimenzií (kategória, skupina, druh činnosti dodávateľa, dodávateľ, odberateľ, protistrana, smer, mena, mesiac, štvrťrok, rok), s ukazovateľmi invoiced, paid, unpaid a tax. Súčty zahŕňajú len doklady viditeľné pre používateľa (kolekcie a kategórie jeho dátového profilu a nastavenie „odpovedať len z overených kariet“); filtre požiadavky tento rozsah zužujú, nikdy ho nerozširujú.

V režime reporting (predvolený) sa sumy prepočítajú na vykazovaciu menu organizácie kurzom k dátumu dokladu a sumy bez kurzu sa uvedú v conversion.unconverted. V režime original sa sumy v rôznych menách nesčítavajú a mena sa stane dimenziou riadka. Ak je riadkov viac ako limit, truncated je true a totals aj tak pokrývajú všetky riadky. Vyžaduje dátový profil s prístupom k finančným údajom (finance.forbidden).

Report, zoznamy faktúr a platieb a ich exporty sú operácie čítania, hoci používajú POST: sú dostupné v režime „View as“ a kľúčom API s rozsahom read (a ako doteraz aj kľúčom s rozsahom write).

Autentifikácia

Odošlite kľúč API v hlavičke Authorization: Authorization: Bearer <kľúč>.

Parametre hlavičky

  • X-View-Asstring

    Len pre kľúče API s rolou admin. Vykoná požiadavku v mene dátového profilu <profile>[:viewer|verifier|editor], napríklad employee:viewer. Inštalačný kľúč túto hlavičku použiť nemôže (403).

Parametre cookie

  • kb_view_asstring

    Súbor cookie režimu „View as“ pre reláciu. POST /auth/view-as ho nastaví a DELETE /auth/view-as ho odstráni.

Telo požiadavky

application/json

Objekt: FinanceReportRequest

  • basisstring

    invoices: faktúry, dobropisy a pokladničné doklady. payments: zoznam platieb (peňažný tok). Pri payments je jediným ukazovateľom paid a dimenzia direction aj súčet ukazujú pohyb peňazí, in alebo out, pričom prevod medzi vašimi vlastnými právnickými osobami je internal.

    Povolené hodnoty: invoicespayments

    Predvolené: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Predvolene invoiced (paid pri payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Ktorý dátum určuje obdobie a filter from/to: dátum dokladu alebo dátum platby.

    Povolené hodnoty: documentpayment

    Predvolené: "document"

  • filtersFinanceFilter
  • order_bystring

    Ukazovateľ alebo dimenzia, podľa ktorej sa triedi. Predvolene prvý ukazovateľ v zostupnom poradí.

  • order_descboolean

    Predvolené: true

  • limitinteger

    Predvolené: 1000≥ 1, ≤ 10000

  • languagestring

    Jazyk názvov kategórií a skupín, en|ru. Predvolene en.

Odpovede

200Report

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: FinanceReport

  • currency_modeFinanceCurrencyModepovinné
  • currencystring

    Vykazovacia mena (režim reporting).

  • rowsarray of FinanceReportRowpovinné
  • totalsarray of FinanceReportTotalpovinné

    Súčty za všetky riadky pred skrátením, jeden záznam za každú menu (pri prehľade rozdelenom podľa smeru za každú menu a smer, FinanceReportTotal.direction).

  • truncatedbooleanpovinné
  • limitintegerpovinné
  • total_rowsintegerpovinné

    Počet zoskupených riadkov pred skrátením.

  • conversionFinanceConversion
  • warningsarray of string

    Kódy upozornení: profile_missing – firemné údaje organizácie nie sú vyplnené, preto je smer faktúr predvolene in; catalog_missing – adresár firiem nie je načítaný; fx_rate_missing – pre niektoré sumy chýba výmenný kurz (conversion.unconverted); fx_rate_stale – niektoré kurzy sú zastarané; enrichment_pending – niektoré doklady sa ešte spracúvajú a nie sú zahrnuté v súčtoch. Neznámy kód zobrazte so všeobecnou správou.

400Požiadavka je neplatná: hodnota parametra alebo stav objektu akciu nedovoľuje (`detail` je správa).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

401Neboli odoslané žiadne prihlasovacie údaje (ani cookie relácie, ani kľúč API) alebo sa kľúč nenašiel.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

403Akcia nie je povolená: rola nestačí, chýba prístup ku kolekcii alebo karte, požiadavka beží v režime „View as“ alebo je organizácia pozastavená či odstránená (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

429Príliš veľa požiadaviek (`api.rate_limited`), vyčerpaná kvóta organizácie na minútu, deň alebo mesiac (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), dosiahnutý limit organizácie alebo zaneprázdnená služba odpovedí (`answers.engine_busy`). Počkajte čas uvedený v hlavičke `Retry-After`.

Hlavičky odpovede

  • Retry-After

    Počet sekúnd, ktoré treba počkať pred opakovaním požiadavky.

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

503Služba, od ktorej táto požiadavka závisí, je dočasne nedostupná. Skúste to znova neskôr.

Hlavičky odpovede

  • RateLimit-Policy

    Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.

  • RateLimit

    Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).

  • X-RateLimit-Remaining

    Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.

  • X-RateLimit-Reset

    Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, ktoré táto operácia môže vrátiť v error.code, okrem všeobecných kódov každej požiadavky.

Bezpečné opakovanie

S každou požiadavkou POST a PATCH odošlite hlavičku Idempotency-Key (napríklad UUID). Opakovaná požiadavka s rovnakým kľúčom do 24 hodín vráti uloženú odpoveď namiesto toho, aby sa požiadavka vykonala znova.

Limity frekvencie

Odpovede obsahujú hlavičky RateLimit a RateLimit-Policy a staršie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpoveď 429 má hlavičku Retry-After v sekundách: počkajte a požiadavku zopakujte.

← finance · Referencia API