POST/v1/finance/invoices

Listaa laskut

finance_invoices

Palauttaa organisaation laskut, hyvityslaskut ja kuitit sivu kerrallaan suodattimin (jakso, suunta, luokka, vastapuoli, valuutta, asiakirjatyyppi, maksettu, erääntynyt, vaatii tarkistuksen, haku numeron ja osapuolen mukaan), lajittelulla ja raportointivaluutan summalla muuntokursseineen. Mukana ovat vain käyttäjälle näkyvät asiakirjat. Saat seuraavan sivun antamalla next_cursor-arvon cursor-parametrina samoilla suodattimilla. Edellyttää dataprofiilia, jolla on pääsy taloustietoihin.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Otsakeparametrit

X-View-Asstring
Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

kb_view_asstring
Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Pyynnön runko

application/json

Objekti: FinanceListRequest

filtersFinanceFilter
date_basisstring
Sallitut arvot: documentpayment
Oletus: "document"
orderstring
Sallitut arvot: date_descdate_ascamount_descamount_asc
Oletus: "date_desc"
currency_modeFinanceCurrencyMode
limitinteger
Oletus: 100≥ 1, ≤ 1000
cursorstring
languagestring
Luokkien nimikkeiden kieli, en|ru.

Vastaukset

200Sivu laskuja

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: FinanceInvoicePage

invoicesarray of FinanceInvoiceRowpakollinen
totalintegerpakollinen
Suodattimia vastaavien laskujen kokonaismäärä.
next_cursorstring
Seuraavan sivun kursori. Jos kenttää ei ole, tämä on viimeinen sivu.
currencystring
reporting-kenttien raportointivaluutta (reporting-tila).
warningsarray of string
Varoituskoodit, samat kuin FinanceReport.warnings-kentässä.
has_moreboolean
Onko seuraavaa sivua. Mukana, kun pyynnössä on limit- tai cursor-parametri.

400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

Retry-After
Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.
RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

503Palvelu, josta tämä pyyntö riippuu, ei ole tilapäisesti käytettävissä. Yritä myöhemmin uudelleen.

Vastausotsakkeet

RateLimit-Policy
Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.
RateLimit
Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).
X-RateLimit-Remaining
Tiukimman rajan puitteissa jäljellä olevat pyynnöt.
X-RateLimit-Reset
Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Turvalliset uusintayritykset

Lähetä jokaisen POST- ja PATCH-pyynnön mukana Idempotency-Key-otsake (esimerkiksi UUID). Kun pyyntö toistetaan samalla avaimella 24 tunnin kuluessa, palautetaan tallennettu vastaus eikä pyyntöä suoriteta uudelleen.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← finance · API-viite

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"

Kokeile

API-avain

Avain säilyy vain tämän välilehden muistissa, ja se lähetetään ainoastaan osoitteeseen https://api.sursa.com.

Pyynnöt kohdistuvat organisaatiosi todellisiin tietoihin.

X-View-As header

Idempotency-Key

Jos kenttä on tyhjä, jokaiselle pyynnölle luodaan uusi avain.

Pyynnön runko (JSON)