API: Skirtumas tarp puslapio versijų

Iš Lobasoft ERP apskaitos sistema.
Jump to navigation Jump to search
 
(nerodoma 14 tarpinių versijų, sukurtų to paties naudotojo)
4 eilutė: 4 eilutė:
  
 
* Autentifikavimas atliekamas ''basic authentication'' būdu.
 
* 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. Pavyzdžiui, trečio puslapio įrašų paėmimui siunčiama užklausa: <code>base_url/Items?$skip=1000&$top=500</code> (t.y. praleidžiama 2 puslapiai po 500 įrašų ir imami 500 įrašų iš trečio puslapio).
+
* 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: <code>base_url/Items?$skip=1000&$top=500</code> (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: <code>base_url/Items?$skip=1000&$top=500&$select=Key,Name,UpdatedAt</code>.
+
* 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: <code>base_url/Items?$skip=1000&$top=500&$select=Key,Name,UpdatedAt</code>.
 +
* 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 <code>base_url/Items?$skip=1000&$top=500&$select=Key,Name&$expand=ItemGroup($select=Name)</code>.
 +
* Įrašų filtravimui naudojamas $filter operatorius. Pvz.: prekių, kurios buvo koreguotos po 2021-01-01 d. paėmimui siunčiama užklausa <code>base_url/Items?$select=Key,Name,UpdatedAt&$filter=UpdatedAt+ge+2021-01-01</code>.
 +
** 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 <code>base_url/Items?$select=Key,Name,Barcode,UpdatedAt</code>.
 +
* Prekių sąrašas su nuotraukomis <code>base_url/Items?$select=Key,Name,Barcode,UpdatedAt&$expand=ItemFiles($select=FileName,ContentType)</code>.
 +
* Einamieji atsargų likučiai:
 +
** Užklausa grąžinanti likučius detalizuotai pagal sandėlius: <code>base_url/InventoryBalances</code>.
 +
** Užklausa grąžinanti likučius sumiškai nurodytuose sandėliuose: <code>base_url/InventoryBalances?locations=SND1,SND2</code>, 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: <code>base_url/InventoryBalances?$filter=UpdatedAt+ge+2021-09-06T12:00:00Z+and+Location/Key+eq+'Pagrindinis'</code>.
 +
** 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: <code>base_url/InventoryBalances?$filter=Quantity+ne+0</code>.
 +
** Kiekiai su rezervavimais apskaičiuojami iš likučių atimant atvirų užsakymų kiekius.
 +
* Pardavimo kainos <code>base_url/SalesPrices?$expand=Item($select=Key,Name,Barcode),SalesPriceList($select=Name)&$select=UnitPrice,UpdatedAt</code>.
 +
 
 +
== 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: <code>base_url/SalesInvoiceLines/Import</code>.
 +
* 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:
 +
 
 +
<pre>
 +
{
 +
    "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": "Paieškos kodas",
 +
                    "code": "Įmonės kodas",
 +
                    "name" "Pavadinimas"
 +
                }
 +
            }
 +
        }
 +
    ]
 +
}
 +
</pre>

Dabartinė 12:06, 25 spalio 2022 versija

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": "Paieškos kodas",
                    "code": "Įmonės kodas",
                    "name" "Pavadinimas"
                }
            }
        }
    ]
}