POST/v1/finance/report

Financieel overzichtsrapport ophalen

finance_report

Geeft de totalen van de facturen of betalingen van de organisatie terug, gegroepeerd op maximaal drie dimensies (categorie, groep, branche van de leverancier, leverancier, koper, relatie, richting, valuta, maand, kwartaal, jaar), met de meetwaarden invoiced, paid, unpaid en tax. De totalen bevatten alleen documenten die zichtbaar zijn voor de gebruiker (de collecties en categorieën van diens dataprofiel, en de instelling “answer only from verified cards”, alleen antwoorden uit geverifieerde kaarten); filters in het request verkleinen dit bereik, maar vergroten het nooit.

In de modus reporting (standaard) worden bedragen omgerekend naar de rapportagevaluta van de organisatie tegen de koers op de documentdatum, en bedragen zonder koers worden vermeld in conversion.unconverted. In de modus original worden bedragen in verschillende valuta’s niet opgeteld en wordt de valuta een dimensie van de rij. Als er meer rijen zijn dan limit, is truncated true, en dekken totals nog steeds alle rijen. Vereist een dataprofiel met toegang tot financiële gegevens (finance.forbidden).

Het rapport, de lijsten met facturen en betalingen en de exports ervan zijn leesbewerkingen, ook al gebruiken ze POST: ze zijn beschikbaar in de modus “View as” en voor API-sleutels met de scope read (en, zoals voorheen, voor sleutels met de scope write).

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

X-View-Asstring
Alleen voor API-sleutels met de rol admin. Voert het request uit als het dataprofiel <profile>[:viewer|verifier|editor], bijvoorbeeld employee:viewer. De installatiesleutel kan deze header niet gebruiken (403).

Cookieparameters

kb_view_asstring
Cookie van de modus “View as” voor een sessie. POST /auth/view-as zet hem en DELETE /auth/view-as wist hem.

Request-body

application/json

Object: FinanceReportRequest

basisstring
invoices: facturen, creditnota’s en bonnen. payments: het betalingslog (kasstroom). Met payments is paid de enige meetwaarde, en tonen de dimensie direction en het totaal de geldstroom, in of out, terwijl een overboeking tussen je eigen juridische entiteiten internal is.
Toegestane waarden: invoicespayments
Standaard: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Standaard invoiced (paid bij payments).
currency_modeFinanceCurrencyMode
date_basisstring
Welke datum de periode en het filter from/to bepaalt: de documentdatum of de betaaldatum.
Toegestane waarden: documentpayment
Standaard: "document"
filtersFinanceFilter
order_bystring
Meetwaarde of dimensie om op te sorteren. Standaard de eerste meetwaarde in aflopende volgorde.
order_descboolean
Standaard: true
limitinteger
Standaard: 1000≥ 1, ≤ 10000
languagestring
Taal van de labels van categorieën en groepen, en|ru. Standaard en.

Responses

200Het rapport

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: FinanceReport

currency_modeFinanceCurrencyModeverplicht
currencystring
Rapportagevaluta (modus reporting).
rowsarray of FinanceReportRowverplicht
totalsarray of FinanceReportTotalverplicht
Totalen over alle rijen vóór het afkappen, één record per valuta (bij een rapport dat naar richting is opgesplitst: per valuta en richting, FinanceReportTotal.direction).
truncatedbooleanverplicht
limitintegerverplicht
total_rowsintegerverplicht
Aantal gegroepeerde rijen vóór het afkappen.
conversionFinanceConversion
warningsarray of string
Waarschuwingscodes: profile_missing, de bedrijfsgegevens van de organisatie zijn niet ingesteld, dus de richting van facturen is standaard in; catalog_missing, het bedrijvenregister is niet geladen; fx_rate_missing, voor sommige bedragen is er geen wisselkoers (conversion.unconverted); fx_rate_stale, sommige koersen zijn verouderd; enrichment_pending, sommige documenten worden nog verwerkt en tellen niet mee in de totalen. Toon een onbekende code met een algemene melding.

400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

Retry-After
Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.
RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

503Een dienst waarvan dit request afhangt, is tijdelijk niet beschikbaar. Probeer het later opnieuw.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← finance · API-referentie

curl -X POST 'https://api.sursa.com/v1/finance/report' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"basis":"invoices","group_by":["category"],"measures":["invoiced"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Uitproberen

API-sleutel

De sleutel blijft in het geheugen van dit tabblad en wordt alleen naar https://api.sursa.com gestuurd.

Requests werken met de echte gegevens van je organisatie.

X-View-As header

Idempotency-Key

Is dit veld leeg, dan wordt voor elk request een nieuwe sleutel gegenereerd.

Request-body (JSON)