Pereiti prie turinio
Sursa Developers

POST/v1/finance/report

Gauti finansų suvestinės ataskaitą

finance_report

Grąžina organizacijos sąskaitų faktūrų arba mokėjimų sumas, sugrupuotas pagal iki trijų dimensijų (kategorija, grupė, tiekėjo veiklos tipas, tiekėjas, pirkėjas, kontrahentas, kryptis, valiuta, mėnuo, ketvirtis, metai), su matais invoiced, paid, unpaid ir tax. Į sumas įtraukiami tik naudotojui matomi dokumentai (jo duomenų profilio rinkiniai ir kategorijos bei nustatymas „answer only from verified cards“ – atsakyti tik remiantis patikrintomis kortelėmis); užklausos filtrai šią sritį susiaurina, bet niekada neišplečia.

Režimu reporting (numatytasis) sumos perskaičiuojamos į organizacijos ataskaitų valiutą pagal dokumento datos kursą, o sumos be kurso išvardijamos lauke conversion.unconverted. Režimu original skirtingų valiutų sumos nesudedamos, o valiuta tampa eilutės dimensija. Jei eilučių daugiau nei limit, truncated yra true, o totals vis tiek apima visas eilutes. Reikia duomenų profilio su prieiga prie finansinių duomenų (finance.forbidden).

Ataskaita, sąskaitų faktūrų ir mokėjimų sąrašai bei jų eksportas yra skaitymo operacijos, nors ir naudoja POST: jos prieinamos režimu „View as“ ir API raktams su apimtimi read (ir, kaip anksčiau, raktams su apimtimi write).

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Antraštės parametrai

  • X-View-Asstring

    Tik API raktams su vaidmeniu admin. Užklausa vykdoma duomenų profilio <profile>[:viewer|verifier|editor] vardu, pvz., employee:viewer. Diegimo raktas šios antraštės naudoti negali (403).

Slapuko parametrai

  • kb_view_asstring

    Režimo „View as“ (žiūrėti kaip) sesijos slapukas. POST /auth/view-as jį nustato, o DELETE /auth/view-as išvalo.

Užklausos turinys

application/json

Objektas: FinanceReportRequest

  • basisstring

    invoices: sąskaitos faktūros, kreditinės sąskaitos faktūros ir kvitai. payments: mokėjimų žurnalas (pinigų srautai). Su payments vienintelis matas yra paid, o dimensija direction ir bendra suma rodo pinigų judėjimą – in arba out, o pervedimas tarp jūsų pačių juridinių asmenų žymimas internal.

    Leidžiamos reikšmės: invoicespayments

    Numatytoji reikšmė: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Numatytoji reikšmė – invoiced (payments atveju – paid).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Kuri data nustato laikotarpį ir filtrą from/to: dokumento data ar mokėjimo data.

    Leidžiamos reikšmės: documentpayment

    Numatytoji reikšmė: "document"

  • filtersFinanceFilter
  • order_bystring

    Matas arba dimensija rūšiavimui. Numatytai rūšiuojama pagal pirmąjį matą mažėjimo tvarka.

  • order_descboolean

    Numatytoji reikšmė: true

  • limitinteger

    Numatytoji reikšmė: 1000≥ 1, ≤ 10000

  • languagestring

    Kategorijų ir grupių pavadinimų kalba, en|ru. Numatytoji – en.

Atsakai

200Ataskaita

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: FinanceReport

  • currency_modeFinanceCurrencyModeprivalomas
  • currencystring

    Ataskaitos valiuta (režimas reporting).

  • rowsarray of FinanceReportRowprivalomas
  • totalsarray of FinanceReportTotalprivalomas

    Visų eilučių sumos prieš sutrumpinimą, po vieną įrašą kiekvienai valiutai (ataskaitoje, suskaidytoje pagal kryptį, – kiekvienai valiutai ir krypčiai, FinanceReportTotal.direction).

  • truncatedbooleanprivalomas
  • limitintegerprivalomas
  • total_rowsintegerprivalomas

    Sugrupuotų eilučių skaičius prieš sutrumpinimą.

  • conversionFinanceConversion
  • warningsarray of string

    Įspėjimų kodai: profile_missing – organizacijos įmonės rekvizitai nenurodyti, todėl sąskaitų faktūrų kryptis numatytai yra in; catalog_missing – įmonių registras neįkeltas; fx_rate_missing – kai kurioms sumoms nėra valiutos kurso (conversion.unconverted); fx_rate_stale – kai kurie kursai pasenę; enrichment_pending – kai kurie dokumentai dar apdorojami ir neįtraukti į sumas. Nežinomą kodą rodykite su bendru pranešimu.

400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

  • Retry-After

    Kiek sekundžių palaukti prieš kartojant užklausą.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

503Paslauga, nuo kurios priklauso ši užklausa, laikinai nepasiekiama. Pakartokite vėliau.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← finance · API žinynas