Gå til indholdet
Sursa Developers

POST/v1/finance/report

Hent en økonomisk oversigtsrapport

finance_report

Returnerer totaler for organisationens fakturaer eller betalinger, grupperet efter op til tre dimensioner (kategori, gruppe, leverandørens branche, leverandør, køber, modpart, retning, valuta, måned, kvartal, år), med nøgletallene invoiced, paid, unpaid og tax. Totalerne omfatter kun dokumenter, der er synlige for brugeren: samlingerne og kategorierne i vedkommendes dataprofil og indstillingen »answer only from verified cards« (svar kun ud fra verificerede kort). Anmodningens filtre indsnævrer dette omfang, men udvider det aldrig.

I tilstanden reporting (standard) omregnes beløb til organisationens rapporteringsvaluta til kursen på dokumentets dato, og beløb uden kurs vises i conversion.unconverted. I tilstanden original lægges beløb i forskellige valutaer ikke sammen, og valutaen bliver en dimension i rækken. Er der flere rækker end limit, er truncated true, og totals dækker stadig alle rækker. Kræver en dataprofil med adgang til økonomiske data (finance.forbidden).

Rapporten, listerne over fakturaer og betalinger og eksporten af dem er læseoperationer, selv om de bruger POST: de er tilgængelige i tilstanden »View as« og for API-nøgler med scopet read (og som hidtil for nøgler med scopet write).

Autentificering

Send en API-nøgle i headeren Authorization: Authorization: Bearer <nøgle>.

Headerparametre

  • X-View-Asstring

    Kun for API-nøgler med rollen admin. Udfører anmodningen som dataprofilen <profile>[:viewer|verifier|editor], fx employee:viewer. Installationsnøglen kan ikke bruge denne header (403).

Cookieparametre

  • kb_view_asstring

    Cookie for tilstanden »View as« i en session. POST /auth/view-as sætter den, og DELETE /auth/view-as fjerner den.

Anmodningens brødtekst

application/json

Objekt: FinanceReportRequest

  • basisstring

    invoices: fakturaer, kreditnotaer og kvitteringer. payments: betalingsloggen (pengestrømme). Med payments er det eneste nøgletal paid, og dimensionen direction og totalen viser pengenes bevægelse, in eller out, mens en overførsel mellem dine egne juridiske enheder er internal.

    Tilladte værdier: invoicespayments

    Standard: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Standard er invoiced (paid for payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Hvilken dato der bestemmer perioden og filteret from/to: dokumentets dato eller betalingsdatoen.

    Tilladte værdier: documentpayment

    Standard: "document"

  • filtersFinanceFilter
  • order_bystring

    Nøgletal eller dimension, der sorteres efter. Som standard det første nøgletal i faldende rækkefølge.

  • order_descboolean

    Standard: true

  • limitinteger

    Standard: 1000≥ 1, ≤ 10000

  • languagestring

    Sprog for etiketterne på kategorier og grupper, en|ru. Standard er en.

Svar

200Rapporten

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: FinanceReport

  • currency_modeFinanceCurrencyModepåkrævet
  • currencystring

    Rapporteringsvaluta (tilstanden reporting).

  • rowsarray of FinanceReportRowpåkrævet
  • totalsarray of FinanceReportTotalpåkrævet

    Totaler over alle rækker før afkortning, én post pr. valuta (for en rapport opdelt efter retning pr. valuta og retning, FinanceReportTotal.direction).

  • truncatedbooleanpåkrævet
  • limitintegerpåkrævet
  • total_rowsintegerpåkrævet

    Antal grupperede rækker før afkortning.

  • conversionFinanceConversion
  • warningsarray of string

    Advarselskoder: profile_missing, organisationens virksomhedsoplysninger er ikke angivet, så fakturaens retning er som standard in; catalog_missing, registret over virksomheder er ikke indlæst; fx_rate_missing, nogle beløb har ingen valutakurs (conversion.unconverted); fx_rate_stale, nogle kurser er forældede; enrichment_pending, nogle dokumenter er stadig under behandling og indgår ikke i totalerne. Vis en ukendt kode med en generel meddelelse.

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

  • Retry-After

    Antal sekunder, du skal vente, før du prøver anmodningen igen.

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

503En tjeneste, som denne anmodning afhænger af, er midlertidigt utilgængelig. Prøv igen senere.

Svarets headere

  • RateLimit-Policy

    Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.

  • RateLimit

    Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).

  • X-RateLimit-Remaining

    Resterende anmodninger under den strengeste grænse.

  • X-RateLimit-Reset

    Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← finance · API-reference