> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.skaitra.com/api/apzvalga/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.skaitra.com/_mcp/server.

# API apžvalga

Skaitros API leidžia jūsų sistemoms skaityti įmones, dokumentus ir mėnesio darbus, įkelti dokumentus ir gauti pranešimus apie pasikeitimus. API skirtas programuotojams ir integracijoms (pavyzdžiui, Make ar Zapier scenarijams).

Pilnas visų užklausų aprašas – [API žinyne](/api/api-zinynas). Jis generuojamas iš to paties kontrakto, pagal kurį veikia Skaitra.

## Adresas

API veikia jūsų agentūros adresu:

```text
https://jusu-agentura.skaitra.com/api/v1
```

Jei agentūra naudoja savo domeną, tinka ir jis, pavyzdžiui, `https://buhalterija.example.lt/api/v1`. Raktas veikia tik savo agentūros adresu.

OpenAPI aprašas viešai pasiekiamas adresu [`https://app.skaitra.com/api/v1/openapi.json`](https://app.skaitra.com/api/v1/openapi.json) ir kiekvienos agentūros adresu (`/api/v1/openapi.json`).

## Prieiga ir API raktai

API naudoti gali agentūros, kurių plane yra funkcija **API ir MCP prieiga**. Kitu atveju API atsako klaida `FEATURE_NOT_INCLUDED`.

Raktus kuria agentūros administratorius, skiltyje **Nustatymai → API raktai**:

#### Sukurkite prieigą

Spauskite **Nauja prieiga**. Įrašykite **Pavadinimas**, pažymėkite **Teisės** ir pasirinkite įmones. Jungiklis **Visos aktyvios įmonės** suteikia prieigą prie visų įmonių. Kitu atveju įmones įjunkite kiekvienos įmonės nustatymuose (**AI ir MCP → API raktai ir agentai**).

#### Sukurkite raktą

Prie prieigos spauskite **Naujas raktas**, nurodykite, **Kur bus naudojamas**, ir pasirinkite **Galiojimas** (nesibaigia, 30 dienų, 90 dienų arba metai). Spauskite **Sukurti raktą**.

#### Nukopijuokite raktą

Raktas parodomas tik vieną kartą. Skaitra saugo tik jo maišos reikšmę (hash), todėl vėliau rakto atgauti negalima.

Raktas turi tik savo prieigos teises ir įmones. Raktą bet kada galite atšaukti mygtuku **Atšaukti** – juo besinaudojančios sistemos iškart praranda prieigą.

Raktas siunčiamas antraštėje `Authorization`:

```bash
curl https://jusu-agentura.skaitra.com/api/v1/companies \
  -H "Authorization: Bearer skt_..."
```

```json
{
  "data": [
    { "id": "...", "name": "UAB Pavyzdys", "registrationCode": "300000000", "...": "..." }
  ],
  "nextCursor": null
}
```

API priima ir OAuth prieigos raktus, išduotus MCP klientams (žr. [MCP](/mcp/prijungimas)).

### Teisės

| Teisė                | Ką leidžia                                        |
| -------------------- | ------------------------------------------------- |
| `companies:read`     | Matyti priskirtas įmones                          |
| `companies:write`    | Keisti įmonių duomenis ir nustatymus              |
| `documents:read`     | Matyti priskirtų įmonių dokumentus ir jų duomenis |
| `documents:write`    | Keisti dokumentų informaciją, įkelti dokumentus   |
| `documents:ocr`      | Paleisti dokumentų atpažinimą (OCR)               |
| `work:read`          | Matyti mėnesio darbus (Darbai)                    |
| `work:write`         | Keisti mėnesio darbų būsenas ir atsakingus        |
| `tasks:read`         | Matyti priskirtų įmonių AI užduotis               |
| `tasks:create`       | Kurti AI užduotis                                 |
| `tasks:write_result` | Pateikti AI užduočių rezultatus                   |
| `events:read`        | Matyti įvykius (kas pasikeitė)                    |
| `webhooks:manage`    | Tvarkyti webhook adresus                          |

Kurios teisės reikia kiekvienai užklausai, nurodyta API žinyne (`x-scopes`). Be reikiamos teisės API atsako `403 INSUFFICIENT_SCOPE`.

## Formatas

* Užklausos ir atsakymai – JSON, laukų pavadinimai `camelCase`.
* Vienas įrašas grąžinamas kaip objektas, sąrašas – kaip `{ "data": [...], "nextCursor": ... }`.
* Kiekvienas atsakymas turi antraštę `X-Request-Id`. Nurodykite ją, jei rašote mums dėl klaidos.

## Puslapiavimas

Sąrašai grąžinami puslapiais:

* `limit` – puslapio dydis nuo 1 iki 200 (numatytasis 50);
* `cursor` – ankstesnio atsakymo `nextCursor`.

Kai `nextCursor` yra `null`, tai paskutinis puslapis. Kursorių nekeiskite ir naudokite su tais pačiais filtrais – kitaip gausite `400 INVALID_CURSOR`. Įvykių sąrašas naudoja `after` vietoj `cursor` (žr. [Įvykiai ir webhook](/api/ivykiai-ir-webhook)).

## Pakartotinės užklausos (Idempotency-Key)

Rašančias užklausas (`POST`, `PATCH`, `PUT`, `DELETE`) galite saugiai kartoti, jei siųsite antraštę `Idempotency-Key` su bet kokia unikalia reikšme (iki 200 simbolių):

```bash
curl -X POST https://jusu-agentura.skaitra.com/api/v1/documents \
  -H "Authorization: Bearer skt_..." \
  -H "Idempotency-Key: 6f1c2a0e-saskaita-123" \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "...", "companyId": "..." }'
```

* Pakartota užklausa su tuo pačiu raktu grąžina pirmą rezultatą ir nieko nedaro dar kartą. Atsakymas turi antraštę `Idempotent-Replayed: true`.
* Raktas galioja 24 valandas. Išsaugomi tik sėkmingi rezultatai – nepavykusią užklausą galite kartoti su tuo pačiu raktu.
* Jei ta pati užklausa dar vykdoma, gausite `409 IDEMPOTENCY_KEY_IN_USE`.
* Jei tą patį raktą panaudosite kitai užklausai, gausite `422 IDEMPOTENCY_KEY_REUSED`.

## Dokumentų įkėlimas

Dokumentas įkeliamas dviem užklausomis:

1. `POST /files?filename=saskaita.pdf` – failo baitai užklausos turinyje su tikru `Content-Type`. Iki 48 MB.
2. `POST /documents` su `fileId` ir `companyId` – failas tampa įmonės dokumentu. Jis atsiranda **Gautieji** ir yra nuskaitomas kaip bet kuris kitas.

Nepanaudoti failai ištrinami po paros.

## Keitimai be išsaugojimo ir versijos

* `PATCH` užklausos su `?dryRun=true` parodo, kas pasikeistų, bet nieko neišsaugo.
* Įmonės instrukcijų keitimui reikia antraštės `If-Match` su versija, kurią redagavote. Be jos – `428 PRECONDITION_REQUIRED`, jei kas nors pakeitė tarp jūsų skaitymo ir rašymo – `412 PRECONDITION_FAILED`.

## Administratoriaus patvirtinimas

Kai kurių pakeitimų raktas ar AI agentas negali atlikti vienas. Šiuo metu tai įmonės AI agentų nustatymų keitimas. Tokia užklausa atsako `403 APPROVAL_REQUIRED`:

```json
{
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "This change needs an agency admin's approval.",
    "details": { "approvalId": "...", "approvalUrl": "https://jusu-agentura.skaitra.com/admin/approvals/...", "expiresAt": "...", "reason": "..." }
  }
}
```

Agentūros administratorius atidaro `approvalUrl`, peržiūri pakeitimus ir spaudžia **Patvirtinti**. Tada pakartokite tą pačią užklausą su antrašte `Approval-Id`. Patvirtinimas galioja parą ir tinka vienam kartui. Laukiančius prašymus administratorius mato ir skiltyje **Nustatymai → API raktai**.

## Užklausų riba

Vienu raktu ar prieigos raktu galima siųsti iki 600 užklausų per minutę. Viršijus ribą, API atsako `429 RATE_LIMITED` su antrašte `Retry-After: 60`.

## Klaidos

Klaida visada grąžinama tokiu pavidalu:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "hint": "Ką galite padaryti",
    "details": { "issues": [] }
  }
}
```

`code` yra stabilus – pagal jį rašykite logiką. `message` ir `hint` skirti žmogui ir yra anglų kalba.

| HTTP     | `code`                                                       | Reikšmė                                                                 |
| -------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
| 400, 422 | `VALIDATION_ERROR`, `INVALID_CURSOR`                         | Neteisinga užklausa; `details.issues` nurodo laukus                     |
| 401      | `INVALID_API_KEY`                                            | Rakto nėra, jis neteisingas, pasibaigęs, atšauktas arba kitos agentūros |
| 403      | `INSUFFICIENT_SCOPE`                                         | Raktui trūksta teisės (`details.requiredScopes`)                        |
| 403      | `COMPANY_ACCESS_DENIED`, `FORBIDDEN`                         | Nėra prieigos prie įmonės ar veiksmo                                    |
| 403      | `FEATURE_NOT_INCLUDED`                                       | Funkcija neįtraukta į agentūros planą (`details.feature`)               |
| 403      | `APPROVAL_REQUIRED`, `APPROVAL_PENDING`, `APPROVAL_REJECTED` | Reikia administratoriaus patvirtinimo arba jis dar nepriimtas           |
| 404      | `NOT_FOUND`                                                  | Nerasta arba šiam raktui nematoma                                       |
| 409      | `IDEMPOTENCY_KEY_IN_USE`, `CONFLICT`                         | Užklausa su tuo pačiu raktu dar vykdoma arba konfliktas                 |
| 412      | `PRECONDITION_FAILED`                                        | Įrašas pasikeitė nuo jūsų skaitymo (`If-Match`)                         |
| 413      | `PAYLOAD_TOO_LARGE`                                          | Failas didesnis nei 48 MB                                               |
| 415      | `UNSUPPORTED_MEDIA_TYPE`                                     | Netinkamas failo tipas                                                  |
| 422      | `IDEMPOTENCY_KEY_REUSED`                                     | `Idempotency-Key` panaudotas kitai užklausai                            |
| 428      | `PRECONDITION_REQUIRED`                                      | Reikia `If-Match`                                                       |
| 429      | `RATE_LIMITED`                                               | Per daug užklausų                                                       |
| 500      | `INTERNAL_ERROR`                                             | Skaitros klaida                                                         |
| 503      | `STORAGE_UNAVAILABLE`                                        | Saugykla laikinai nepasiekiama                                          |

> Kaip prisijungti prie Skaitros API, kaip veikia raktai, klaidos, puslapiavimas ir pakartotinės užklausos.