Kas yra INVOX API?

INVOX API – programinė sąsaja, per kurią su INVOX bendrauja kita sistema, o ne žmogus INVOX lange. Per ją dokumentai siunčiami apdoroti, o nuskaityti duomenys atsiimami atgal.

Daugumai apskaitos į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.

Kur tvarkomi API raktai ir webhook adresai

API raktai ir webhook adresai tvarkomi skiltyje Bendrieji nustatymai, skirtuke API. Šį skirtuką mato tik įmonės administratorius.

Nariui skirtukas nerodomas. Atvėręs adresą tiesiogiai, narys mato tik užrašą API raktus gali valdyti tik įmonės administratoriai. Žr. Kuo skiriasi administratorius ir narys?.

Skirtuke yra dvi kortelės: API raktai ir Webhook’ai. Mygtukas Sukurti raktą yra kortelės API raktai antraštėje, dešinėje, šalia API dokumentacija.

Ką galima daryti per API

Per API prijungta sistema gali:

• siųsti dokumentus į INVOX ir sekti, kas su jais vyksta, įskaitant nepriimtus failus;
• atsiimti sąskaitų faktūrų duomenis, kai jos pasiekia kliento sąrašą Sąskaitos;
• atsisiųsti originalų dokumento failą;
• priskirti apskaitos kodus sąskaitai faktūrai arba atskiroms jos eilutėms;
• pridėti ir tvarkyti įmones: pažymėti, ar įmonė yra jūsų klientas, ir keisti kliento nustatymus;
• tvarkyti 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 INVOX sąraše;
• 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 pranešimų eigą.

Per API atsiųstas dokumentas skiltyje Įkėlimas, stulpelyje Iš kur, pažymimas API. Žr. Kaip sekti gautus dokumentus?.

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. Netinkamos pradžios raktas atmetamas kodu INVALID_API_KEY.

Visi raktai prasideda invx_live_. Ši pradžia nesikeičia.

Raktui suteikiamos teisės. Skaitymas suteikiamas visada, o rašymas ir eksportas – atskirai. Trūkstant teisės, atsakoma 403 su kodu INSUFFICIENT_SCOPE. Žr. Kaip sukurti ir panaikinti API raktą?.

Ką raktas pasiekia

Vienas raktas priklauso vienai apskaitos įmonei ir pasiekia visus jos klientus. Kelias apskaitos į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 iš atsakymo negalima spręsti, ar toks įrašas kur nors egzistuoja.

Kur rasti techninę dokumentaciją

Interaktyvi dokumentacija pasiekiama adresu app.invox.lt/api-docs (atsidaro naujame skirtuke). Prisijungti nereikia, todėl nuorodą galite nusiųsti programinės įrangos tiekėjui nesuteikdami jam prieigos prie INVOX.

Skirtuke API nuoroda API dokumentacija yra kortelės API raktai viršuje, dešinėje. Ji atsidaro naujame naršyklės skirtuke.

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ą?.

Kaip siųsti dokumentus

Dokumentą galima siųsti dviem būdais:

• Viena užklausa. Failas siunčiamas kartu su užklausa.
• Tiesioginis įkėlimas trimis žingsniais. Pirmiausia jungtis praneša failo pavadinimą, tipą, dydį ir kontrolinę sumą. Atsakyme ji gauna vienkartinę nuorodą, kuria įkelia failą. Galiausiai jungtis praneša, kad įkėlimas baigtas.

Tiesioginis įkėlimas dar prieš siunčiant failą atsako, ar jis nėra per didelis, netinkamo tipo ar dublikatas. Gautą nuorodą reikia panaudoti per 15 minučių.

Abiem būdais failas turi būti iki 50 MB. Nepriimtas failas gauna atsakymą su klaidos kodu:

Kodas	Reikšmė
FILE_TOO_LARGE	Failas didesnis nei 50 MB
UNSUPPORTED_FILE_TYPE	Tokio tipo failų INVOX nepriima
CORRUPT_FILE	Failas tuščias, sugadintas arba neatitinka savo tipo
DUPLICATE_UPLOAD	Toks failas jau atsiųstas

Kokius failus galima siųsti, žr. Kokius failus galima įkelti?.

Nepriimtas failas, išskyrus per didelį, lieka API įkėlimų sąraše kaip atmestas įrašas su priežastimi. Netinkamo tipo ar sugadinto failo INVOX nepasilieka, todėl jo atsisiųsti nebegalima.

Dublikatas atmetamas, kai sistemos nustatymuose įjungtas Atmesti dublikatus. Žr. Kaip INVOX atpažįsta dublikatus?.

Ribos, kurių reikia laikytis

Kas ribojama	Riba
Užklausos iš viso	600 per minutę vienam raktui
Dokumentų siuntimas, abu būdai kartu	60 per minutę vienam raktui
Eksporto užsakymai	10 per minutę vienam raktui
Pranešimai apie klaidas	5 per minutę vienam raktui
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.

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

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 completed, partial arba failed;
• užbaigto darbo failas atsisiunčiamas. Jei programa duomenis gauna tiesiogiai, pvz., B1, Finvalda API ar iTax.lt API, failo nėra.

Būsena partial reiškia, kad dalis sąskaitų faktūrų eksportuota, o kitos atmestos su priežastimis.

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 eksportuota sąskaita faktūra atmetama iškart.

Paruoštas failas saugomas tiek pat, kiek ir eksporto įrašas, o laukas expiresAt visada null. Jei failo nebėra, atsakoma 410 su kodu EXPORT_EXPIRED – eksportą užsakykite iš naujo.

Kas pasikeitė API sąsajoje

Jei jungtis kurta anksčiau, atkreipkite dėmesį į šiuos pakeitimus:

• Tiesioginis įkėlimas. Atsirado antrasis dokumentų siuntimo būdas trimis žingsniais. Senasis būdas veikia toliau.
• Nepriimti failai matomi. Atmestas failas lieka įkėlimų sąraše su priežastimi, o atsakyme grąžinamas jo uploadId. Įkėlimų sąraše per API matomi ir el. paštu ar iš Google Drive gauti bei INVOX lange įkelti failai, įskaitant nepriimtus. Iš kur failas atėjo, nurodo laukas source.
• Nauja source reikšmė mobile. Ja pažymimi failai, kuriuos jūsų klientas atsiuntė telefono programėle. Ta pati reikšmė ateina ir webhook pranešime.
• Nauja klaida CORRUPT_FILE. Ja atmetamas ir failas, kurio pradžia tinkama, bet turinys neperskaitomas.
• Ar įmonė yra klientas. Įmonės įraše yra laukas clientStatus su reikšmėmis CLIENT, NOT_CLIENT arba UNDECIDED. Senasis isFavorite dar veikia. Pakeitus clientStatus iš CLIENT, panaikinami ir šios įmonės priskyrimai komandos nariams.
• Kliento nustatymai. Per API galima keisti kliento apskaitos programą, eilučių vaizdą, nulinių eilučių laikymą ir automatinį valiutos keitimą. Pakeitus programą, kliento taisyklės (skiltis Eksportas ir apskaita, skirtukas Taisyklės) iš naujo pritaikomos sąskaitoms faktūroms, kurios jau yra sąraše Sąskaitos, bet dar neeksportuotos. Taip vyksta ir pakeitus programą INVOX lange. Sąskaitų faktūrų laukai atnaujinami netrukus po užklausos, ne jos metu. Žr. Kaip veikia taisyklės, kurios užpildo laukus?.
• Nauji formatai. integrationType reikšmių sąraše atsirado RODA, ITAX, FINVALDA_API ir ITAX_API.
• Numatytieji partnerio kodai pašalinti. Jų nustatymo per API nebėra. Kaip kodai parenkami dabar, žr. Kaip nustatyti numatytuosius kodus įmonei?.
• Valiutos keitimas. Sąskaitos faktūros duomenyse laukas conversion nurodo, iš kokios valiutos ir kokiu kursu sumos perskaičiuotos.
• Eksporto failai saugomi neribotai. Failas saugomas tiek pat, kiek eksporto įrašas, o laukas expiresAt visada null.
• Dokumento tipas. Sąskaitos faktūros duomenyse atsirado laukas documentType su reikšmėmis INVOICE, CREDIT_NOTE, DEBIT_NOTE, ADVANCE, RECEIPT arba null. Reikšmė null reiškia, kad tipas nenustatytas, ir toks dokumentas laikomas sąskaita faktūra.
• Tikslinamos sąskaitos faktūros. Naujas laukas correctedInvoices – sąskaitų faktūrų, kurias dokumentas tikslina, sąrašas su number ir date. Kai data nežinoma, date yra null. Kai tikslinamų sąskaitų faktūrų nėra, sąrašas tuščias.
• docType rodo tipą, o ne sumos ženklą. Reikšmė creditinvoice grąžinama tik tada, kai documentType yra CREDIT_NOTE. Anksčiau ją lėmė neigiama suma. Dabar sąskaita faktūra su neigiama suma grąžinama kaip invoice.
• Kreditinės sąskaitos faktūros ir neigiama suma eksporte. Kreditinė sąskaita faktūra eksportuojama visais formatais, išskyrus APSKAITA5, CENTAS_API ir RIVILE_API. Kreditinė sąskaita faktūra su teigiama suma arba ne eurais neeksportuojama jokiu formatu. Dokumentas, kuris nėra kreditinė sąskaita faktūra, bet jo suma su PVM ar be PVM neigiama, taip pat neeksportuojamas jokiu formatu. Visais šiais atvejais eksporto darbo sąraše items[] dokumento outcome yra failed, o reason – credit_note_unsupported. Tuo pačiu kodu jis nurodomas ir sąraše errors[]. Žr. Nepavyko eksportuoti: ką daryti?.

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

• Neveikia iš naršyklės. API kviečiama tik iš jungties serverio, ne iš tinklalapio.
• Nekuria ir nepanaikina raktų. Tai daroma INVOX nustatymuose – žr. Kaip sukurti ir panaikinti API raktą?.
• Neregistruoja webhook adresų. Jie pridedami INVOX nustatymuose. Jei jungtis neturi periodiškai klausinėti apie naujus dokumentus, INVOX gali pranešti pats – žr. Kaip nustatyti webhook adresą?.
• Nepakeičia pačios jungties. Raktas yra tik prieigos priemonė, o kviečiančiąją pusę dar reikia sukurti.

Susiję straipsniai

• Kaip sukurti ir panaikinti API raktą?
• Kaip nustatyti webhook adresą?
• Kaip eksportuoti duomenis į apskaitos programą?
• Kuo skiriasi administratorius ir narys?