Datum spremembe: 31.03.2017

eStoritve FRP

Opis vmesnika

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

ZZI 2/19

ESTORITVE INTEGRACIJA

Zgodovina dokumenta

ZGODOVINA VERZIJ

Ver. Opis spremembe Avtor Datum

1 Osnovna verzija Andraž Franjko 31.03.2017

ZZI 3/19

ESTORITVE

FRP

INTEGRACIJA

Kazalo

1.1 NAMEN DOKUMENTA 5

1.1.1 Zakaj ZZI eStoritve? 5

2.1 ZZINET PAKET 6

2.2 OVOJNICA 6

2.2.1 Struktura ovojnice 6

2.2.2 Določitev predala pošiljatelja – Računovodski servis 7

2.2.3 Določitev predala banke prejemnice 8

3.1 OPIS SPLETNIH FUNKCIJ 9

3.1.1 WSDL 9

3.1.2 DLL 9

3.1.3 RPC 9

3.1.4 Echo 10

3.1.5 Login 10

3.1.6 sendDocument 11

3.1.7 transformDocumentByType 12

3.2 DODATNE UPORABNE FUNKCIJE DLL KNJIŽNICE 12

3.2.1 useSSL 12

3.2.2 useTest 12

3.3 EHRAMBA 12

3.3.1 eHrambaGetAccounts 12

3.3.2 eHrambaGetDocumentList 13

4.1 POŠILJANJE 15

4.2 DOSTOP DO DOKUMENTOV V EHRAMBI 16

4.2.1 POSLANI DOKUMENTI 16

4.2.2 PREJETI DOKUMENTI 17

ZZI 4/19

ESTORITVE

FRP

INTEGRACIJA

5.1 PRIJAVA V SISTEM 18

ZZI 5/19

ESTORITVE

FRP

INTEGRACIJA

1

UVOD

1.1 NAMEN DOKUMENTA

Namen dokumenta je prikazati način integracije in procesni tok med ZZI eStoritve in ERP.

1.1.1 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.

ZZI 6/19

ESTORITVE

FRP

INTEGRACIJA

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

2.2.1 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>SI12345678.HQ</e_address>

<e_location>C:SI12345678</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:SI10000001</e_location>

<physical-address>

<name>Prejemnik d.o.o.name>

<address>Cesta k prejemniku 1, LJUBLJANA </address>

</physical-address>

</to>

ZZI 7/19

ESTORITVE

FRP

INTEGRACIJA

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>22255109</external_id>

<file_name>SP_02_22255109_FRPDesito_#19.xml</file_name>

<description>SP_02_22255109_FRPDesito_#19</description>

</document>

<attachments>

<document>

<file_name>SP_02_22255109_FRPDesito_#19.xlsm</file_name>

</document>

</attachments>

Struktura ovojnice je podrobna opisana v priloženi xsd datoteki zziEnvelope.xsd:

2.2.2 Določitev predala pošiljatelja – Računovodski servis

<from>

<e_address>SI12345678.HQ</e_address>

<e_location>C:SI12345678</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:SI85190586).

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.

ZZI 8/19

ESTORITVE

FRP

INTEGRACIJA

2.2.3 Določitev predala banke prejemnice

<to>

<e_address1>SI91132550</e_address1>

<e_location>C:SI91132550</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:SI85190586). 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.

ZZI 9/19

ESTORITVE

FRP

INTEGRACIJA

3

OPIS FUNKCIJ

3.1 OPIS SPLETNIH FUNKCIJ

3.1.1 WSDL

WSDL do testnega sistema eStoritve se nahaja na naslednjem naslovu:

http://demo.zzi.si/zziestoritve/services/EStoritve/wsdl/EStoritve.wsdl

WSDL do produkcijskega sistema eStoritve se nahaja na naslednjem naslovu:

https://ws.zzi.si/EStoritve/wsdl/EStoritve.wsdl

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:

http://www.bizbox.eu/si/index.php?option=com_jdownloads&task=download.send&id=3&

catid=1&m=0&Itemid=397&lang=sl-SI

3.1.2 DLL

Do eStoritev se lahko dostopa tudi s pomočjo DLL, ki ga zagotavlja ZZi. DLL je treba

registrirati.

3.1.3 RPC

RPC funkcije so na testnem okolju dostopne preko URLja

http://demo.zzi.si//zziestoritve/eStoritveRpc/EStoritve .

RPC funkcije so na produkcijskem okolju dostopne preko URLja

https://ws.zzi.si//zziestoritve/eStoritveRpc/EStoritve

ZZI 10/19

ESTORITVE

FRP

INTEGRACIJA

3.1.4 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)

3.1.5 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,

ZZI 11/19

ESTORITVE

FRP

INTEGRACIJA

String password)

3.1.6 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 true…dokument se arhivira o 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 ("").

ZZI 12/19

ESTORITVE

FRP

INTEGRACIJA

3.1.7 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: FRP )

docFormatIn (fiksno: EXCEL )

docFormatOut (fiksno: XML.ZRS )

Rezultat:

transformDocumentByTypeReturn (niz znakov)…Dokument, pretvorjen v XML obliko in zakodiran v obliko Base64.

3.2 DODATNE UPORABNE FUNKCIJE DLL KNJIŽNICE

3.2.1 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

3.2.2 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.

3.3.1 eHrambaGetAccounts

Metoda: String eHrambaGetAccounts(String guid)

ZZI 13/19

ESTORITVE

FRP

INTEGRACIJA

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.

<ACCOUNTS>

<ACCOUNT>

<!--Id računa-->

<ID>1383</ID>

<!--naziv računa v eHramba.si-->

<NAME>SI85190586.HQ</NAME>

<!--Opis računa-->

<DESCRIPTION>Avtomatska eHramba</DESCRIPTION>

</ACCOUNT>

</ACCOUNTS>

RPC:

HTTP metoda: POST URL: ./eHrambaGetAccounts

Funkcija: public ACCOUNTS eHrambaGetAccounts( String guid)

3.3.2 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:

SI85190586.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:

ZZI 14/19

ESTORITVE

FRP

INTEGRACIJA

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": "=" } ] }

ZZI 15/19

ESTORITVE

FRP

INTEGRACIJA

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)

ZZI 16/19

ESTORITVE

FRP

INTEGRACIJA

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

4.2.1 POSLANI DOKUMENTI

Ob uspešnem klicu metode sendDocument pridobimo ZZInet ID (primer 35253980).

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 guid o accountName (Primer: SI85190586.HQ) o filterXML

primer: <FILTERS>

<FILTER>

<NAME>MSG_ID</NAME>

<OPERATOR>=</OPERATOR>

<VALUE>35253980</VALUE>

</FILTER>

</FILTERS>

getStatusByMsgIdResponse vrne listo dokumentov, ki ustrezajo pogoju. Iz te liste preberemo metapodatek ID.

<DOCUMENTS>

<DOCUMENT>

<ID>5608227</ID>

<EXTERNAL_ID>1430000000001</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: 5608227)

ZZI 17/19

ESTORITVE

FRP

INTEGRACIJA

eHrambaReceiveDocumentReturn vrne željeni dokument v obliki priponke (SOAP

Attachemnt).

4.2.2 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>35253793</id>

<from>

Klic metode eHrambaGetDocumentList z naslednjimi parametri: o guid o accountName (Primer: SI85190586.HQ) o filterXML

primer: <FILTERS>

<FILTER>

<NAME>MSG_ID</NAME>

<OPERATOR>=</OPERATOR>

<VALUE>35253793</VALUE>

</FILTER>

</FILTERS>

getStatusByMsgIdResponse vrne listo dokumentov, ki ustrezajo pogoju. Iz te liste preberemo metapodatek ID.

<DOCUMENTS>

<DOCUMENT>

<ID>5608228</ID>

<EXTERNAL_ID>1430000000002</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: 5608228)

eHrambaReceiveDocumentReturn vrne željeni dokument v obliki priponke (SOAP

Attachemnt).

ZZI 18/19

ESTORITVE

FRP

INTEGRACIJA

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: https://demo.zzi.si/

Povezava do produkcijskega sistema je: https://www.bizbox.eu/

5.1.1 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.

ZZI 19/19

ESTORITVE

FRP

INTEGRACIJA

5.1.2 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.