Konvencijos, klaidos ir užklausų limitai

Užklausų ir atsakymų formatai, puslapiavimas, identifikatoriai, datos ir pinigų sumos, HTTP būsenos kodai ir 60 užklausų per minutę limitas.

Užklausos

Bazinis URL https://app.fsaskaita.lt/api.
Antraštės kiekvienoje užklausoje: Authorization: Bearer <token> ir Accept: application/json.
Sąskaitų faktūrų galiniai taškai priima JSON turinį (Content-Type: application/json). Išlaidų galiniai taškai priima multipart/form-data, nes kartu keliauja failas.
Šioje API PUT ir PATCH yra lygiaverčiai. Abu pakeičia visą resursą jūsų siunčiamu turiniu, todėl visada siųskite visus laukus.

Atsakymai

Pavienis resursas įvilktas į data:

{ "data": { "id": "…", "…": "…" } }

Sąrašas įvilktas į data su meta bloku:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://app.fsaskaita.lt/api/invoices",
    "per_page": 50,
    "to": 50,
    "total": 132
  }
}

Šalinimas grąžina 200 su tuščiu turiniu.

Sąrašai grąžina 50 įrašų puslapyje, naujausius pirmus, ir priima tik ?page=N. Filtrų, rikiavimo parametrų ar puslapio dydžio pasirinkimų nėra. Sinchronizuodami eikite per puslapius, kol current_page susilygins su last_page. GET /currencies nepuslapiuojamas.

Identifikatoriai, datos, pinigų sumos

Tipas	Formatas	Pavyzdys
Identifikatoriai	UUID eilutė	`"9c1f7b2e-3a6d-4d5e-9f0a-2b7c8d9e0f11"`
Datos užklausose ir atsakymuose	`YYYY-MM-DD`	`"2026-09-08"`
`created_at`, `updated_at`	Unix laiko žyma, sekundės, sveikasis skaičius	`1757318400`
Pinigų sumos	JSON skaičius	`60.5`
Valiuta	ISO 4217 kodas didžiosiomis raidėmis, priimamas `GET /currencies`	`"EUR"`
Sąskaitų numeriai	eilutė, atsakymuose užpildyta nuliais iki trijų skaitmenų	`"007"`

Išvardintosios reikšmės yra mažųjų raidžių snake_case eilutės, pavyzdžiui vat_invoice arba not_paid. Žinyne pateiktos leidžiamos kiekvieno lauko reikšmės.

Klaidos

Būsena	Reikšmė	Turinys
`401`	Trūkstamas, neteisingas arba ištrintas prieigos raktas	`{"message":"Unauthenticated."}`
`404`	Nežinomas id arba resursas priklauso kitam verslui	`{"message":"…"}`
`422`	Validacija nepavyko	žr. toliau
`429`	Viršytas užklausų limitas	`{"message":"Too Many Attempts."}` ir `Retry-After`
`500`	Netikėta serverio klaida	`{"message":"Server Error"}`

Validacijos klaidos išvardija visus netinkamus laukus. Įdėtiniams laukams naudojami taškiniai keliai. Pranešimai yra lietuvių kalba.

{
  "message": "Laukas type yra privalomas. (and 2 more errors)",
  "errors": {
    "type": ["Laukas type yra privalomas."],
    "buyer.company_name": ["…"],
    "products.0.quantity": ["…"]
  }
}

403 nėra. Prieigos raktas arba veikia savo verslui, arba atmetamas su 401.

Užklausų limitai

Kiekvienas verslas gali atlikti 60 užklausų per minutę visais savo prieigos raktais kartu. Kiekvienas atsakymas turi antraštes X-RateLimit-Limit ir X-RateLimit-Remaining. Pasiekus limitą, atsakymas yra 429 su Retry-After sekundėmis ir X-RateLimit-Reset kaip Unix laiko žyma. Palaukite iki tol; bandant anksčiau gausite tik daugiau 429 atsakymų.

Idempotentiškumas ir pakartotiniai bandymai

API neturi idempotentiškumo rakto. POST užklausa, kuriai baigėsi tinklo laukimo laikas, vis tiek galėjo sukurti resursą. Prieš kartodami, peržiūrėkite naujausių įrašų sąrašą ir patikrinkite, ar jūsiškis jau yra. PUT ir DELETE kartoti saugu.

Lokalizacija

Validacijos pranešimai ir tipo pavadinimas PDF failų pavadinimuose yra lietuvių kalba, nebent sąskaitos language nurodo kitaip. Accept-Language derinimo nėra.