Kam skirtas API?
API yra programinė sąsaja, skirta integracijų kūrimui su kitomis informacinėmis sistemomis. Pvz. Jūsų turima el. parduotuvė gali kurti sąskaitas faktūras itax.lt sistemoje, gauti informaciją apie turimus atsargų likučius, prekių kainas ir t.t.
Trumpai tariant, API sąsaja skirta naudotis itax.lt sistema ne žmogui, o kitam kompiuteriui ir norint pasinaudoti šiomis galimybėmis reikia turėti bent minimalių programavimo žinių.
API leidžia automatizuotai gauti ir kurti duomenis (pirkėjai, tiekėjai, pardavimo sąskaitos, pirkimo sąskaitos, prekės, paslaugos, prekių likučiai sandėliuose, kainos ir t.t.) iš itax.lt
Pagal nutylėjimą, API prieiga yra išjungta. Norėdami susikurti šią prieigą, turite susikurti API raktą Įmonės nustatymuose.
Nustatymai -> API raktai
Galite susikurti neribotą skaičių API prieigos raktų. Pvz. skirtingoms sistemoms naudoti skirtingus raktus. Nebenaudojamus raktus panaikinkite.
API rakto pavadinimas - Jūsų suteiktas integracijos pavadinimas.
API vartotojo vardas - Sistemos sugeneruotas API prisijungimo vartotojas. API slaptažodis - API slaptažodis.
Dėmesio - sukūrus API raktą, sistema jums sugeneruos API vartotojo vardą ir slaptažodį. Slaptažodis bus rodomas tik vieną kartą po sukūrimo. Jei slaptažodį pamiršite nusikopijuoti, raktą ištrinkite ir susikurkite naują.
Prisijungimas
API V2 versija:
Kiekvieną kartą siunčiant API užklausą, turi būti siunčiama autentifikacijos informacija užklausos antraštėje (header). Autentifikavimas vykdomas naudojant API prisijungimo vardą ir slaptažodį. Naudojama Basic Auth autentifikacija.
Siunčiant POST užklausą, t.y. kuriant naują pirkėją/tiekėją/sąskaitą ir t.t. užklausos antraštėje (headeryje) reikia nurodyti "Content-Type: application/json" , nes kitu atveju bus klaidingai interpretuojami parametrai ir sulauksite klaidos pranešimo.
Ją ištestuoti paprasčiausia su Postman programa.
Arba komandinėje eilutėje
$ curl -u api_vartotojas:api_slaptazodis https://itax.lt/api/v2/invoices
GET užklausa (pirkėjų sąrašas)
pvz.: curl -u 6a5d6e3c7aa990a124553d:0548380f4d832aa38c314af https://itax.lt/api/v2/clients
POST užklausa (naujo pirkėjo sukūrimas)
curl -d '{"client":{"name":"Testas"}}' -u 6a5d6e3c7aa990a124553d:0548380f4d832aa38c314af -H "Content-Type: application/json" -X POST https://itax.lt/api/v2/clients
Arba užkoduojant antrašėje
curl -H 'Authorization: Basic < base64 užkoduotas API vartotojas ir slaptažodis >' https://itax.lt/api/v2/invoices
Užkoduojamas base64 vartotojo vardas ir slaptažodis
echo -n "6a5d6e3c7aa990a124553d:0548380f4d832aa38c314af" | base64
Gauname: NmE1ZDZlM2M3YWE5OTBhMTI0NTUzZDowNTQ4MzgwZjRkODMyYWEzOGMzMTRhZg==
curl -H 'Authorization: Basic NmE1ZDZlM2M3YWE5OTBhMTI0NTUzZDowNTQ4MzgwZjRkODMyYWEzOGMzMTRhZg==' https://itax.lt/api/v2/invoices
API V1 versija (nebegaliojanti):
Pirmoje API versijoje buvo naudojamas API raktas be vartotojo. API V1 versija veiks iki 2025 m. kovo 31 d. Todėl visas naujas integracijas kurkite API V2 versijai, taip pat V1 integracijas iki šios datos turite migruoti į V2 versiją.
Užklausos antraštėje turi būti nurodomas toks autentikacijos parametras Authorization: Token token="{api raktas}"
Pvz.:
$ curl https://itax.lt/api/v1/products -H 'Authorization: Token token="9d334f0942e31f3ada264f0"'
API sąsają pasieksite konstruojant tokį url https://itax.lt/api/{api versijos numeris}/{resursas}/{resurso id - jei prašoma konkretaus resurso informacijos}.
Šiuo metu naujausia API versija yra 2. Todėl užklausoje nurodoma v2 (v1 versija bus aktyvi iki 2025 m. kovo 31 d.).
Pvz.:
https://itax.lt/api/v2/invoices - gausite Pardavimo sąskaitų sąrašą.
https://itax.lt/api/v2/invoices/1254 - gausite konkrečią pardavimo sąskaitą.
API atsako į tokias užklausas:
GET - resursų sąrašas (pvz. GET https://itax.lt/api/v2/invoices) arba konkretus resursas (GET https://www.itax.lt/api/v1/invoices/1525)
POST - resurso sukūrimas (pvz. POST https://itax.lt/api/v2/invoices - bus kuriama nauja sąskaita pagal pateikiamus parametrus)
PUT - resurso atnaujinimas (pvz. PUT https://itax.lt/api/v2/invoices/1525 - bus atnaujinama sąskaita pagal pateikiamus parametrus)
DELETE - resurso ištrynimas (pvz. DELETE https://itax.lt/api/v2/invoices/1525 - bus ištrinta nurodyta sąskaita)
Dėmesio! Serveris tam pačiam vartotojui atsako max į 5 užklausas per sekundę (5r/s). Jei siunčiama daugiau užklausų, serveris grąžina 503 (Service Temporarily Unavailable) klaidą.
Siunčiant daug API užklausų, nustatykite pauzes tarp jų, kad į jas visas būtų atsakyta.
Parametrus patogiausia siųsti JSON formatu.
Pvz.:
{
"client": {
"name": "UAB Klientas",
"code": "12546849",
"default_currency": "LTL",
"payment_term": 30
}
}
Resursai
Per API galite gauti šių resursų duomenis:
clients - Pirkėjai
client_groups - Pirkėjų grupės
projects - Projektai
departments - Padaliniai
products - Prekės ir paslaugos
items - Prekės
services - Paslaugos
fixed_assets - Ilgalaikis turtas
invoices - Pardavimo sąskaitos
draft_invoices - Išankstinės sąskaitos
measurements - matavimo vienetai
product_groups - prekių grupės
sale_prices - pardavimo kainos
purchase_prices - pirkimo kainos
locations - sandėliai
supliers - tiekėjai
suplier_groups - tiekėjų grupės
purchases - pirkimo sąskaitos
sales_taxes - PVM tarifai
payment_documents - mokėjimo dokumentai
bank_accounts - banko sąskaitos
tags - žymos
bins - vietos sandėlyje
sales_order - pardavimo užsakymas
purchase_order - pirkimo užsakymas
sales_quote - pardavimo pasiūlymas
purchase_quote - pirkimo pasiūlymas
people - kontaktiniai asmenys (pirkėjo arba tiekėjo)
item_journals - atsargų žurnalai
item_transfer_journals - atsargų perkėlimo žurnalai
item_assembly_journals - atsargų komplektavimo žurnalai
crm_pipelines - CRM pardavimo procesai
crm_deals - CRM pardavimo galimybės
crm_activities - CRM užduotys
exports - savo sukurtos duomenų eksporto ataskaitos
general_journals - Bendrieji žurnalai
payment_journals - Mokėjimų žurnalai
Atsakymai į užklausas pateikiami JSON formatu. Jei resursas turi sąsajų su kitais resursais (pvz. pirkėjas priklauso pirkėjų grupei), tai jie sutrumpinta forma įtraukiami į atsakymą. Prie kiekvieno resurso pateikiamas URL, kuriuo pasieksite detalią resurso informaciją.
Pvz. norint gauti prekių sąrašą, reikia siųsti GET užklausą https://itax.lt/api/v2/products
Gaunamas atsakymas:
{ "response": [ { "url": "https://www.itax.lt/api/v2/services/192925", "id": 192925, "name": "Mokesciu konsultacijos", "code": null, "barcode": null, "for_sales": true, "for_purchases": true, "extended_description": null, "type": "Service", "is_active": true, "measurement_id": 5599, "product_group_id": null, "created_at": "2015-06-23T12:37:56.000+03:00", "updated_at": "2015-06-23T12:37:56.000+03:00", "measurement": { "url": "https://www.itax.lt/api/v2/measurements/5599", "id": 5599, "name": "vnt" }, "product_group": null, "sale_prices": [], "purchase_prices": [] }, { "url": "https://www.itax.lt/api/v2/services/192923", "id": 192923, "name": "Transportas", "code": "", "barcode": "", "for_sales": true, "for_purchases": true, "extended_description": "", "type": "Service", "is_active": true, "measurement_id": 5599, "product_group_id": null, "created_at": "2015-06-23T11:37:52.000+03:00", "updated_at": "2015-06-23T11:37:52.000+03:00", "measurement": { "url": "https://www.itax.lt/api/v2/measurements/5599", "id": 5599, "name": "vnt" }, "product_group": null, "sale_prices": [ { "url": "https://www.itax.lt/api/v2/sale_prices/159800", "id": 159800, "base": "fixed_price", "price": "1.0", "currency": "EUR", "surcharge_amount": null, "surcharge_percent": null, "product_id": 192923, "client_group_id": null, "created_at": "2015-06-23T11:37:52.000+03:00", "updated_at": "2015-06-23T11:37:52.000+03:00", "client_group": null } ], "purchase_prices": [ { "url": "https://www.itax.lt/api/v2/purchase_prices/159801", "id": 159801, "price": "0.5", "currency": "EUR", "product_id": 192923, "suplier_id": null, "created_at": "2015-06-23T11:37:52.000+03:00", "updated_at": "2015-06-23T11:37:52.000+03:00", "suplier": null } ] }, { "url": "https://www.itax.lt/api/v2/services/192922", "id": 192922, "name": "Konsultacijos", "code": "", "barcode": "", "for_sales": true, "for_purchases": true, "extended_description": "", "type": "Service", "is_active": true, "measurement_id": 5599, "product_group_id": null, "created_at": "2015-06-23T11:37:25.000+03:00", "updated_at": "2015-06-23T11:37:25.000+03:00", "measurement": { "url": "https://www.itax.lt/api/v2/measurements/5599", "id": 5599, "name": "vnt" }, "product_group": null, "sale_prices": [ { "url": "https://www.itax.lt/api/v2/sale_prices/159798", "id": 159798, "base": "fixed_price", "price": "100.0", "currency": "EUR", "surcharge_amount": null, "surcharge_percent": null, "product_id": 192922, "client_group_id": null, "created_at": "2015-06-23T11:37:25.000+03:00", "updated_at": "2015-06-23T11:37:25.000+03:00", "client_group": null } ], "purchase_prices": [ { "url": "https://www.itax.lt/api/v2/purchase_prices/159799", "id": 159799, "price": "50.0", "currency": "EUR", "product_id": 192922, "suplier_id": null, "created_at": "2015-06-23T11:37:25.000+03:00", "updated_at": "2015-06-23T11:37:25.000+03:00", "suplier": null } ] } ], "count": 3, "pagination": { "previous": null, "next": null, "current": 1, "per_page": 100, "count": 3, "pages": 1 } }
Užklausiant prekių sąrašo, prie prekės pateikiama jos bendro likučio (visuose sandėliuose) informacija.
Jei norite, kad prekių sąraše būtų tik vieno sandėlio likučiai, tai įtraukite sandėlio filtrą į užklausos url, pvz. https://www.itax.lt/api/v1/products?location_id=6683
GET https://itax.lt/api/v2/items
{ "response": [ { "url": "https://www.itax.lt/api/v2/items/192927", "id": 192927, "name": "Žibintas", "code": "", "barcode": "", "for_sales": true, "for_purchases": true, "extended_description": "", "weight": null, "volume": null, "type": "Item", "is_active": true, "measurement_id": 5599, "product_group_id": null, "created_at": "2015-06-23T13:01:53.000+03:00", "updated_at": "2015-06-23T13:01:53.000+03:00", "item_balance": { "qty": "2.0", "amount": "15.0", "qty_reserved": "0.0", "qty_on_hand": "2.0" }
Jei prašoma informacijos apie konkrečią prekę, tai pateikiama detali informacija - koks likutis yra skirtinguose sandėliuose.
GET https://itax.lt/api/v2/items/192927
{ "response": { "url": "https://www.itax.lt/api/v2/items/192927", "id": 192927, "name": "Žibintas", "code": "", "barcode": "", "for_sales": true, "for_purchases": true, "extended_description": "", "weight": null, "volume": null, "type": "Item", "is_active": true, "measurement_id": 5599, "product_group_id": null, "created_at": "2015-06-23T13:01:53.000+03:00", "updated_at": "2015-06-23T13:01:53.000+03:00", "item_balance": { "qty": "2.0", "amount": "15.0", "qty_reserved": "0.0", "qty_on_hand": "2.0", "locations": [ { "id": 4620, "name": "Vilniaus", "qty": "1.0", "amount": "5.0", "qty_reserved": "0.0", "qty_on_hand": "1.0" }, { "id": 4621, "name": "Kauno", "qty": "1.0", "amount": "10.0", "qty_reserved": "0.0", "qty_on_hand": "1.0" } ] }, "measurement": { "url": "https://www.itax.lt/api/v2/measurements/5599", "id": 5599, "name": "vnt" }, "product_group": null, "sale_prices": [] } }
{ "product": { "name": "Naujas pavadinimas" }
}
Duomenys pagal nutylėjimą yra puslapiuojami po 1000.
Parametrai naudojami puslapiavimui:
per_page - duomenų kiekis puslapyje (ne daugiau 1000)
page - puslapio numeris.
Puslapiavimo informacija pateikiama atsakymo apačioje:
"count": 3, "pagination": { "previous": null, "next": null, "current": 1, "per_page": 100, "count": 3, "pages": 1 }
Duomenų rūšiavimui naudojami šie parametrai:
sort - stulpelio pavadinimas
direction - asc arba desc
Duomenis filtruoti galima praktiškai pagal kiekvieną duomenų stulpelį . Tereikia į užklausą įtraukti jo pavadinimą ir reikšmę, pvz. client_group_id=15221
Filtruojama ir surūšiuota užklausa atrodo taip:
https://itax.lt/api/v2/invoices?client_id=74712&sort=created_at&direction=desc
Dėmesio, jei filtruojama pagal žymas, žymos parametras turi būti perduodamas kaip masyvas (tags[]=GPM), pvz.
https://itax.lt/api/v2/invoices?client_id=74712&tags[]=GPM
Pagal šią užklausą pateikiamos vieno pirkėjo sąskaitos faktūros surūšiuotos pagal sukūrimo datą mažėjančiai.
Norėdami sukurti sąskaitą, pirkėją, prekę ar pan. per API turite siųsti POST užklausą su atitinkamais parametrais.
Kuriant sąskaitą faktūrą, siunčiama POST užklausą https://itax.lt/api/v2/invoices
Pavyzdiniai parametrai (atkreipkite dėmesį į tai, kaip perduodama sąskaitos eilučių informacija):
{ "invoice":{ "date":"2015-06-23", "client_id":131721, "due_date":"2015-07-22", "currency":"USD", "inv_lines_attributes":[ { "product_id":192922, "price":10.10, "qty":2, "amount":20.20, "sales_tax_id":15198, "vat_amount":4.30, "total_amount":24.50 }, { "product_id":192923, "price":100, "qty":1, "amount":100, "sales_tax_id":15198, "vat_amount":21, "total_amount":121 } ] } }
Jei sąskaita bus sėkmingai sukurta, Jums bus grąžinta visa sukurtos sąskaitos informacija JSON formatu. Kitu atveju gausite klaidos pranešimą, su klaidos aprašymu (taip pat JSON formatu).
Pvz. klaidos pranešimas apie trūkstamą parametrą:
{ "error":"invalid_resource", "messages":{ "client_id":[ "turi būti užpildytas (-a)" ] } }
Išankstinių sąskaitų eilutės perduodamos su parametru "draft_inv_lines_attributes", pirkimo sąskaitos "purch_inv_lines_attributes"
Jei norite, kad sąskaita iš karto būtų užregistruota, reikia pridėti "posted" = true parametrą.
{
"invoice":{
"posted":true,
"date":"2015-06-23",
.........
Norint sąskaitą redaguoti per API, visų pirma reikią ją išregistruoti
PUT https://www.itax.lt/api/v1/invoices/1452478
{ "invoice":{ "posted":false } }
Modifikuojam sąskaitos eilutes ir ją užregistruojam ("posted"=true parametras).
Šiame pavyzdyje yra parodyti 3 variantai kaip galima modifikuoti sukurtos sąskaitos eilutes:
1. kai nurodytas sąskaitos eilutės ID bus modifikuojama eilutė su šiuo ID
2. kai nurodytas eilutės ID ir parametras _destroy (dėmesio - priekyje apatinis brūkšnys) - eilutė bus panaikinta
3. jei redaguojant sąskaitą eilutės ID nėra nurodytas - bus sukurta papildoma eilutė.
PUT https://itax.lt/api/v2/invoices/1452478
{
"invoice":{
"posted":true,
"date":"2020-10-01",
"client_id":43173,
"currency":"EUR",
"location_id":1684,
"is_shipping_address":true,
"shipping_address":"Pristatymo adresas",
"vat_aggregated": true,
"discount_amount": 14,
"inv_lines_attributes":[
{ "id":5663449,
"product_id":30854,
"price":60,
"qty":1,
"discount_amount":1,
"amount":59,
"sales_tax_id":5885,
"vat_amount":4,
"total_amount":63,
"reverse_vat":true
}, { "id":5663450,
_destroy:true },
{ "product_id":30854,
"price":20,
"qty":1,
"discount_amount":1,
"amount":19,
"sales_tax_id":5885,
"vat_amount":4,
"total_amount":23,
"reverse_vat":true
}
]
}
}
Prekė
POST https://itax.lt/api/v2/products
{ "product":{ "name":"Mokesčių konsultacijos", "type":"Service", "measurement_id":5599, "sales_tax_id":15198 } }
Parametre type nurodomas prekės tipas (paslauga - Service, atsarga - Item, ilgalaikis turtas - FixedAsset)
Mokėjimo dokumentas
POST https://www.itax.lt/api/v2/payment_documents
{ "payment_document":{ "date":"2024-04-20", "bank_account_id":2668, "currency":"EUR", "amount": 100, "account_balanceable_type": "Client", "account_balanceable_id":1113574, "posted":true } }
account_balanceable_type ir account_balanceable_id nurodoma kas atliko mokėjimą. Šiuo atveju mokėjimą atliko Pirkėjas. Jei būtų atliktas pavedimas iš kitos banko sąskaitos, tai reikėtų nurodyti: "BankAccount" ir atitinkamai jo id.
Jei pavedimu buvo apmokėta kažkuri sąskaita, tai papildomai nurodomas parametras invoice_id:
{ "payment_document":{ "date":"2024-04-20", "bank_account_id":2668, "currency":"EUR", "amount": 100, "account_balanceable_type": "Client", "account_balanceable_id":1113574, "invoice_id":2556718, "posted":true } }
Kontaktinio asmens sukūrimas
POST https://itax.lt/api/v2/people
{
"person":{
"contactable_id": 473211,
"contactable_type": "Client",
"name": "Petras Kliemis",
"email": "petras@gmail.com",
"position": "Vadybininkas"
}}
Atsargų žurnalo sukūrimas
POST https://itax.lt/api/v2/item_journals
Atsargų nurašymas
{
"item_journal":{
"location_id": 1684,
"name": "Atsargų nurašymas",
"date": "2018-11-27",
"posted": true,
"item_journal_lines_attributes":[{
"product_id":636348,
"qty": -2
}]
}}
Pajamavimas
{
"item_journal":{
"location_id": 1684,
"name": "Atsargų pajamavimas",
"date": "2018-11-27",
"posted": true,
"item_journal_lines_attributes":[{
"product_id":636348,
"qty": 2,
"total_cost": 10200
}]
}}
Perkėlimo žurnalo sukūrimas
POST https://itax.lt/api/v2/item_transfer_journals
{
"item_transfer_journal":{
"from_location_id": 1684,
"to_location_id": 9981,
"name": "Perkėlimas iš eshop",
"date": "2018-11-27",
"posted": true,
"item_transfer_journal_lines_attributes":[{
"product_id":636340,
"qty": 1
},
{
"product_id": 636347,
"qty": 2
},
{
"product_id": 636344,
"qty": 2
} ]
}}
Komplektavimo žurnalo sukūrimas
POST https://itax.lt/api/v2/item_assembly_journals
bom - ar kompletavimas vykdomas pagal prekės kortelėje aprašytą specifikaciją (tada nereikia nurodyti komplektavimo dalių)
part - kompletavimo dalis (true), komplektuojama nauja prekė (false)
{
"item_assembly_journal":{
"location_id": 1684,
"name": "Komplektavimas iš eshop",
"date": "2018-11-27",
"posted": true,
"bom": false,
"item_assembly_journal_lines_attributes":[{
"product_id":636348,
"qty": 1,
"part": false
},
{
"product_id": 636347,
"qty": 2,
"part": true
},
{
"product_id": 636344,
"qty": 2,
"part": true
} ]
}}
Bendrojo žurnalo sukūrimas
POST https://itax.lt/api/v2/general_journals
{ "general_journal":{ "name": "Testas", "posted": true, "general_journal_lines_attributes":[{ "date": "2023-10-12", "journable_type": "Client", "journable_id": 1113539, "journal_balanceable_type": "BankAccount", "journal_balanceable_id": 2668, "amount": 200, "currency": "EUR" }] }}
arba
{
"general_journal":{
"name": "Testas",
"posted": true,
"general_journal_lines_attributes":[{
"date": "2023-10-12",
"journable_type": "Client",
"journable_id": 1113539,
"amount": 200,
"currency": "EUR"
},
{
"date": "2023-10-13",
"journable_type": "BankAccount",
"journable_id": 20594,
"amount": -200,
"currency": "EUR"
}]
}}
Mokėjimų žurnalo sukūrimas
POST https://itax.lt/api/v2/payment_journals
{ "payment_journal":{ "name": "Testas", "posted": true, "payment_journal_lines_attributes":[{ "date": "2023-10-12", "journable_type": "Client", "journable_id": 1113539, "amount": 200, "currency": "EUR" }, { "date": "2023-10-12", "journable_type": "BankAccount", "journable_id": 20594, "amount": -200, "currency": "EUR" }] }}
Dokumento kūrimas su žymomis (tagais)
Norėdami kuriamam dokumentui priskirti žymas (tagus), turite pridėti papildomą parametrą all_tags, kuriame žymos pateikiamos masyve, pvz.:
POST https://www.itax.lt/api/v2/clients
{
"client":{
"name":"Testas",
"default_currency":"EUR",
"payment_term":30,
"all_tags":["Svarbu", "GPM"]
}
}
Norėdami per API gauti sąskaitą faktūrą (arba išankstinę sąskaitą) PDF formatu, turite siųsti tokią užklausą:
GET https://www.itax.lt/api/v1/downloads.pdf?document=invoice&id=324039
Parametrai:
document - invoice, sales_order, sales_quote, purchase_order, purchase_quote id - dokumento id template - spausdinamo dokumento šablonas. Naudojamas kai norima atspausdinti kito tipo dokumentą, pvz. išanktinę sąskaitą faktūrą iš pardavimo užsakymo. Galimos rekšmės: pro_forma_invoice, pick_list
Pvz. išansktinės sąskaitos spausdinimas iš užsakymo
GET https://www.itax.lt/api/v1/downloads.pdf?document=sales_order&id=324039&template=pro_forma_invoice
{ "email_message":{ "recipient_email":"client_email@gmail.com", "subject": "Sąskaita faktūra", "body": "Siunčiame sąskaitą faktūrą\n\nLinkėjimai\nRomas Romauskas", "sender_name": "Vadybininkas Romas Romauskas", "sender_email": "romas@gmail.com", "bcc_to_sender": true } }