Kas yra INVOX API?
INVOX API – programinė sąsaja, per kurią su INVOX bendrauja kita įmonės sistema, o ne naudotojas portale. Per ją dokumentai siunčiami apdoroti, o nuskaityti duomenys atsiimami atgal.
Daugumai įmonių API nereikia. Duomenys į apskaitos programą perkeliami įprastu eksportu – žr. Kaip eksportuoti duomenis į apskaitos programą?. API verta svarstyti tada, kai jungtį kuria ar prižiūri programinės įrangos tiekėjas.
Ką galima daryti per API
Skyrius „Ką galima daryti per API“Per API prijungta sistema gali:
- siųsti dokumentus į INVOX ir sekti jų apdorojimą;
- atsiimti patikrintų sąskaitų faktūrų duomenis;
- atsisiųsti originalų dokumento failą;
- priskirti apskaitos kodus dokumentui arba atskiroms jo eilutėms;
- tvarkyti kontrahentus ir jų kodų sąrašus;
- užsakyti eksporto failą ir jį atsiimti;
- pažymėti sąskaitą faktūrą kaip eksportuotą – tai ta pati žyma, kurią matote portale;
- pašalinti sąskaitą faktūrą ir ją atstatyti – žr. Kaip pašalinti arba atstatyti sąskaitą faktūrą?;
- pranešti apie klaidingai nuskaitytą dokumentą ir sekti pateiktų pranešimų eigą.
Per API atsiųstas dokumentas įkėlimų sąraše pažymimas API. Taip portale matyti, kuriuo keliu jis pateko.
Kaip užklausos autentifikuojamos
Skyrius „Kaip užklausos autentifikuojamos“Kiekvienoje užklausoje siunčiamas API raktas. Jis rašomas antraštėje Authorization pagal Bearer schemą.
Kitokia antraštė netinka. Jos nesiuntus, atsakoma 401 su kodu MISSING_API_KEY, o netinkamos pradžios raktas atmetamas kodu INVALID_API_KEY.
Visi raktai prasideda invx_live_. Ši pradžia nesikeičia. Paties rakto INVOX nesaugo – lieka tik jo pradžia, paskutiniai keturi simboliai ir kriptografinis atspaudas.
Raktui suteikiamos teisės. Skaitymas suteikiamas visada, o rašymas ir eksportas – atskirai. Žr. Kaip sukurti ir atšaukti API raktą?.
Ką raktas pasiekia
Skyrius „Ką raktas pasiekia“Vienas raktas priklauso vienai įmonei. Kelias įmones apimančio rakto nėra, o kitos įmonės duomenų juo pasiekti negalima.
Nurodžius kitai įmonei priklausantį identifikatorių, atsakoma 404, o ne 403. Taip padaryta sąmoningai: iš atsakymo negalima spręsti, ar toks įrašas kur nors egzistuoja.
Kur rasti techninę dokumentaciją
Skyrius „Kur rasti techninę dokumentaciją“Interaktyvi dokumentacija pasiekiama adresu https://app.invox.lt/api-docs. Prisijungti nereikia, todėl nuorodą galite nusiųsti programinės įrangos tiekėjui neatverdami jam portalo.
Portale nuorodą API dokumentacija rasite raktų sąrašo viršuje, nustatymų skiltyje API. Ji atsidaro naujoje kortelėje. Šią skiltį mato tik įmonės administratorius.
Dokumentacija parengta tik anglų kalba – lietuviško varianto nėra.
Webhook parašų tikrinimas joje neaprašytas. Ką tikrinti gaunamoje užklausoje, žr. Kaip nustatyti webhook adresą?.
Ribos, kurių reikia laikytis
Skyrius „Ribos, kurių reikia laikytis“| Kas ribojama | Riba |
|---|---|
| Užklausos iš viso | 600 per minutę vienam raktui |
| Dokumentų siuntimas | 60 per minutę |
| Eksporto užsakymai | 10 per minutę |
| Pranešimai apie klaidas | 5 per minutę |
| Užklausos iš vieno IP adreso | 900 per minutę |
| JSON užklausos turinys | iki 2 MB |
| Siunčiamas failas | iki 50 MB |
Viršijus užklausų ribą, atsakoma 429. Antraštėje Retry-After nurodoma, po kiek sekundžių bandyti iš naujo. Per didelis turinys atmetamas kodu 413.
Antrą kartą atsiųstas tas pats failas atmetamas kodu 409 – žr. Kaip INVOX atpažįsta dublikatus?.
Ribos aprašo dabartinį INVOX veikimą, todėl jungtį verta kurti su atsarga.
Kiekvieno atsakymo antraštėje siunčiamas x-request-id. Rašydami support@invox.lt dėl konkrečios užklausos, nurodykite šią reikšmę.
Kaip veikia eksportas per API
Skyrius „Kaip veikia eksportas per API“Eksporto failas ruošiamas ne iš karto, todėl jis atsiimamas trimis veiksmais:
- jungtis užsako eksportą ir gauna darbo identifikatorių;
- jungtis klausia darbo būsenos, kol ji tampa užbaigta;
- užbaigto darbo failas atsisiunčiamas.
Būsenos klausinėjimas eksporto ribos neišnaudoja: jis skaičiuojamas prie bendrosios užklausų ribos.
Duomenų klaidos čia pasirodo ne iš karto. Užklausa priimama, o klaida grįžta kaip nepavykęs darbas su klaidų sąrašu. Jau eksportuotas dokumentas atmetamas iškart.
Paruoštas failas laikomas 7 dienas, o darbo įrašas – 30 dienų. Vėliau eksportą tenka užsakyti iš naujo.
Kaip API keičiasi
Skyrius „Kaip API keičiasi“Pakeitimai daromi tik pridedant. Atsiranda naujų laukų ir naujų reikšmių, o versija dėl to nesikeičia.
Todėl jungtis turi praleisti nežinomus laukus ir nesiremti baigtiniu reikšmių sąrašu. Rakto pradžia ir įvykių pavadinimai nekeičiami.
Ko API nedaro
Skyrius „Ko API nedaro“- Neveikia iš naršyklės. INVOX nesiunčia antraščių, kurios leistų kreiptis iš tinklalapio. API kviečiama tik iš serverio.
- Nekuria ir neatšaukia raktų. Tai daroma portale – žr. Kaip sukurti ir atšaukti API raktą?.
- Neregistruoja webhook adresų. Jie pridedami portale. Jei jungtis neturi periodiškai klausinėti apie naujus dokumentus, INVOX gali pranešti pati – žr. Kaip nustatyti webhook adresą?.
- Nepakeičia pačios jungties. Raktas yra tik prieigos priemonė, o kviečiančiąją pusę dar reikia sukurti.