Kaj je API?

API je kratica za Application Programming Interface in označuje programski vmesnik.

API pomaga pri sporazumevanju med programi, kot si človek pomaga z vprašanji in odgovori, ko želi pridobiti informacije. Če uporabljata enak jezik (enak API), se bosta razumela, v nasprotnem pa potrebujeta prevajalca. Enako je pri informacijskih sistemih. Če dva sistema ne uporabljata enakega standardnega API-ja, potrebujeta prevajanje. Za to poskrbijo strokovnjaki, ki jim običajno rečemo integratorji. Preučiti morajo posebnosti obeh API-jev in poskrbeti za ustrezno prevajanje med njima.

iCenter API trenutno podpira jezik "XML", s kodiranjem "UTF-8 BOM".

Tehnična dokumentacija:  https://icwebsvc.saop.si/SI/API

Primer Swagger testnega okolja: https://icwebsvc.saop.si/SI/API/swagger/ui/index

 

Nekaj pogostih primerov rabe Saop API-ja

• Uvoz izdanih računov (Osnutek računa)

Kot uporabnik želim iz zunanje aplikacije prenašati oziroma zapisati osnutke izdanih računov v ERP, z namenom izstavitve računov.

Zunanja aplikacija pripravi podatke o posameznem računu (stranka, datumi, artikel, količina, cena) in jih s klicem ustrezne metode (AddInvoice) zapiše v ERP. Dokument se v ERP preračuna in glede na proces poknjiži. Zunanja aplikacija lahko tak dokument tudi prebere z uporabo metode GetInvoice. V primeru, da želi zunanja aplikacija spreminjati osnutek računa, se za ta namen lahko uporabi metoda ModifyInvoice.

• Uvoz izdanih računov

Kot uporabnik želim iz zunanje aplikacije, v kateri se pripravljajo izdani računi (in se tudi izstavljajo),  v ERP zapisati finančni dogodek.

Glede na to, da se je račun pripravil in izstavil v zunanji aplikaciji, se v ERP prenaša samo finančna temeljnica in sicer tako, da se kliče metoda AddJournal.

• Uvoz prejetih računov

Kot uporabnik zunanje aplikacije želim, da se prejeti račun zapiše v ERP z namenom nadaljnje obdelave.

Prejeti račun se v ERP doda z metodo AddIncomingInvoice. V primeru, da ima prejeti račun eno ali več priponk, se le te doda v dokumentacijski sistem z metodo AddDocument .V primeru, da je prejeti račun v obliki eRačuna, se lahko uporabi eno od elektronskih poti ePoštarja.

• Oddaja spletnega naročila

Kot uporabnik spletne trgovine želim oddati oziroma zapisati naročilo v ERP za namene nadaljnje obdelave (izdaja blaga, izstavitev računa, finančno knjiženje).

Naročilo se v ERP zapiše z metodo AddOrder, vendar je pred tem potrebno pridobiti matične, podporne in ostale podatke in sicer:

Artikli: GetItems  

Stranke: GetCustomer (če stranka ne obstaja, se jo doda z AddCustomer)

Zaloge: GetStock

Cene: GetPrices

Naročilo se lahko, seveda dokler je v ustreznem statusu, tudi spreminja z metodo ModifyOrder oziroma se ga lahko pridobi v metodo GetOrder.

• Prevzem blaga  - WMS – napoved

Kot uporabnik WMS želim izvesti prevzem najavljenega blaga.

V ERP se na podlagi naročil dobavitelja pripravi predlog prevzema oziroma prevzem od dobavitelja. Zunanji sistem, z metodo GetReceivingAdviceStatus preverja, če je kakšen dokument v statusu primernen za prenos. Če tak dokument obstaja, ga prebere z metodo GetReceivingAdvice in nato z metodo ModifyReceivingAdvice postavi v tak status, kateri onemogoča spreminjanje dokumenta znotraj ERP.

Ko se dejanski prevzem v skladišču zaključi, se z metodo  ModifyReceivingAdvice uredi dokument v ERP in z metodo PostReceivingAdvice se ga materialno poknjiži.

• Prevzem blaga  - WMS – odprti prevzem

Kot uporabnik WMS želim izvesti prevzem nenajavljenega blaga.

Ko se dejanski prevzem v skladišču zaključi, se z metodo  AddReceivingAdvice zapiše dokument v ERP in se ga z metodo PostReceivingAdvice materialno poknjiži.

• Izdaja blaga  - WMS

Kot uporabnik zunanjega sistema želim zapisati izdajo blaga v ERP.

V zunanjem sistemu kot je na primer WMS, se pripravi blago za izdajo kot tudi pripadajoči spremni dokument. Ko se operacija v zunanjem sistemu zaključi, je potrebno dokument posredovati v ERP.

Glede na tip izdaje (najavljena, odprta, naročilo) se uporabi sledeče metode:

- Najavljena izdaja: WMS pripravi izdajo na podlagi prejete najave izdaje, ki jo je posredoval ERP. Ko se v ERP zaključijo aktivnosti se z metodo ModifyDispatchAdvice zapiše podatke o dejansko izdanih količinah v ERP.

- Odprta izdaja: Izdaja se zgodi v WMS in ker se je aktivnost začela v ERP, se dokument zapiše z metodo AddDispatchAdvice.

- Naročilo: ERP posreduje v  WMS eno ali več naročil. Na podlagi posredovanih naročil se pripravijo izdaje. Ko se zaključijo aktivnosti v zunanjem sistemu, le ta z metodo AddDispatchAdvice zapiše dokumente izdaje blaga in nato še delno ali v celoti zapre naročila.

V primeru, da velja eno naročilo ena izdaja, pa lahko zunanji sistem z metodo MoveOrderToDispatchAdvice pripravi izdajo v ERP in nato le to z metodo PostDispatchAdvice poknjiži.

Posebnosti v primeru uporabe "posebnih" znakov

V kolikor uporabljate "posebne" znake (navedeni spodaj) v šifri entitete, api metoda pa ima vrsto parametra  (Parameter type) za to entiteto "path"  in želite api metodo izvesti preko Swaggerja, to ne bo šlo, saj to orodje ne dovoli uporabo "posebnih" znakov; npr.:.

V ta namen boste za testiranje api metod morali uporabljati drugo orodje (npr. Postman) ter namesto "posebnega" zanka vpisati njegovo pretvorbo; npr.:

Pretvorniki posebnih znakov so: