API

Prieiga per API

Sistemos REST API įgyvendintas pagal OData standartą (žr. https://www.odata.org/getting-started/basic-tutorial/). OData metadatuomenys preinami adresu base_url/$metadata, kur base_url - bazinis bazės adresas.

• Autentifikavimas atliekamas basic authentication būdu.
• Užklausose turėtų būti naudojamas puslapiavimas - imama ne daugiau nei po 500 įrašų. Įrašų kiekis gali būti apribotas. Pvz.: prekių sąrašo trečio puslapio įrašų paėmimui siunčiama užklausa: base_url/Items?$skip=1000&$top=500 (t.y. praleidžiama 2 puslapiai po 500 įrašų ir imami 500 įrašų iš trečio puslapio).
• Užklausose turi būti nurodomi reikalingi laukai naudojant $select operatorių. Pvz.: jeigu iš prekių sąrašo reikalingas tik prekės kodas ir pavadinimas, siunčiama tokia užklausa: base_url/Items?$skip=1000&$top=500&$select=Key,Name,UpdatedAt.
• Susijusių įrašų paėmimui naudojamas $expand opreatorius. Pvz.: norint kartu su prekės duomenimis gauti informaciją apie prekės grupę, kuriai ta prekė priklauso, siunčiama užklausa base_url/Items?$skip=1000&$top=500&$select=Key,Name&$expand=ItemGroup($select=Name).
• Įrašų filtravimui naudojamas $filter operatorius. Pvz.: prekių, kurios buvo koreguotos po 2021-01-01 d. paėmimui siunčiama užklausa base_url/Items?$select=Key,Name,UpdatedAt&$filter=UpdatedAt+ge+2021-01-01.
  • Visos duomenų aibės turi lauką UpdatedAt, kurio pagalba galima paimti tik tuos įrašus, kurie yra pasikeitę.

Dažniausiai naudojamos užklausos

• Prekių sąrašas base_url/Items?$select=Key,Name,Barcode,UpdatedAt.
• Prekių sąrašas su nuotraukomis base_url/Items?$select=Key,Name,Barcode,UpdatedAt&$expand=ItemFiles($select=FileName,ContentType).
• Einamieji atsargų likučiai:
  • Užklausa grąžinanti likučius detalizuotai pagal sandėlius: base_url/InventoryBalances.
  • Užklausa grąžinanti likučius sumiškai nurodytuose sandėliuose: base_url/InventoryBalances?locations=SND1,SND2, kur SND1, SND2 - traukiamų į likučius sandėlių kodai.
  • Einamieji atsargų likučiai, pasikeitę po 2021-09-06 d. 12 val. ir esantys pagrindiame sandėlyje: base_url/InventoryBalances?$filter=UpdatedAt+ge+2021-09-06T12:00:00Z+and+Location/Key+eq+'Pagrindinis'.
  • Atsargų likučių užklausa grąžina atsargas ir su nuliniais likučiais (kad būtų galima matyti pasikeitimus ir tų atsargų, kurių nebėra). Jeigu reikalingi tik nenuliniai likučiai, siunčiama užklausa: base_url/InventoryBalances?$filter=Quantity+ne+0.
  • Kiekiai su rezervavimais apskaičiuojami iš likučių atimant atvirų užsakymų kiekius.
• Pardavimo kainos base_url/SalesPrices?$expand=Item($select=Key,Name,Barcode),SalesPriceList($select=Name)&$select=UnitPrice,UpdatedAt.

Pardavimo sąskaitų importas

• Pardavimų duomenys importuojami pardavimo sąskaitų eilučių lygmenyje. Jeigu kelios eilutės priklauso tai pačiai sąskaitai, tuomet turi būti pateikiami tie patys sąskaitos antraštės duomenys.
• Duomenys importuojami šiuo adresu: base_url/SalesInvoiceLines/Import.
• Kai kurių importuojamų objektų laukų paaiškinimai:
  • item/key - prekės kodas (turi būti aprašytas sistemoje).
  • location/key - sandėlio kodas (turi būti aprašytas sistemoje).
  • salesInvoice/transaction/externalNo - išorinis unikalus dokumentos numeris. Pagal šį numerį identfikuojama, ar dokumentas jau importuotas, ar dar ne.
  • salesInvoice/sellToEntity/key - pirkėjo paieškos kodas (turi būti aprašytas sistemoje).
• Importo duomenų struktūros pavyzdys:

{
    "salesInvoiceLines": [
        {
            "quantity": 1.0,
            "priceDC": 94.96,
            "taxAmount": 19.94,
            "priceInclTax": false,
            "taxRate": 21.0,
            "item": {
                "key": "$pvz"
            },
            "location": {
                "key": "$pvz"
            },
            "salesInvoice": {
                "transaction": {
                    "currency": {
                        "key": "EUR"
                    },
                    "date": "2022-07-01T00:00:00+02:00",
                    "description": "test_odata_import_1",
                    "externalNo": "test_odata_import_1"
                },
                "docDate": "2022-07-01T00:00:00+02:00",
                "sellToEntity": {
                    "key": "$pvz"
                }
            }
        },
        {
            "quantity": 3.00,
            "priceDC": 2.00,
            "taxAmount": 1.26,
            "priceInclTax": false,
            "taxRate": 21.0,
            "item": {
                "key": "$pvz2"
            },
            "location": {
                "key": "$pvz"
            },
            "salesInvoice": {
                "transaction": {
                    "currency": {
                        "key": "EUR"
                    },
                    "date": "2022-07-01T00:00:00+02:00",
                    "description": "test_odata_import_1",
                    "externalNo": "test_odata_import_1"
                },
                "docDate": "2022-07-01T00:00:00+02:00",
                "sellToEntity": {
                    "key": "$pvz"
                }
            }
        },
        {
            "quantity": 1.0,
            "priceDC": 94.96,
            "taxAmount": 19.94,
            "priceInclTax": false,
            "taxRate": 21.0,
            "item": {
                "key": "$pvz"
            },
            "location": {
                "key": "$pvz"
            },
            "salesInvoice": {
                "transaction": {
                    "currency": {
                        "key": "EUR"
                    },
                    "date": "2022-07-01T00:00:00+02:00",
                    "description": "test_odata_import_2",
                    "externalNo": "test_odata_import_2"
                },
                "docDate": "2022-06-01T00:00:00+02:00",
                "sellToEntity": {
                    "key": "$pvz"
                }
            }
        },
        {
            "quantity": 10.00,
            "priceDC": 2.00,
            "taxAmount": 4.20,
            "priceInclTax": false,
            "taxRate": 21.0,
            "item": {
                "key": "$pvz2"
            },
            "location": {
                "key": "$pvz"
            },
            "salesInvoice": {
                "transaction": {
                    "currency": {
                        "key": "EUR"
                    },
                    "date": "2022-07-01T00:00:00+02:00",
                    "description": "test_odata_import_2",
                    "externalNo": "test_odata_import_2"
                },
                "docDate": "2022-06-01T00:00:00+02:00",
                "sellToEntity": {
                    "key": "$pvz"
                }
            }
        }
    ]
}