Ugrás a tartalomra
Sursa Developers

POST/v1/finance/report

Pénzügyi összesítő jelentés lekérése

finance_report

Visszaadja a szervezet számláinak vagy kifizetéseinek összesítőit, legfeljebb három dimenzió szerint csoportosítva (kategória, csoport, a szállító tevékenységi köre, szállító, vevő, partner, irány, pénznem, hónap, negyedév, év), az invoiced, a paid, az unpaid és a tax mérőszámmal. Az összesítők csak a felhasználó számára látható dokumentumokat tartalmazzák (az adatprofiljának gyűjteményei és kategóriái, valamint a „csak ellenőrzött kártyák alapján válaszolj” beállítás szerint); a kérés szűrői szűkítik ezt a kört, de soha nem bővítik.

reporting módban (alapértelmezett) az összegeket a dokumentum dátuma szerinti árfolyamon a szervezet jelentési pénznemére váltja át, az árfolyam nélküli összegeket pedig a conversion.unconverted mezőben sorolja fel. original módban a különböző pénznemű összegeket nem adja össze, és a pénznem a sor egyik dimenziója lesz. Ha több sor van, mint a limit, a truncated értéke true, a totals pedig továbbra is az összes sort lefedi. Pénzügyi adatokhoz hozzáférő adatprofil szükséges (finance.forbidden).

A jelentés, a számla- és kifizetési listák és ezek exportálásai olvasási műveletek, bár POST metódust használnak: „View as” módban és a read hatókörű API-kulcsokkal is elérhetők (és ahogy eddig, a write hatókörű kulcsokkal is).

Hitelesítés

Küldj egy API-kulcsot az Authorization fejlécben: Authorization: Bearer <kulcs>.

Fejlécparaméterek

  • X-View-Asstring

    Csak admin szerepkörű API-kulcsokhoz. A kérést a <profile>[:viewer|verifier|editor] adatprofil nevében hajtja végre, például employee:viewer. A telepítési kulcs nem használhatja ezt a fejlécet (403).

Cookie-paraméterek

  • kb_view_asstring

    A „View as” mód sütije egy munkamenethez. A POST /auth/view-as beállítja, a DELETE /auth/view-as törli.

Kéréstörzs

application/json

Objektum: FinanceReportRequest

  • basisstring

    invoices: számlák, jóváíró számlák és nyugták. payments: a kifizetési napló (pénzforgalom). A payments értéknél az egyetlen mérőszám a paid; a direction dimenzió és az összesítés a pénzmozgást mutatja, in vagy out, a saját jogi személyeid közötti átutalás pedig internal.

    Megengedett értékek: invoicespayments

    Alapértelmezett: "invoices"

  • group_byarray of FinanceDimension

    items ≤ 3

  • measuresarray of FinanceMeasure

    Alapértelmezett érték: invoiced (payments esetén paid).

  • currency_modeFinanceCurrencyMode
  • date_basisstring

    Melyik dátum határozza meg az időszakot és a from/to szűrőt: a dokumentum dátuma vagy a kifizetés dátuma.

    Megengedett értékek: documentpayment

    Alapértelmezett: "document"

  • filtersFinanceFilter
  • order_bystring

    A rendezés alapjául szolgáló mérőszám vagy dimenzió. Alapértelmezés szerint az első mérőszám, csökkenő sorrendben.

  • order_descboolean

    Alapértelmezett: true

  • limitinteger

    Alapértelmezett: 1000≥ 1, ≤ 10000

  • languagestring

    A kategóriák és a csoportok megnevezésének nyelve, en|ru. Alapértelmezett érték: en.

Válaszok

200A jelentés

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: FinanceReport

  • currency_modeFinanceCurrencyModekötelező
  • currencystring

    Jelentési pénznem (reporting mód).

  • rowsarray of FinanceReportRowkötelező
  • totalsarray of FinanceReportTotalkötelező

    Az összes sor összesítése a csonkolás előtt, pénznemenként egy rekord (irány szerint bontott jelentésnél pénznemenként és irányonként, FinanceReportTotal.direction).

  • truncatedbooleankötelező
  • limitintegerkötelező
  • total_rowsintegerkötelező

    A csoportosított sorok száma a csonkolás előtt.

  • conversionFinanceConversion
  • warningsarray of string

    Figyelmeztetési kódok: profile_missing: a szervezet cégadatai nincsenek megadva, ezért a számlák iránya alapértelmezés szerint in; catalog_missing: a cégkatalógus nincs betöltve; fx_rate_missing: egyes összegekhez nincs árfolyam (conversion.unconverted); fx_rate_stale: egyes árfolyamok elavultak; enrichment_pending: egyes dokumentumok feldolgozása még folyamatban van, ezért nem szerepelnek az összesítésben. Ismeretlen kódnál általános üzenetet jeleníts meg.

400A kérés érvénytelen: egy paraméter értéke vagy az objektum állapota nem teszi lehetővé a műveletet (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

401Nem érkeztek hitelesítő adatok (sem munkamenet-süti, sem API-kulcs), vagy a kulcs nem található.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

403A művelet nem engedélyezett: a szerepkör nem elegendő, nincs hozzáférés a gyűjteményhez vagy a kártyához, a kérés „View as” módban fut, vagy a szervezetet felfüggesztették vagy törölték (a `detail` egy objektum, `code: org_suspended | org_deleted` mezővel).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

429Túl sok kérés (`api.rate_limited`), elfogyott a szervezet percre, napra vagy hónapra szóló kvótája (`api.quota_exceeded`; az `error.details` a `quota`, a `limit` és a `reset_at` mezőt tartalmazza), a szervezet elérte a korlátját, vagy a válaszszolgáltatás foglalt (`answers.engine_busy`). Várj a `Retry-After` fejlécben megadott ideig.

Válaszfejlécek

  • Retry-After

    Ennyi másodpercet várj, mielőtt újrapróbálod a kérést.

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

503Egy szolgáltatás, amelytől ez a kérés függ, átmenetileg nem érhető el. Próbáld újra később.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

Hibakódok

Azok a kódok, amelyeket ez a végpont hiba esetén az error.code mezőben visszaadhat, a minden kérésre érvényes általános kódokon kívül.

Biztonságos újrapróbálkozás

Minden POST és PATCH kéréssel küldj Idempotency-Key fejlécet (például egy UUID-t). Ha 24 órán belül ugyanazzal a kulccsal megismétled a kérést, a mentett választ kapod vissza, és a kérés nem fut le újra.

Gyakorisági korlátok

A válaszokban ott van a RateLimit és a RateLimit-Policy fejléc, valamint a korábbi X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléc. A 429-es válasz Retry-After fejléce másodpercben adja meg a várakozást: várj, majd próbáld újra.

← finance · API-referencia