ZZI d.o.o., Pot k sejmišču 33, 1231 Ljubljana-Črnuče. estoritve FRP. Opis vmesnika

Transcription

1 ZZI d.o.o., Pot k sejmišču 33, 1231 Ljubljana-Črnuče estoritve Opis vmesnika Datum spremembe:

2 ZZI 2/19 Zgodovina dokumenta ZGODOVINA VERZIJ Ver. Opis spremembe Avtor Datum 1 Osnovna verzija Andraž Franjko

3 ZZI 3/19 Kazalo 1.1 NAMEN DOKUMENTA Zakaj ZZI estoritve? ZZINET PAKET OVOJNICA Struktura ovojnice Določitev predala pošiljatelja Računovodski servis Določitev predala banke prejemnice OPIS SPLETNIH FUNKCIJ WSDL DLL RPC Echo Login senddocument transformdocumentbytype DODATNE UPORABNE FUNKCIJE DLL KNJIŽNICE usessl usetest EHRAMBA ehrambagetaccounts ehrambagetdocumentlist POŠILJANJE DOSTOP DO DOKUMENTOV V EHRAMBI POSLANI DOKUMENTI PREJETI DOKUMENTI 17

4 ZZI 4/ PRIJAVA V SISTEM 18

5 ZZI 5/19 1 UVOD 1.1 NAMEN DOKUMENTA Namen dokumenta je prikazati način integracije in procesni tok med ZZI estoritve in ERP Zakaj ZZI estoritve? Storitve in omrežja elektronske izmenjave (RIP ali EDI) zagotavljajo izmenjavo formalnih standardnih dokumentov med poslovnimi partnerji in njihovimi sistemi. Cilj je čim bolj avtomatizirati procese in poslovanje med partnerji. Glavno vodilo ZZI je zagotoviti odprtost poslovanja - povezovanje omrežij, avtomatizacijo postopkov, podporo vsem standardom, možnost konverzij, vključevanje zunanjih rešitev in s tem zagotoviti možnost enostavnega poslovanja s poljubnimi partnerji in sistemi za velike in majhne. Storitveno vodilo povezovanja z vsemi funkcijami v oblaku za majhna in velika podjetja je lahko splošen opis estoritev ZZI. Skupaj s partnerji zagotavljamo več neodvisnih storitev, ki smo jih združili na enotni platformi, ki zagotavlja povezovanje podjetij in izvajanje procesov med partnerji. Odprtost za različne procese, povezave, protokole in tipe dokumentov smo opredelili kot osnovno lastnost naših storitev.

6 ZZI 6/19 2 STRUKTURA PAKETOV ZZINET 2.1 ZZINET PAKET Preko omrežja ZZInet se prenašajo ZZInet paketi. ZZInet paket je zip datoteka s standardno strukturo in je sestavljena iz naslednji datotek: Ovojnica (envelope.xml) Dokument Priloge dokumentu 2.2 OVOJNICA Struktura ovojnice Ovojnica mora biti v paketu in mora biti poimenovana na enega izmed spodnjih načinov: - ime datoteke vsebuje besedo»envelope«in se konča s končnico».xml«ovojnica (datoteka envelope.xml v paketu) je sestavljena iz treh sklopov in sicer: Podatki za usmerjanje dokumenta <from> <e_address>si hq</e_address> <e_location>c:si </e_location> <physical-address> <name>pošiljatelj d.o.o.</name> <address>cesta k pošiljatelju 1, LJUBLJANA</address> </physical-address> </from> <to> <e_location>c:si </e_location> <physical-address> <name>prejemnik d.o.o.name> <address>cesta k prejemniku 1, LJUBLJANA </address> </physical-address> </to>

7 ZZI 7/19 parametri <params> <param Name="Sender" Value="Računovodski servis XY>"/> <param Name="Receiver" Value="Banka YX"/> <param Name="Client" Value="Komitent XXX"/> </params> Informacije o dokumentih in prilogah <document> <external_id> </external_id> <file_name>sp_02_ _desito_#19.xml</file_name> <description>sp_02_ _desito_#19</description> </document> <attachments> <document> <file_name>sp_02_ _desito_#19.xlsm</file_name> </document> </attachments> Struktura ovojnice je podrobna opisana v priloženi xsd datoteki zzienvelope.xsd: Določitev predala pošiljatelja Računovodski servis <from> <e_address>si hq</e_address> <e_location>c:si </e_location> <physical-address> <name>pošiljatelj d.o.o.</name> <address>cesta k pošiljatelju 1, LJUBLJANA</address> </physical-address> </from> Bistvena podatka ob pošiljanju dokumenta sta e_location in e_address. e_location predstavlja lokacijo, iz katere pošiljamo dokument. Za potrebe izmenjave dokumentov se v e_location vpisuje identifikacijska številka podjetja (primer C:SI ). e_address predstavlja točno določen kanal (ZZInet predal) iz katerega se pošilja dokumente. Če e_address polja ni prisotnega v ovojnici pomeni, da se pošilja iz privzetega kanala za pošiljanje na omrežju. V takem primeru omrežje samodejno uporabi za pošiljanje privzeti kanal in ga tudi zapiše v polje e_address. Opomba: priporočeno je, da se polje e_address vselej vpisuje ob pošiljanju. Tako se lahko zagotovi, da poslovni sistem pošilja vselej dokumente iz točno določenega kanala.

8 ZZI 8/ Določitev predala banke prejemnice <to> <e_address1>si </e_address1> <e_location>c:si </e_location> <physical-address> <name>banka XY</name> <address>ulica 123</address> <po_code>1000</po_code> <po>ljubljana</po> </physical-address> </to> e_location predstavlja lokacijo, na katero pošiljamo dokument. Za potrebe izmenjave dokumentov se v e_location vpisuje identifikacijska številka banke, ki je prejemnik dokumenta (primer C:SI ). Pred davčno številko je potrebno dodati predpono C: e_address predstavlja točno določen kanal (ZZInet predal) na katerega se pošilja dokumente. Če e_address polje v ovojnici ni prisotno pomeni, da se pošilja na privzet kanala za prejem. V takem primeru omrežje samodejno uporabi za pošiljanje privzeti kanal in ga tudi zapiše v polje e_address.

9 ZZI 9/19 3 OPIS FUNKCIJ 3.1 OPIS SPLETNIH FUNKCIJ WSDL WSDL do testnega sistema estoritve se nahaja na naslednjem naslovu: WSDL do produkcijskega sistema estoritve se nahaja na naslednjem naslovu: Za pridobitev podatkov za prijavo na testnem ter na produkcijskem okolju se je potrebno obrniti na podjetje ZZI d.o.o. Andraž Franjko, Andraz.Franjko@zzi.si Podpora uporabnikom, podpora@zzi.si V primeru, da podjetje, ki želi pošiljati dokumente, še ni registrirano na sistemu bizbox, se registracijo izvede na način, ki je opisan v dokumentu: catid=1&m=0&itemid=397&lang=sl-si DLL Do estoritev se lahko dostopa tudi s pomočjo DLL, ki ga zagotavlja ZZi. DLL je treba registrirati RPC RPC funkcije so na testnem okolju dostopne preko URLja RPC funkcije so na produkcijskem okolju dostopne preko URLja

10 ZZI 10/ Echo Metoda: String echo(string s) Opis: Funkcija echo je namenjena preverjanju aktivnosti seje in hkrati preverjanju delovanja omrežja ZZInet. Vhodni parametri: s (niz znakov(guid)) V vhodni parameter s se lahko vpiše poljuben znakovni niz, ki ga funkcija vrne nazaj. Rezultat: echoreturn (niz znakov) V primeru ko vpišemo veljaven GUID funkcija vrne tekst v naslednji obliki: GUID 'guid' pripada uporabniku: 'Uporabniško ime'. Če funkcija vrne enak znakovni niz kot smo ga posredovali v vhodnem parametru s pomeni, da je omrežje dostopna, vendar guid ni veljaven. DLL: procedure checkguid(const instr: WideString; out Result: WideString); Nabor vrednosti za Result: o 0: guid ne priprada nobenemu uporabniku o 1: guid je veljaven RPC: HTTP metoda: POST URL:./echo Funkcija: public String echo( String s) Login Metoda: String login(string username, String password) Opis: Prijave v omrežje Vhodni parametri: username (niz do 100 znakov) uporabniško ime za dostop do omrežja ZZInet. password (niz znakov) geslo za dostop do omrežja ZZInet Rezultat: guid (36 znakov) identifikacija uporabnikove seje. Seja traja 60 minut od zadnje aktivnosti. Guid se nadalje uporablja ob klicu vseh ostalih funkcij. DLL: procedure login(const username: WideString; const password: WideString; out GUID: WideString); RPC: HTTP metoda: POST URL:./login Funkcija: public String login( String username,

11 ZZI 11/19 String password) senddocument Metoda: String senddocument(string guid, boolean isarchived) Opis: Pošiljanje dokumenta v omrežje ZZInet. Pošilja se ZZInet paket, ki je SOAP zahtevi dodan kot priloga (SOAP Attachment) Vhodni parametri: guid (niz znakov, obvezen) identifikacija uporabnikove seje isarchived (boolean, obvezen) informacija za prenos paketa v zakonsko skladno dolgoročno hrambo ehramba.si o o true dokument se arhivira false dokument se NE arhivira paket (.ZIP, obvezen) Priponka(SOAP Attachemnt) v formatu.zip. Vsebovati mora ovojnico (envelope.xml) in dokumente s pripadajočimi prilogami. Ovojnica mora biti sestavljene glede na shemo zzienvelope.xsd. Rezultat: docid (integer) docid je identifikacija številka, ki jo dobi posamezen dokument v omrežju. DLL: procedure senddocumentfn(const documentfn: WideString; const isarchived: WideString; out Result: WideString); documentfn vsebuje podatek o poti (absolute path) do začasne ZIP datoteke (ZZInet paket). RPC: HTTP metoda: POST URL:./sendDocument Funkcija: public String senddocument( String guid, boolean isarchived, byte[] pack) Opomba: klic ne sme biti opravljen s podajanjem parametrov preko URLja, ampak v samo telo zahtevka. Vrednost parametra pack mora biti kodirana v Base64 obliki in znotraj narekovajev ("").

12 ZZI 12/ transformdocumentbytype Vhodni parametri: guid (niz znakov, obvezen) identifikacija uporabnikove seje, guid dobimo s klicem funkcije login. eaddress (niz znakov, obvezen) informacija o ZZInet kanalu pošiljatelja. Za več informacij kontaktirajte ZZI. docb64encoded (niz znakov, obvezen) Excel datoteka, ki jo želimo poslati, kodirana v obliki Base64. doctype (fiksno: ) docformatin (fiksno: EXCEL ) docformatout (fiksno: XML.ZRS ) Rezultat: transformdocumentbytypereturn (niz znakov) Dokument, pretvorjen v XML obliko in zakodiran v obliko Base DODATNE UPORABNE FUNKCIJE DLL KNJIŽNICE usessl Metoda: procedure usessl(const issecure: WideString); Opis: Procedura omogoča izbor dostopa do spletnih storitev preko varne SSL povezave Vhodni parametri: issecure (niz znakov) o 'False': povezava ne poteka preko varne SSL povezave (privzeta vrednost) o 'True' povezava omogočena preko varne SSL povezave usetest Metoda: procedure usetest(const istestenv: WideString) Opis: Procedura omogoča izbor med testni in produkcijskim okolje estoritev Vhodni parametri: istestenv (niz znakov) o 'False': dostop do testnega okolja estoritev (privzeta vrednost) o 'True': dostop do produkcijskega okolja estoritev 3.3 EHRAMBA Opomba: metode so namenjene tistim subjektom, ki uporabljajo storitev samodejnega vlaganja izmenjanih dokumentov v ehrambo ehrambagetaccounts Metoda: String ehrambagetaccounts(string guid)

13 ZZI 13/19 Opis: Metoda omogoča pridobitev seznama računov ehramba.si do katerih ima uporabnik dostop Vhodni parametri: guid (niz 36 znakov, obvezen) enolični identifikator posamezne uporabnikove seje. Rezultat: XML s podatki računov, do katerih ima uporabnik dostop. RPC: <ACCOUNTS> <ACCOUNT> <!--Id računa--> <ID>1383</ID> <!--naziv računa v ehramba.si--> <NAME>SI HQ</NAME> <!--Opis računa--> <DESCRIPTION>Avtomatska ehramba</description> </ACCOUNT> </ACCOUNTS> HTTP metoda: POST URL:./eHrambaGetAccounts Funkcija: public ACCOUNTS ehrambagetaccounts( String guid) ehrambagetdocumentlist Struktura klica metoda je enaka kot pri metodi getdocumentlist (glej točko 3.1.6), le da se namesto parametra taxnumber uporablja parameter accountname. Metoda: String ehrambagetdocumentlist (String guid, String accountname, String filterxml) Opis: Funkcija vrača listo dokumentov, ki ustrezajo pogojem zapisanim v filterxml Vhodni parametri: guid (niz 36 znakov, obvezen) enolični identifikator posamezne uporabnikove seje. accountname (niz znakov, obvezen) ime računa ehrambe (Primer: SI HQ) filterxml (niz znakov) filter v obliki XML. Določa pogoje za pridobitev liste dokumentov. filterxml naj bo obdan s CDATA. Če je parameter filterxml prazen funkcija vrne seznam še neprevzetih dokumentov. Rezultat: XML z listo dokumentov, ki ustrezajo pogojem RPC:

14 ZZI 14/19 HTTP metoda: POST URL:./eHrambaGetDocumentList Funkcija: public DOCUMENTS ehrambagetdocumentlist( String guid, String accountname, FILTERS filter) Opomba: filter mora biti podan v JSON obliki. Primer: { "filter": [ { "name": "ACCEPTED", "value": "true", "operator": "=" } ] }

15 ZZI 15/19 4 DOBRE PRAKSE 4.1 POŠILJANJE Pošiljanje dokumentov poteka v naslednjih korakih: Preverjanje aktivnosti seje (WS: echo) Primer: V podatkovni bazi je shranjena zadnja veljavna seja za uporabnika. S funkcije echo se preveri ali je seja še aktivna. Če je seja aktivna so je uporabi v nadaljnjih klicih funkcij, sicer se kliče funkcijo login, da se pridobi novo vrednost parametra guid, ki enolično označuje sejo. Prijava v omrežje (WS: login)

16 ZZI 16/19 Primer: Funkcijo se kliče v primeru, ko je predhodna seja uporabnika potekla oziroma ob prvi prijavi v sistem. Konverzija dokumenta iz Excel v XML obliko (WS: transformdocumentbytype) Primer: Imamo Excel datoteko, ki jo želimo poslati. Pred pošiljanjem je potrebno datoteko pretvoriti v ustrezno XML obliko. Pošiljanje paketa (WS: senddocument) Primer: Podjetje želi poslati račun na UJP (Uprava za javna plačila). V omrežje pošlje ZZI paket s primerno ovojnico za distribucijo dokumenta. Omrežje ZZInet ovojnico pretvori na način, da jo UJP sistem razume in jo dostavi. Shranjevanje id poslanega paketa Primer: Ob pošiljanju dokumenta funkcija kot rezultat vrne identifikacijsko številko paketa docid. To številko ERP zapiše v podatkovno bazo, tako da lahko kasneje ob prejemu povratnice povratnico veže na dotični dokument. 4.2 DOSTOP DO DOKUMENTOV V EHRAMBI POSLANI DOKUMENTI Ob uspešnem klicu metode senddocument pridobimo ZZInet ID (primer ). Pridobljen ZZInet ID je tudi metapodatek (MSG_ID), s katerim lahko dostopamo do hranjenega dokumenta. To naredimo v naslednjih korakih: Klic metode ehrambagetdocumentlist z naslednjimi parametri: o o o guid accountname (Primer: SI HQ) filterxml primer: <FILTERS> <FILTER> <NAME>MSG_ID</NAME> <OPERATOR>=</OPERATOR> <VALUE> </VALUE> </FILTER> </FILTERS> getstatusbymsgidresponse vrne listo dokumentov, ki ustrezajo pogoju. Iz te liste preberemo metapodatek ID. <DOCUMENTS> <DOCUMENT> <ID> </ID> <EXTERNAL_ID> </EXTERNAL_ID> <TITLE>Račun št 60</TITLE> Klic metode ehrambareceivedocument z metapodatkom ID iz prejšnjega koraka, ki ga zapišemo v parameter docid: o guid o docid (Primer: )

17 ZZI 17/19 ehrambareceivedocumentreturn vrne željeni dokument v obliki priponke (SOAP Attachemnt) PREJETI DOKUMENTI Ob prejemu dokumenta iz ovojnice (envelope.xml) preberemo podatek ID, ki je tudi metapodatek (MSG_ID), s katerim lahko dostopamo do hranjenega dokumenta. To naredimo v naslednjih korakih: Primer ovojnice (envelope.xml) iz katere preberemo ID. <envelope> <header> <id> </id> <from> Klic metode ehrambagetdocumentlist z naslednjimi parametri: o o o guid accountname (Primer: SI HQ) filterxml primer: <FILTERS> <FILTER> <NAME>MSG_ID</NAME> <OPERATOR>=</OPERATOR> <VALUE> </VALUE> </FILTER> </FILTERS> getstatusbymsgidresponse vrne listo dokumentov, ki ustrezajo pogoju. Iz te liste preberemo metapodatek ID. <DOCUMENTS> <DOCUMENT> <ID> </ID> <EXTERNAL_ID> </EXTERNAL_ID> <TITLE>Račun št 61</TITLE> Klic metode ehrambareceivedocument z metapodatkom ID iz prejšnjega koraka, ki ga zapišemo v parameter docid: o guid o docid (Primer: ) ehrambareceivedocumentreturn vrne željeni dokument v obliki priponke (SOAP Attachemnt).

18 ZZI 18/19 5 POŠILJANJE DOKUMENTOV PREK SPLETNEGA VMESNIKA V nadaljevanju je opisan postopek pošiljanja in pregledovanja poslanih dokumentov v sistemu enabiralnik. 5.1 PRIJAVA V SISTEM BIZBOX V sistem bizbox.eu se prijavimo z veljavnim uporabniškim imenom in geslom. Povezava do testnega sistema je: Povezava do produkcijskega sistema je: Pošiljanje dokumenta Po uspešni prijavi kliknemo na meni enabiralnik in iz njega izberemo možnost Pošlji Dokument. Ta del navodil bo dopolnjen naknadno, ko bo spletna aplikacija zaključena.

19 ZZI 19/ Pregled poslanih dokumentov: Po uspešni prijavi kliknemo na meni enabiralnik in iz njega izberemo možnost enabiralnik: Prikaže se okno, podobno spodnjemu: Na levi strani v drevesni strukturi najprej izberemo Poslano > Vrste dok > Ostalo. Prikažejo se nam vsi poslani dokumenti, razvrščeni so po datumu, od najnovejšega proti najstarejšim.