Integracija AI agentams

Glaustas, agentams skirtas F-sąskaita API aprašymas. Bazinis URL, autentifikacija, specifikacijos vieta, puslapiavimas, klaidų apdorojimas ir taisyklės, padedančios išvengti dažnų klaidų.

Šis puslapis skirtas LLM agentams ir programavimo asistentams. Jis sąmoningai glaustas. Žmonėms gali būti patogesni gidai.

Faktai

Bazinis URL: https://app.fsaskaita.lt/api
OpenAPI 3.1 specifikacija: https://docs.fsaskaita.lt/openapi.json
Visa dokumentacija tekstu: https://docs.fsaskaita.lt/lt/llms-full.txt
Autentifikacija: Authorization: Bearer <token>. Prieigos raktas priklauso vienam verslui; naudotojo lygio ar kelių verslų prieigos rakto nėra.
Visada siųskite Accept: application/json. Be jo neautentifikuotos ir užklausų limitą viršijusios užklausos vietoj JSON grąžina HTML peradresavimą arba puslapį.
Sąskaitų faktūrų ir profilio turinio tipas: application/json. Išlaidos naudoja multipart/form-data, nes kartu siunčiamas failas.
Užklausų limitas: 60 užklausų per minutę vienam verslui, bendras visiems jo prieigos raktams. Skaitykite X-RateLimit-Remaining; gavę 429, laukite Retry-After sekundžių.
Puslapiavimas: ?page=N, fiksuotai 50 įrašų puslapyje, filtravimo ar rikiavimo parametrų nėra. Atsakymo forma { "data": [...], "meta": { "current_page", "last_page", "per_page", "total", "from", "to", "path" } }.
Pavieniai resursai įvilkti: { "data": { ... } }.
Identifikatoriai yra UUID eilutės. Datos – YYYY-MM-DD. created_at ir updated_at – Unix laiko žymos sekundėmis. Pinigų sumos – JSON skaičiai. Valiutų kodai – didžiosiomis raidėmis pagal ISO 4217 ir privalo būti GET /currencies sąraše.
Šalinimas grąžina 200 su tuščiu atsakymo turiniu.
Validacijos klaidos grąžina 422 su { "message": "...", "errors": { "field.path": ["..."] } }. Pranešimai yra lietuvių kalba.
Kitam verslui priklausantys resursai grąžina 404.

Taisyklės, padedančios išvengti klaidų

Atnaujindami sąskaitą faktūrą per PUT /invoices/{id}, siųskite visą sąskaitą, įskaitant jos dabartinį invoice_number. Nenurodžius numerio, priskiriamas naujas numeris iš serijos skaitiklio.
Kiekvienai sąskaitos eilutei siųskite lygiai vieną iš price, total arba total_incl_vat. Kitus du serveris apskaičiuoja pats.
type reikšmės, kurios baigiasi vat_invoice, yra PVM sąskaitos faktūros. Joms kiekvienoje eilutėje privalomas vat_percentage ir pardavėjo vat_code (kai use_default_seller_info yra true, imamas jūsų kodas iš profilio).
Rinkitės use_default_seller_info: true, nebent kviečiantysis aiškiai nori pakeisti pardavėjo duomenis.
Sąskaitų juodraščiai API niekada nerodomi. Viskas, ką API sukuria, yra užbaigta, sunumeruota sąskaita faktūra.
Jei PDF dar neparengtas, GET /invoices/{id}/download jo laukia iki maždaug 20 sekundžių, todėl kvieskite šį galinį tašką po sukūrimo, o ne tikėkitės failo kūrimo atsakyme.
Webhook pranešimų turinys yra { "event": "<name>", "data": { ... } }, pasirašytas neapdoroto turinio HMAC-SHA256 parašu antraštėje Signature. Prieš pasitikėdami turiniu, patikrinkite jį su prenumeratos paslaptimi. Pristatymas bandomas iki 3 kartų (du pakartojimai – po 10 s ir po 100 s); laikykite juos „bent vieną kartą“ pristatymais.
Prieigos raktų ar webhook prenumeratų valdymo API nėra. Abu kuria žmogus programėlėje, skiltyje Nustatymai, Integracijos.
Idempotentiškumo rakto nėra. Nekartokite POST užklausos, kuri grąžino tinklo klaidą, prieš tai neperžiūrėję naujausių sąskaitų sąrašo.

Instrukcijos jūsų agentui

Įklijuokite tai į savo programavimo agentą arba nurodykite jam https://docs.fsaskaita.lt/agents/prompt.md.

Instrukcijos agentuiAtverti kaip tekstą

Implement invoicing in this project with the F-sąskaita API.

Read first, in this order:
1. https://docs.fsaskaita.lt/llms.txt — the index of every documentation page. Fetch the Invoices and Conventions guides from it.
2. https://docs.fsaskaita.lt/openapi.json — the Spec: every endpoint, field and enum.
Take field names and behaviour from the Spec. Where this prompt and the Spec disagree, the Spec wins.

Facts
- Base URL: https://app.fsaskaita.lt/api. JSON in, JSON out.
- Authentication: a Business token, scoped to one business, sent as `Authorization: Bearer <token>`. Read it from the FSASKAITA_TOKEN environment variable and keep it out of code, logs and version control.
- Send `Accept: application/json` on every request; without it, 401 and 429 responses are HTML.
- Rate limit: 60 requests per minute per business. On 429, wait `Retry-After` seconds, then retry.
- Validation errors: 422 with `{ "message", "errors": { "field.path": ["..."] } }`. Messages are in Lithuanian; show them to the user unchanged.
- Lists: `?page=N`, 50 per page, newest first, no filters. Single resources are wrapped in `{ "data": ... }`.
- Identifiers are UUIDs, dates are `YYYY-MM-DD`, money values are JSON numbers, currency codes are uppercase ISO 4217 and must appear in `GET /currencies`.

Build
1. One client module with a narrow interface: base URL, both headers, JSON encoding, and typed errors for 401, 404, 422, 429 and 500. Retry only on 429, and only GET, PUT and DELETE.
2. createInvoice(input): `POST /invoices`. Default `use_default_seller_info: true`. For each line in `products` send exactly one of `price`, `total` or `total_incl_vat`. Types ending in `vat_invoice` need `vat_percentage` on every line. Omit `invoice_number` so the series assigns the next one. Return `data` from the 201 response; it includes `share_link`, a public page where the buyer views and downloads the invoice.
3. downloadInvoicePdf(id): `GET /invoices/{id}/download`, called after create. Stream the body: there is no Content-Length, and the response can take up to about 20 seconds if the PDF is not ready yet.
4. updateInvoice(id, input): `PUT /invoices/{id}` replaces the whole invoice. Read it first, change what you need, and send it back including the current `invoice_number`; an update without it renumbers the invoice.
5. Webhooks, when the project needs them: an HTTPS endpoint that verifies the `Signature` header (hex HMAC-SHA256 of the raw body with the subscription secret) before parsing, and treats deliveries as at-least-once.

Rules
- There is no idempotency key. After a network error on POST, list recent invoices with `GET /invoices` and check before creating again.
- Every invoice the API creates is final and numbered; drafts exist only in the app.
- Tokens and webhook subscriptions have no API. A person creates them in the app under Settings, Integrations, and the integration reads them from configuration.

Done when
- Unit tests with recorded responses cover 201, 422 and 429.
- A live check runs only when FSASKAITA_TOKEN is set. It creates a real, numbered invoice, so ask before running it and delete the invoice afterwards with `DELETE /invoices/{id}`.
- Your report names what you built, which endpoints you used, and what in the Spec you left out.

Minimali užklausa

curl https://app.fsaskaita.lt/api/profile \
  -H "Authorization: Bearer $FSASKAITA_TOKEN" \
  -H "Accept: application/json"

Kur žiūrėti toliau

Galinių taškų formos ir visi laukai: OpenAPI specifikacija arba Žinynas.
Išsamūs sąskaitų faktūrų užklausų pavyzdžiai: Sąskaitos faktūros.
Parašo tikrinimo kodas: Webhook pranešimai.
Elgsenos pokyčiai laikui bėgant: Pakeitimų žurnalas, taip pat pasiekiamas RSS formatu adresu /changelog.xml.