# 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`:

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

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

```json
{
  "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.

## Puslapiavimas

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.

```json
{
  "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.