API nustatymai

API skiltis leidžia vartotojams susikurti unikalų prieigos raktą (API key), kuris naudojamas integracijoms su kitomis sistemomis, įrankiais ar paslaugomis. Tai yra saugus ir efektyvus būdas pasiekti jūsų dokumentų duomenis programiniu būdu.

API dokumentacija (Swagger). Ji pasiekiama registruotiems vartotojams https://app.beelogic.io/api-docs.

Kaip susikurti API raktą?

1. Eikite į Vartotojo nustatymus → API skiltį.

2. Spauskite Sukurti naują API raktą.

3. Sistema sugeneruos unikalų raktą.

4. Nukopijuokite raktą iš karto – jis vėliau nebebus matomas dėl saugumo priežasčių.

⚠️ Svarbu: Jei pametėte API raktą, turėsite sukurti naują – senasis taps negaliojantis, kai jį ištrinsite arba pakeisite.

API raktų naudojimas

Kaip naudoti API raktą

Įtraukite savo API raktą į x-api-key antraštę kiekvienoje užklausoje:

x-api-key: jūsų_API_raktas

Užklausų limitai (Rate Limits)

• Limitas: 30 užklausų per minutę vienam API raktui

• Laiko langas: 1 minutė

• Reakcija viršijus limitą: HTTP kodas 429 Too Many Requests

Swagger dokumentacija

Norėdami susipažinti su galimomis API užklausomis, jų struktūra ir atsakymais, naudokitės mūsų interaktyvia API dokumentacija (Swagger). Ji pasiekiama registruotiems vartotojams https://app.beelogic.io/api-docs.

🔗 Swagger nuoroda visada pateikiama po raktu ir yra atvira peržiūrai bei testavimui registruotiems vartotojams.

API užklausos (Endpoints)

1. Sąskaitos įkėlimas

POST /invoices/upload Įkelkite sąskaitos failą apdorojimui. Sistema palaiko įvairius failų formatus ir automatiškai ištrauks bei apdoros duomenis.

Užklausa

• Content-Type: multipart/form-data

• Body: Formos duomenys su failo lauku, kuriame yra sąskaitos failas

Palaikomi failų tipai

• PDF: application/pdf

• Word dokumentai: application/vnd.openxmlformats-officedocument.wordprocessingml.document

• Paveikslėliai: image/png, image/jpg, image/jpeg, image/webp

• Excel: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Failų dydžio limitai

• Maksimalus dydis: 10 MB vienam failui

Atsakymas

• Sėkmė: 201 Created

{
  "id": "string"
}

Galimos klaidos

• 400 Bad Request: netinkamas failo formatas arba per didelis failas

• 401 Unauthorized: API raktas neteisingas

• 429 Too Many Requests: viršytas užklausų limitas

• 500 Internal Server Error: serverio klaida

---

2. Sąskaitos būsenos tikrinimas

GET /invoices/status Patikrinkite įkeltos sąskaitos apdorojimo būseną. Grąžinamas esamas statusas ir galimos klaidos.

Užklausos parametrai

Parametras	Tipas	Privalomas	Aprašymas
id	string	Taip	Failo ID, gautas įkėlus sąskaitą

Atsakymas

• Sėkmė: 200 OK

[
  {
    "id": "string",
    "status": "PENDING",
    "error": "string"
  }
]

Galimos būsenos

• PENDING: failas laukia apdorojimo

• PROCESSING: failas šiuo metu apdorojamas

• COMPLETED: apdorojimas sėkmingai baigtas

• FAILED: apdorojimas nepavyko

Galimos klaidos

• 400 Bad Request: trūksta arba neteisingas failo ID

• 401 Unauthorized: API raktas neteisingas arba trūksta

• 404 Not Found: sąskaita nerasta

• 429 Too Many Requests: viršytas užklausų limitas

• 500 Internal Server Error: serverio klaida

---

3. Sąskaitos eksportas

GET /invoices/export Eksportuokite apdorotą sąskaitą nurodytu formatu ir schema. Atsakymas yra ZIP failas su eksportuotais duomenimis.

Užklausos parametrai

Parametras	Tipas	Privalomas	Numatyta reikšmė	Aprašymas
id	string	Taip	-	Failo ID
format	string	Taip	-	Eksporto formatas (xml)
schema	string	Taip	-	Eksporto schema (agnum-cloud-xml)
sumLines	string	Ne	true	Ar sumuoti eilutes
XmlDecimalSeparator	string	Ne	,	Skaičių skyriklis (. arba ,)

Palaikomi formatai ir schemos

• Formatas: xml

• Schema: agnum-cloud-xml

Atsakymas

• Sėkmė: 200 OK

• Content-Type: application/zip

• Body: ZIP failas su eksportuotais duomenimis

• Headeriai:

  Content-Disposition: attachment; filename="export.zip"
  Content-Length: [failo_dydis]

ZIP failo turinys

• supplier-0.xml, supplier-1.xml, ... – Tiekėjo duomenys

• customer-0.xml, customer-1.xml, ... – Kliento duomenys

Galimos klaidos

• 400 Bad Request: neteisingi parametrai, nepalaikomas formatas arba failas dar neapdorotas

• 401 Unauthorized: API raktas neteisingas arba trūksta

• 404 Not Found: sąskaita nerasta

• 429 Too Many Requests: viršytas užklausų limitas

• 500 Internal Server Error: serverio klaida

---

Klaidos ir jų apdorojimas

Dažniausi klaidų kodai

Statuso kodas	Aprašymas	Sprendimas
400	Netinkama užklausa	Patikrinkite parametrus ir failo formatą
401	Nepatikrintas	Patikrinkite API raktą
404	Nerasta	Įsitikinkite, kad failo ID egzistuoja
429	Per daug užklausų	Palaukite ir bandykite vėliau
500	Serverio klaida	Susisiekite su pagalba nurodydami klaidos ID

Klaidos atsakymo formatas

Struktūra kaip JSON su klaidos tipu, pranešimu ir (jei yra) error_id.