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. Jis generuojamas iš to paties kontrakto, pagal kurį veikia Skaitra.

Adresas

API veikia jūsų agentūros adresu:

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

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:

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

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

API priima ir OAuth prieigos raktus, išduotus MCP klientams (žr. MCP).

Teisės

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).

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ų):

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:

{
  "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:

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