Skip Ribbon Commands
Skip to main content
Navigate Up
Sign In

Navodila

:

WEB_Services

MIT navodila za uporabo programa Orkester
​​​​

Orkester spletne storitve - WEB Services

Za administracijo dostopov in pravice je zadolžen administrator baze podatkov, ki s pravicami določa do katerih tabel ima spletni servis dostop. Spletni servis mora biti tudi zaščiten s SSL protokolom, ker se po spletu prenašajo zaupni podatki. Nekoliko manj varnostnega tveganja je, kadar spletna storitev ne seže izven lokalnega omrežja.

 

Administrator sistema se mora zavedati, da se v bazi hranijo tudi osebni podatki, ki jih obravnavajo zakoni v sklopu GDPR.​

Kazalo izpostavljenih poglavij

1.Namestitev na IIS

2.Testiranje v testnem okolju MIT

3.API vmesnik - skupno 

4.Branje podatkov iz tabel

5.Poizvedbe o tabelah in strukturi tabel

6.Šifranta parnerjev in artiklov - branje, pisanje, brisanje

7.Prejem dokumentov 

  • Iz spletne trgovine - NZO nalogi za odpemo
8. Nekatere bolj uporabljane tabele ​


1 Namestitev

1.1   IIS 

Namestitev se na IIS (Internet Information Services) strežnik izvede enako kot za druge spletne strani. MIT zagotovi paket datotek za namestitev, ki se prekopirajo na izbran imenik, do katerega ima dostop IIS. V kolikor SQL strežnik ni na istem strežniku kot IIS, potem je potrebno zagotoviti dostop do MS SQL strežnika, na katerem je nameščena MIT Orkester baza. Razlogi za onemogočen dostop so navadno v požarnem zidu – Privzeta vrata za korensko namestitev SQL strežnika je 1433).

Pravilna namestitev v WAN mora zaradi zaradi varnosti upoštevati sledeče:

  • Poseben IIS strežnik v DMZ samo z dostopom preko enih vrat v notranjo omrežje do SQL strežnika ali/in
  • Zapora dostopa na WS samo za točno določene IP naslove. 
  • Nameščen SSL protokol na IIS.
  • Nameščen SSL protokol na notranjem SQL strežniku in dostop samo s tem protokolom.
  • Minimalne pravice uporabnika omejene samo na izbrane tabele. 

1.2  Pravice na SQL strežniku

Administrator baze podatkov mora na SQL strežniku zagotoviti sledeče:

-          Uporabnika z geslom – SQL overitev (SQL server Authentification)

-          Pravice uporabnika za bralni dostop do posameznih tabel

-          Pravice uporabnika za bralno / pisalni dostop do tabel povezanih s polnjenjem podatkov (podrobnosti pri posebnih funkcijah)

-          Bralne pravice do tabel VSI_BAZABAZ, VSI_BAZAPOL, VSI_BAZAMIT za delovanje vpogleda v podatkovni slovar s strukturo tabel (apl/DataDictionary).¸

Administrator si lahko pri določanju pravic pomaga z vlogami (database roles). Z zagonom procedur (EXEC + ime procedure) VSI_CreateRoleMit_datareader, [dbo].[VSI_CreateRoleMit_datawriter] in [dbo].[VSI_CreateRoleMit_exec] se pripravilo vloge MIT_datareader_*, MIT_datawritter_* in MIT_exec. Uporabniku lahko potem samo dodelite članstvo. Je pa ta poenostavljen način primeren za notranje spletne storitve.

1.3  Dokumentacija spletnih servisov

Podrobno dokumentacijo dobite na samem portalu. Podrobnosti se nahajajo v zavihku API.

2    Testiranje v testnem okolju MIT

2.1        Testni portal MIT

Testni portal se nahaja na naslovu: https://demo.mit-ing.si/ws_orkester. Testni portal je namenjen preverjanju delovanja spletne storitve. 

POZOR: struktura tabel je lahko pri naročniku drugačna kot na testnem portalu!

Prijavni podatki na testni portal:

-          UserID: WS

-          Password: OsnovnoGeslo1

-          InitialCatalog: DEMO_SLO

-          DataSource: MITDEMO01\\SQL2016

2.2        Ali spletni servis deluje?  GET /api/values

Za testiranje delovanja je na voljo GET funkcija brez parametrov.

Storitev vrne string:

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Orkester Web Service, MIT informatika d.o.o.</string>

Primer:GET https://demo.mit-ing.si/WS_ORKESTER/api/values

2.3        Orodje za testiranje spletnega servisa

Za testiranje lahko uporabite različna orodja. Sami testiramo z: 

- Postman 

- Fiddler 

- <RESTED> doatek v Chrome ali Opera

JSON POST nize je potrebno dodati v telo poizvedbe.

2.4   Pogostejše napake

HTTP/1.1 415 Unsupported Media Type​: manjka oznaka Content-Type: application/json

405 - HTTP verb used to access this page is not allowed  na IIS niso omogočeni klici  PUT, DELETE,... več tukaj.

3 API vmesnik - skupno 

3.1        Niz za povezavo - connection

Objekt se imenuje connection. Za povezave je potrebno pridobiti od administratorja baze podatkov sledeče:

  • -          Ime uporabnika
  • -          Geslo
  • -          Naslov SQL strežnika
  • -          Ime baze podatkov

Podatke je potrebno posredovati pri vsaki poizvedbi v JSON obliki.

Primer povezovalnega niza:

{

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

}

3.2 API: Ime firme, ki ji pripada baza podatkov

API vrne osnovne podatke o firmi.

POST

https://demo.mit-ing.si/WS_ORKESTER/api/DataDictionary/CompanyData

BODY:

{

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

}


4 Branje podatkov iz tabel 

4.1  Pridobivanje podatkov iz poljubne tabele - /api/values  ali /api/select

Osnovna procedura  za vpoglede (SELECT) ene tabele je POST API, ki mu morate v telesu sporočila zagotoviti sledeče podatke:

-          Connection; podatki za povezavo na strežnik (glej zgoraj),

-          queryData elementi SELECT poizvedbe

o   ProcedureType: privzeto 0

o   TableName: ime tabele

o   FieldList: seznam polj v tabeli ali *

o   Where: filter na poizvedbo v formatu TSQL poizvedbe; če ni filtra potem je vrednost "".

Primer:

POST 

https://demo.mit-ing.si/WS_ORKESTER/api/values​

BODY

{

  "connection": {

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

  },

  "queryMeta": {

    "ProcedureType": 0,

    "TableName": "VSI_ARTIKLI",

    "FieldList": "SIFPRO,NAZIV,EM",

    "Where": "SIFPRO LIKE '11%'"

  }

}​



5 . Poizvedbe o tabelah in strukturi tabel - meta podatki , podatkovni slovar

5.1  Seznam vseh tabel v bazi z opisi

V ERP sistemu MIT Orkester je več kot tisoč tabel. Tabele so združene po področjih tako, da prve tri črke do podčrtaja praviloma določajo, kateremu programskemu paketu pripadajo.  
Funkcija vrne seznam čez tisoč tabel s kratkim opisom.

POST

https://demo.mit-ing.si/WS_ORKESTER/api/DataDictionary/TableList

BODY:

{

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

}

5.2     Seznam polj ene tabele z opisi

Strukturo tabele dobimo s klicem API TableDescription. Seznam vseh tabel dobimo z ukazom TableList.

POST

BODY:

{

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

}

6 . Šifranta artiklov in partnerjev 

6.1 Artikli - branje, insertiranje, brisanje

Za artikle so tri procedure api/Products:  

  • INSERT: PUT api/Products
  • UPDATE: POST api/Products?sifpro={sifpro}
  • DELETE: POST api/Products?sifpro={sifpro}

PUT:

https://demo.mit-ing.si/WS_ORKESTER/api/Products

Body:

{

  "connection": {

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

  },

 },
 "InsertMeta": {
  "FieldList":"SIFPRO,NAZIV",
  "Values": "'121','TOMAŽ BUREK'"
 }
}

 

POST:

Body:

{
 "Connection": {

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

 },
 "InsertMeta": {
  "FieldList":"SIFPRO,NAZIV",
  "Values": "'121','DOBER BUREK SPLOH'"
 }
}

 

DELETE:

https://demo.mit-ing.si/WS_ORKESTER/api/products​

Body:

{

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

}

 

6.2 Partnerji - branje, pisanje, brisanje

Za partnerje so tri procedure api/Products:  :  
  • INSERT: PUT api/Customers
  • UPDATE: POST api/Customers?sifrk={sifrk}
  • DELETE: POST api/Customers?sifrk={sifrk}


7 . Pošiljanje dokumentov

8.1 NZO Nalog za odpremo
Spletne trgovine praviloma pošiljajo spletna naročila v Naloge za odpremo. Nalog za odpremo je zahtevnica odpremni službi kaj in kdaj mora odpremiti. Iz naloga za odpremo ob odpremi nastane dobavnica in račun. Račun se prenese v saldakonte. Naloge za odpremo delimo na sledeče skupine glede na plačilo:
 - nalogi iz web naročila, kjer pred odpremo pričakujemo predplačilo,
 - nalogi, kjer je kupec naročilo že v celoti plačal preko spletne trgovine (imajo polno polje AVANS),
 - nalogi, kjer bo kupec plačal po povzetju.
Vse navedene procese je potrebno posebej načrtovati v MIT Orkestru in niso del spletnega vmesnika.

Spletni vmesnik za NZO pričakuje, da bodo šifranti med sistemoma usklajeni.
 - Šifrant artiklov mora biti enak kot v MIT Orkester.
 - Šifrant pogodb mora biti enako kot v MIT Orkester. Lahko se nastavi samo ena privzeta pogodba.

Šifrant kupcev lahko deluje na dva načina:
 - Šifra kupca mora obstajati v MIT Orkester. Če šifre ni, je dokument zavrnjen.
 - Šifre kupca se ne prenaša. Obvezen podatek je e-pošta. Če kupec s tako e-pošto obstaja, potem se ostali podatki kupca samo posodobijo v MIT Orkestru (naslov, pošta,...). Če e-naslov ne obstaja, potem se kupec doda v MIT-Orkester. 

Vse nastavitve spreminja administrator v Web.config na IIS strežniku. 

  <appSettings>

    <!--NZO prednastavitve prenosa-->

    <add key="NZO-POGODBA" value="" /><!--Če je ena pogodba lahko prednastavimo njeno vrednost. (prevzeto prazno)  -->

    <add key="NZO-SIFRK" value="" /> <!--V primeru, da je en sam partner za maloprodajo, dobijo vsi nalogi to šifro.(privzeto prazno) -->

    <add key="NZO-PopraviPartner" value="2" /> <!--Kako postopamo s partnerji:

        0-Šifra partnerja SIFRK mora biti vnešena in mora obstajati v VSI_PARTNER. Če NE uvoz prekinemo.

        1-Če ni SIFRK vnesen potem pogleda po E_NASLOV; če ne najde, potem novega partnerja doda v VSI_PARTNER

        2-Dela enako kot 1 in še popravi matične podatke v VSI_PARTNER, če tam partner že obstaja.  -->

    <add key="NZO-SpisekSQLprocedur" value="MEDEX_WEBSHOP_NZO" /> <!--Spisek SQL procedur, ki se v transakciji izvedejo po uspešnem insertu NZO. Več procedur ločimo z vejico. Proceduri program doda parameter NALOG. Primer OLMA_WEB_SHOP_NZO-->

    <add key="NZO-KontrolaVezniDokument" value="0" /> <!--Kontrola, če je bil STUVDOK že prenešen na NZO 1-DA 0-NE-->

    <add key="NZO-KontrolaExternoNarocilo" value="0" /> <!--Kontrola, če je bil EXNAR že prenešen na NZO 1-DA 0-NE-->

    <add key="NZO-SIFSKL" value="30" /> <!--Šifra skladišča iz katerega se vrši odprema.-->

  </appSettings>



​Entiteta

Polje

Opis polja

NZO Glava dokumenta

SifraKupca

Šifra kupca iz šifranta MIT Orkester. Če šifre ni vnešene, potem se kupce išče po e-naslovu <Enaslov>

 

Enaslov

Primarni klljuč kupca, če ni šifre kupca. Če e-naslova ni v šifrantu Mit Orkester, potem se kupec doda v šifrant.

 

NazivKupca

Osnovni naziv kupca -  obvezno

 

NazivKupca2

Dodatni naziv kupca - opcijsko

 

NaslovKupca

Uliča in hišna številka za dostavo - obvezno

 

PostaKupca

Poštna številka in pošta – obvezno

 

PostnaStevilka

Poštna številka – v skladu s šifrantom v MIT Orkester KAD_POSTE- opcija

​NacinPlacila ​​Način plačila - v skladu s šifrantom VSI_NACPL v MIT Orkester - opcija

 

TelefonKupca

Telefon kupca – ni obvezno – praviloma mora biti zaradi dostave

 

StevilkaDokumenta

Številka izvornega dokumenta – npr. številka spletnega naročila. Podatek mora biti unikaten.

 

Datum

Datum prenešenega dokumenta – obvezno

 

Avans

Znesek predplačila. Če je plačano v naprej preko spletne trgovine mora biti znesek enak vrednosti naročila z DDV. Lahko 0

 

Sklic

Številka sklica, po kateri bo kupec nakazal kupnino. Ni obvezno.

 

Pogodba

Številka pogodbe iz MIT Orkestra. Obvezno kadar je več cenikov ali več pogodb. Če je en cenik je lahko prazno.

​Tekst ​Besedilo dolžine do 200 znakov namenjeno podrobnostim o dostavi.

NZOPozicija

SifraIzdelka

Šifra izdelka iz šifranta MIT. Obvezno

 

Kolicina

Količina izdelka - obvezno

 

Cena

Cena izdelka brez DDV – obvezno

 

RabatProcent

Odstotek rabata na vrednost pozicije dokumenta. Med 0-99

 

PopustProcent

Ostotek popusta na vrednost pozicije. Med 0-99.

 

DavcnaOsnova

Vrednost pozicije z odštetimi rabati in popusti brez DDV. Če je 0 se izračuna samodejno iz zgornjih podatkov.

 

Davek

Znesek davka. Če je 0 se izračuna iz zgornjih podatkov.

 
Primer: 

PUT na naslov http://demo.mit-ing.si/WS_ORKESTER/Api/NZO
{
  "connection": {
    "DataSource": "MITDEMO01\\SQL2016",
    "InitialCatalog": "DEMO_SLO",
    "UserID": "WS",
    "Password": "OsnovnoGeslo1"
  },
  "NZO": {
    "SifraKupca": "",
    "Enaslov": "janez.novak@gmail.com",
    "NazivKupca": "Janez Novak",
    "NazivKupca2": "",
    "NaslovKupca": "Ljubljanska 54",
    "PostaKupca": "8333 SEMIČ",
    "PostnaStevilka": "SI-8333",
    "TelefonKupca": "041 466 493",
    "StevilkaDokumenta": "SN 12344/2020",
    "Datum": "2020-04-17",
    "Avans": 87.47,
    "Sklic": "0-20000194-107399",
    "Pogodba": "webSHOP",
    "Tekst":"Paket pustite pri sosedi pod stopnicami.",
    "NZOPozicija": [
      {
        "SifraIzdelka": "KOI00001",
        "Kolicina": 1.0,
        "Cena": 22.3689,
        "RabatProcent": 5.0,
        "PopustProcent": 0.0,
        "DavcnaOsnova": 0.0,
        "Davek": 0.0
      },
      {
        "SifraIzdelka": "KOI00002",
        "Kolicina": 2.0,
        "Cena": 26.5492,
        "RabatProcent": 5.0,
        "PopustProcent": 0.0,
        "DavcnaOsnova": 0.0,
        "Davek": 0.0
      }
    ]
  }
}

Odgovor, če ni napake:
{ "ErrorCode": 0, "Description": "OK - prenesen NZO / transfered order: 19000007 " }

Vsebinske napake:
Servis vrne napake v JSON obliki. Primer:
{ "ErrorCode": 1, "Description": "Ta dokument je bil že prenesen / This document has already been tranfered: SN 12344/2020" }​
Napake pri prenosu:

-          Connection to SQL server can't be made. Chech connection parameters!: napačni prijavni parametri na SQL (server/uporabnik/geslo) Instance serverjev morajo imedi dve poštevnici npr. MITDEMO01\\SQL2016

-          Partner ne obstaja / Customer does not exist {jNZO.NZO.SifraKupca} ! ; če pošiljate šifro kupca

-          Pogodba ne obstaja / contract does not exists

-          Poštna številka ne obstaja / Postoffice No does not exists

-          "Ta dokument je bil že prenesen / This document has already been tranfered:godba ne obstaja / contract does not exists …." ; če je kontrola na številko dokumenta

-          To eksterno naročilo je bilo že preneseno / This foreighn order  has already been tranfered:; Če je kontrola na številko naročila

-          Artikel ne obstaja / Product does not exist:

-          Napaka v JSON / JSON Error !: Poslani objekt ni JSON. Preveriti napake v JSON parserju.

-          NZO header is missing!: V JSON-u ni dela za glavo naloga

-          NZO items (NZOPozicija) are missing!: v JSON-u ni pozicij naloga z artikli ali pa so te nepravilno oblikovane.​ 


8 . Nekatere bolj uporabljane tabele 

8.1 Trenutne zaloge

Podatki o zalogah so pogosto vir poizvedb, zato klice navajamo posebej.

POST 

https://demo.mit-ing.si/WS_ORKESTER/api/values​

Body:

{

  "connection": {

    "DataSource": "MITDEMO01\\SQL2016",

    "InitialCatalog": "DEMO_SLO",

    "UserID": "WS",

    "Password": "OsnovnoGeslo1"

  },

  "queryMeta": {

    "ProcedureType": 0,

    "TableName": "VSI_ZALOGE",

    "FieldList": "[SIFSKL],[SIFPRO],[ZALOGA],[REZ],[NAROCENO],[PROSTO],[NA_PREDRAC],[NEK_IZ],[NEK_PR],[NAROCILA],[Q_PL]"

    "Where"; "SIFSKL LIKE 'IZD%'"

  }

}​