Pāriet uz saturu
Sursa Developers

POST/v1/finance/report

Iegūt finanšu kopsavilkuma pārskatu

finance_report

Atgriež organizācijas rēķinu vai maksājumu kopsummas, grupētas pēc ne vairāk kā trim dimensijām (kategorija, grupa, piegādātāja darbības veids, piegādātājs, pircējs, darījuma partneris, virziens, valūta, mēnesis, ceturksnis, gads), ar rādītājiem invoiced, paid, unpaid un tax. Kopsummās tiek iekļauti tikai lietotājam redzamie dokumenti (viņa datu profila kolekcijas un kategorijas un iestatījums „atbildēt tikai no pārbaudītām kartītēm“); pieprasījuma filtri šo apjomu sašaurina, bet nekad nepaplašina.

Režīmā reporting (noklusējums) summas tiek konvertētas organizācijas pārskatu valūtā pēc kursa dokumenta datumā, un summas bez kursa tiek uzskaitītas laukā conversion.unconverted. Režīmā original summas dažādās valūtās netiek saskaitītas, un valūta kļūst par rindas dimensiju. Ja rindu ir vairāk nekā limit, truncated ir true, un totals joprojām aptver visas rindas. Nepieciešams datu profils ar piekļuvi finanšu datiem (finance.forbidden).

Pārskats, rēķinu un maksājumu saraksti un to eksports ir lasīšanas operācijas, lai gan tās izmanto POST: tās ir pieejamas režīmā „View as“ un API atslēgām ar tvērumu read (un, tāpat kā iepriekš, atslēgām ar tvērumu write).

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Galvenes parametri

  • X-View-Asstring

    Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

  • kb_view_asstring

    Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Pieprasījuma saturs

application/json

Objekts: FinanceReportRequest

  • basisstring

    invoices: rēķini, kredītrēķini un čeki. payments: maksājumu žurnāls (naudas plūsma). Ar payments vienīgais rādītājs ir paid, un dimensija direction un kopsumma rāda naudas kustību, in vai out, bet pārskaitījums starp jūsu pašu juridiskajām personām ir internal.

    Atļautās vērtības: invoicespayments

    Noklusējums: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Pēc noklusējuma invoiced (paid, ja payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Kurš datums nosaka periodu un filtru from/to: dokumenta datums vai maksājuma datums.

    Atļautās vērtības: documentpayment

    Noklusējums: "document"

  • filtersFinanceFilter
  • order_bystring

    Rādītājs vai dimensija, pēc kuras kārtot. Pēc noklusējuma – pirmais rādītājs dilstošā secībā.

  • order_descboolean

    Noklusējums: true

  • limitinteger

    Noklusējums: 1000≥ 1, ≤ 10000

  • languagestring

    Kategoriju un grupu nosaukumu valoda, en|ru. Pēc noklusējuma en.

Atbildes

200Pārskats

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: FinanceReport

  • currency_modeFinanceCurrencyModeobligāts
  • currencystring

    Pārskatu valūta (režīms reporting).

  • rowsarray of FinanceReportRowobligāts
  • totalsarray of FinanceReportTotalobligāts

    Kopsummas pa visām rindām pirms saīsināšanas, viens ieraksts katrai valūtai (pārskatā, kas sadalīts pa virzieniem, – katrai valūtai un virzienam, FinanceReportTotal.direction).

  • truncatedbooleanobligāts
  • limitintegerobligāts
  • total_rowsintegerobligāts

    Grupēto rindu skaits pirms saīsināšanas.

  • conversionFinanceConversion
  • warningsarray of string

    Brīdinājumu kodi: profile_missing – organizācijas uzņēmuma rekvizīti nav norādīti, tāpēc rēķinu virziens pēc noklusējuma ir in; catalog_missing – uzņēmumu reģistrs nav ielādēts; fx_rate_missing – dažām summām nav valūtas kursa (conversion.unconverted); fx_rate_stale – daži kursi ir novecojuši; enrichment_pending – daži dokumenti vēl tiek apstrādāti un nav iekļauti kopsummās. Nezināmu kodu rādiet ar vispārīgu ziņojumu.

400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

  • Retry-After

    Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

503Pakalpojums, no kura atkarīgs šis pieprasījums, īslaicīgi nav pieejams. Atkārtojiet vēlāk.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Droši atkārtojumi

Ar katru POST un PATCH pieprasījumu nosūtiet galveni Idempotency-Key (piemēram, UUID). Atkārtots pieprasījums ar to pašu atslēgu 24 stundu laikā atgriež saglabāto atbildi, nevis izpilda pieprasījumu vēlreiz.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← finance · API rokasgrāmata