POST/v1/finance/invoices

Popis računa

finance_invoices

Vraća račune, knjižna odobrenja i blagajničke račune organizacije stranicu po stranicu, s filtrima (razdoblje, smjer, kategorija, poslovni partner, valuta, vrsta dokumenta, plaćeno, s prekoračenim rokom, potreban pregled, pretraživanje po broju i strani), sortiranjem te iznosom u izvještajnoj valuti s tečajem preračunavanja. Uključeni su samo dokumenti vidljivi korisniku. Za sljedeću stranicu proslijedite next_cursor kao cursor s istim filtrima. Zahtijeva podatkovni profil s pristupom financijskim podacima.

Autentifikacija

Pošaljite API ključ u zaglavlju Authorization: Authorization: Bearer <ključ>.

Parametri zaglavlja

X-View-Asstring
Samo za API ključeve s ulogom admin. Izvodi zahtjev kao podatkovni profil <profile>[:viewer|verifier|editor], na primjer employee:viewer. Ključ instalacije ne može koristiti ovo zaglavlje (403).

Parametri kolačića

kb_view_asstring
Kolačić načina „View as” za sesiju. Postavlja ga POST /auth/view-as, a briše DELETE /auth/view-as.

Tijelo zahtjeva

application/json

Objekt: FinanceListRequest

filtersFinanceFilter
date_basisstring
Dopuštene vrijednosti: documentpayment
Zadano: "document"
orderstring
Dopuštene vrijednosti: date_descdate_ascamount_descamount_asc
Zadano: "date_desc"
currency_modeFinanceCurrencyMode
limitinteger
Zadano: 100≥ 1, ≤ 1000
cursorstring
languagestring
Jezik naziva kategorija, en|ru.

Odgovori

200Stranica računa

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: FinanceInvoicePage

invoicesarray of FinanceInvoiceRowobavezno
totalintegerobavezno
Ukupan broj računa koji odgovaraju filtrima.
next_cursorstring
Kursor sljedeće stranice. Ako polja nema, ovo je posljednja stranica.
currencystring
Izvještajna valuta polja reporting (način reporting).
warningsarray of string
Kodovi upozorenja, isti kao u FinanceReport.warnings.
has_moreboolean
Postoji li sljedeća stranica. Prisutno kad zahtjev prosljeđuje limit ili cursor.

400Zahtjev nije valjan: vrijednost parametra ili stanje objekta ne dopušta radnju (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

401Vjerodajnice nisu poslane (ni kolačić sesije ni API ključ) ili ključ nije pronađen.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

403Radnja nije dopuštena: uloga nije dovoljna, nema pristupa zbirci ili kartici, zahtjev se izvodi u načinu „View as” ili je organizacija suspendirana ili izbrisana (`detail` je objekt s `code: org_suspended | org_deleted`).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

429Previše zahtjeva (`api.rate_limited`), kvota organizacije za minutu, dan ili mjesec je potrošena (`api.quota_exceeded`; `error.details` sadrži `quota`, `limit` i `reset_at`), dosegnuto je ograničenje organizacije ili je usluga odgovora zauzeta (`answers.engine_busy`). Pričekajte vrijeme navedeno u zaglavlju `Retry-After`.

Zaglavlja odgovora

Retry-After
Broj sekundi koje treba pričekati prije ponovnog pokušaja zahtjeva.
RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

503Usluga o kojoj ovaj zahtjev ovisi privremeno nije dostupna. Pokušajte ponovno kasnije.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

Kodovi pogrešaka

Kodovi koje ova operacija može vratiti u error.code, uz opće kodove svakog zahtjeva.

Sigurni ponovni pokušaji

Uz svaki POST i PATCH pošaljite zaglavlje Idempotency-Key (na primjer UUID). Ponovni pokušaj s istim ključem unutar 24 sata vraća spremljeni odgovor umjesto da ponovno izvrši zahtjev.

Ograničenja učestalosti

Odgovori sadrže zaglavlja RateLimit i RateLimit-Policy te ranija zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odgovor 429 sadrži zaglavlje Retry-After u sekundama: pričekajte i pokušajte ponovno.

← finance · Referenca API-ja

curl -X POST 'https://api.sursa.com/v1/finance/invoices' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"from":"2026-10-24","to":"2026-10-24","directions":["in"]},"date_basis":"document","order":"date_desc"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Isprobajte

API ključ

Ključ ostaje u memoriji ove kartice preglednika i šalje se samo na https://api.sursa.com.

Zahtjevi djeluju na stvarne podatke vaše organizacije.

X-View-As header

Idempotency-Key

Ako je polje prazno, za svaki se zahtjev stvara novi ključ.

Tijelo zahtjeva (JSON)