POST/v1/finance/report

Finanzübersicht abrufen

finance_report

Gibt die Summen der Rechnungen oder Zahlungen der Organisation zurück, gruppiert nach bis zu drei Dimensionen (Kategorie, Gruppe, Geschäftsart des Lieferanten, Lieferant, Käufer, Geschäftspartner, Richtung, Währung, Monat, Quartal, Jahr), mit den Kennzahlen invoiced, paid, unpaid und tax. Die Summen umfassen nur für den Benutzer sichtbare Dokumente (die Sammlungen und Kategorien seines Datenprofils sowie die Einstellung „nur aus geprüften Karten antworten“); Filter der Anfrage schränken diesen Umfang ein, erweitern ihn aber nie.

Im Modus reporting (Standard) werden Beträge zum Kurs am Dokumentdatum in die Berichtswährung der Organisation umgerechnet, und Beträge ohne Kurs werden in conversion.unconverted aufgeführt. Im Modus original werden Beträge in verschiedenen Währungen nicht addiert, und die Währung wird zu einer Dimension der Zeile. Gibt es mehr Zeilen als limit, ist truncated gleich true, und totals umfasst dennoch alle Zeilen. Erfordert ein Datenprofil mit Zugriff auf Finanzdaten (finance.forbidden).

Der Bericht, die Listen der Rechnungen und Zahlungen und ihre Exporte sind Leseoperationen, obwohl sie POST verwenden: Diese Operationen sind im Modus „Ansicht als“ und für API-Schlüssel mit dem Scope read verfügbar (und wie bisher für Schlüssel mit dem Scope write).

Authentifizierung

Senden Sie einen API-Schlüssel im Header Authorization: Authorization: Bearer <Schlüssel>.

Header-Parameter

X-View-Asstring
Nur für API-Schlüssel mit der Rolle admin. Führt die Anfrage mit dem Datenprofil <profile>[:viewer|verifier|editor] aus, zum Beispiel employee:viewer. Der Installationsschlüssel kann diesen Header nicht verwenden (403).

Cookie-Parameter

kb_view_asstring
Cookie des Modus „Ansicht als“ für eine Sitzung. POST /auth/view-as setzt es, DELETE /auth/view-as entfernt es.

Anfragetext

application/json

Objekt: FinanceReportRequest

basisstring
invoices: Rechnungen, Gutschriften und Belege. payments: das Zahlungsprotokoll (Cashflow). Mit payments ist die einzige Kennzahl paid, und die Dimension direction und die Summe zeigen die Geldbewegung, in oder out, während eine Überweisung zwischen Ihren eigenen juristischen Personen internal ist.
Zulässige Werte: invoicespayments
Standard: "invoices"
group_byarray of FinanceDimension
items ≤ 3
measuresarray of FinanceMeasure
Standardmäßig invoiced (paid bei payments).
currency_modeFinanceCurrencyMode
date_basisstring
Welches Datum den Zeitraum und den Filter from/to bestimmt: das Dokumentdatum oder das Zahlungsdatum.
Zulässige Werte: documentpayment
Standard: "document"
filtersFinanceFilter
order_bystring
Kennzahl oder Dimension, nach der sortiert wird. Standardmäßig die erste Kennzahl in absteigender Reihenfolge.
order_descboolean
Standard: true
limitinteger
Standard: 1000≥ 1, ≤ 10000
languagestring
Sprache der Bezeichnungen von Kategorien und Gruppen, en|ru. Standardmäßig en.

Antworten

200Der Bericht

Antwort-Header

RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: FinanceReport

currency_modeFinanceCurrencyModeerforderlich
currencystring
Berichtswährung (Modus reporting).
rowsarray of FinanceReportRowerforderlich
totalsarray of FinanceReportTotalerforderlich
Summen über alle Zeilen vor dem Kürzen, ein Eintrag pro Währung (bei einem nach Richtung aufgeteilten Bericht pro Währung und Richtung, FinanceReportTotal.direction).
truncatedbooleanerforderlich
limitintegererforderlich
total_rowsintegererforderlich
Anzahl der gruppierten Zeilen vor dem Kürzen.
conversionFinanceConversion
warningsarray of string
Warncodes: profile_missing – die Unternehmensdaten der Organisation sind nicht hinterlegt, daher ist die Rechnungsrichtung standardmäßig in; catalog_missing – das Unternehmensverzeichnis ist nicht geladen; fx_rate_missing – für einige Beträge gibt es keinen Wechselkurs (conversion.unconverted); fx_rate_stale – einige Kurse sind veraltet; enrichment_pending – einige Dokumente werden noch verarbeitet und sind nicht in den Summen enthalten. Zeigen Sie einen unbekannten Code mit einer allgemeinen Meldung an.

400Die Anfrage ist ungültig: Ein Parameterwert oder der Zustand des Objekts lässt die Aktion nicht zu (`detail` ist eine Meldung).

Antwort-Header

RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

401Es wurden keine Anmeldedaten gesendet (weder ein Sitzungscookie noch ein API-Schlüssel), oder der Schlüssel wurde nicht gefunden.

Antwort-Header

RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

403Die Aktion ist nicht erlaubt: Die Rolle reicht nicht aus, es besteht kein Zugriff auf die Sammlung oder Karte, die Anfrage läuft im Modus „Ansicht als“, oder die Organisation ist gesperrt oder gelöscht (`detail` ist ein Objekt mit `code: org_suspended | org_deleted`).

Antwort-Header

RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

429Zu viele Anfragen (`api.rate_limited`), das Kontingent der Organisation für die Minute, den Tag oder den Monat ist aufgebraucht (`api.quota_exceeded`; `error.details` enthält `quota`, `limit` und `reset_at`), das Limit der Organisation ist erreicht, oder der Antwortdienst ist ausgelastet (`answers.engine_busy`). Warten Sie die im Header `Retry-After` angegebene Zeit ab.

Antwort-Header

Retry-After
Anzahl der Sekunden, die Sie warten sollten, bevor Sie die Anfrage wiederholen.
RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

503Ein Dienst, von dem diese Anfrage abhängt, ist vorübergehend nicht verfügbar. Versuchen Sie es später erneut.

Antwort-Header

RateLimit-Policy
Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.
RateLimit
Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).
X-RateLimit-Remaining
Verbleibende Anfragen unter dem strengsten Limit.
X-RateLimit-Reset
Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

Fehlercodes

Codes, die dieser Endpunkt in error.code zurückgeben kann, zusätzlich zu den allgemeinen Codes jeder Anfrage.

Sichere Wiederholungen

Senden Sie bei jedem POST und PATCH einen Header Idempotency-Key (zum Beispiel eine UUID). Eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden gibt die gespeicherte Antwort zurück, statt die Anfrage erneut auszuführen.

Ratenlimits

Antworten enthalten die Header RateLimit und RateLimit-Policy sowie die älteren X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Antwort 429 enthält Retry-After in Sekunden: Warten Sie und versuchen Sie es dann erneut.

← finance · API-Referenz

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"

Ausprobieren

API-Schlüssel

Der Schlüssel bleibt im Speicher dieses Tabs und wird nur an https://api.sursa.com gesendet.

Anfragen wirken auf die echten Daten Ihrer Organisation.

X-View-As header

Idempotency-Key

Ist das Feld leer, wird für jede Anfrage ein neuer Schlüssel erzeugt.

Anfragetext (JSON)