Salt la conținut
Sursa Developers

POST/v1/finance/report

Obține un raport financiar sintetic

finance_report

Returnează totalurile facturilor sau plăților organizației, grupate după cel mult trei dimensiuni (categorie, grup, tipul de activitate al furnizorului, furnizor, cumpărător, partener, direcție, monedă, lună, trimestru, an), cu indicatorii invoiced, paid, unpaid și tax. Totalurile includ doar documentele vizibile pentru utilizator (colecțiile și categoriile profilului lui de date și setarea de a răspunde doar din fișe verificate); filtrele cererii restrâng acest domeniu, dar nu îl lărgesc niciodată.

În modul reporting (implicit), sumele sunt convertite în moneda de raportare a organizației la cursul de la data documentului, iar sumele fără curs sunt listate în conversion.unconverted. În modul original, sumele în monede diferite nu se adună, iar moneda devine o dimensiune a rândului. Dacă există mai multe rânduri decât limit, truncated este true, iar totals acoperă în continuare toate rândurile. Necesită un profil de date cu acces la datele financiare (finance.forbidden).

Raportul, listele de facturi și de plăți și exporturile lor sunt operații de citire, deși folosesc POST: sunt disponibile în modul „View as” (vizualizare ca alt utilizator) și pentru cheile API cu domeniul read (și, ca înainte, pentru cheile cu domeniul write).

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de antet

  • X-View-Asstring

    Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

  • kb_view_asstring

    Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Corpul cererii

application/json

Obiect: FinanceReportRequest

  • basisstring

    invoices: facturi, note de credit și chitanțe. payments: jurnalul plăților (flux de numerar). Cu payments, singurul indicator este paid, iar dimensiunea direction și totalul arată mișcarea banilor, in sau out, în timp ce un transfer între propriile entități juridice este internal.

    Valori permise: invoicespayments

    Implicit: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Implicit invoiced (paid pentru payments).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Data care stabilește perioada și filtrul from/to: data documentului sau data plății.

    Valori permise: documentpayment

    Implicit: "document"

  • filtersFinanceFilter
  • order_bystring

    Indicatorul sau dimensiunea după care se sortează. Implicit, primul indicator în ordine descrescătoare.

  • order_descboolean

    Implicit: true

  • limitinteger

    Implicit: 1000≥ 1, ≤ 10000

  • languagestring

    Limba etichetelor categoriilor și grupurilor, en|ru. Implicit en.

Răspunsuri

200Raportul

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: FinanceReport

  • currency_modeFinanceCurrencyModeobligatoriu
  • currencystring

    Moneda de raportare (modul reporting).

  • rowsarray of FinanceReportRowobligatoriu
  • totalsarray of FinanceReportTotalobligatoriu

    Totaluri pentru toate rândurile înainte de trunchiere, câte o înregistrare pe monedă (pentru un raport împărțit pe direcții, pe monedă și direcție, FinanceReportTotal.direction).

  • truncatedbooleanobligatoriu
  • limitintegerobligatoriu
  • total_rowsintegerobligatoriu

    Numărul de rânduri grupate înainte de trunchiere.

  • conversionFinanceConversion
  • warningsarray of string

    Coduri de avertizare: profile_missing, datele companiei organizației nu sunt completate, așa că direcția facturii este implicit in; catalog_missing, registrul companiilor nu este încărcat; fx_rate_missing, pentru unele sume nu există curs de schimb (conversion.unconverted); fx_rate_stale, unele cursuri sunt învechite; enrichment_pending, unele documente sunt încă în procesare și nu sunt incluse în totaluri. Afișați un cod necunoscut cu un mesaj generic.

400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

503Un serviciu de care depinde această cerere este temporar indisponibil. Reîncercați mai târziu.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← finance · Referința API