NAVODILA ZA IZVEDBO KLICA PROGRAMA SimplyTax.exe
(ver 20.10.2015)
SIMPLYTAX.EXE <VrstaZahteve> <Delovanje> <SWid> < TxtDatoteka> <CertGeslo>
[RD#<ResponseDatoteka>] [QRV#<Velikost>] [QRT#<Tip>] [QRF#<Format>]
[CER#<PotDoCertifikata>] [DT#<ŠteviloSekund>] [/console] [/debug]
Prvih pet parametrov je obveznih, podati jih je potrebno natanko po navedenem vrstnem redu,
ostali so neobvezni (navedba v oglatih oklepajih ponazarja njihovo opcijsko naravo, oklepaji niso del
parametra).
Če neobvezni parametri niso navedeni, se privzamejo spodaj navedene default vrednosti.
Ob navedbi neobveznih parametrov se le-ti identificirajo po predponi, zato so lahko navedeni v
poljubnem vrstnem redu.
<Vrsta Zahteve>
Parameter je obvezen, možne vrednosti so prostor, racun, racun-n , racun-p, racun-k
Pravilna navedba tega parametra je zelo pomembna, saj komunikacija z ISFU poteka v
vsakem od navedenih primerov na drugačen način.
Vrednost prostor se poda v primeru, ko prijavljamo novo lokacijo na kateri se izdajajo
računi. To se za vsako lokacijo stori samo enkrat. Če prostor ni predhodno prijavljen,
se fakture iz te lokacije ne morejo prijavljati v potrditev.
Vrednost racun je najpogostejši način, saj predstavlja prijavo rednega računa iz
elektronske naprave.
Vrednost racun-n (n kot naknadno potrjevanje) se uporabi takrat, ko v času izdelave
računa povezave z ISFU ni bilo mogoče vzpostaviti in se potrditev izvaja naknadno. V
času, ko povezave ni bilo mogoče vzpostaviti (ni deloval internet na lokaciji
fakturiranja ali ni deloval FURS servis) je SimplyTax lahko vrnil le ZOI in črtno kodo, ne
pa tudi EOR številke. To številko je potrebno pridobiti kasneje (v roku dveh dni). V
response datoteko se v tem primeru zapiše samo EOR, ne pa tudi ZOI in črtna koda,
saj sta bila že navedena (in natisnjena) ob izdaji računa.
Vrednost racun-p (p kot ponovno potrjevanje ali morda kot popravek) se v skladu z
novimi navodili FURSA uporabi takrat, ko je po potrditvi računa prišlo do vsebinske
spremembe računa (je bil uporabljen napačen znesek, napačna davčna stopnja ipd.).
V tem primeru se račun pošlje ponovno z enako številko računa, zanj pa se pridobi
nov ZOI, nova črtna koda in nov EOR. (vse to je potrebno zavesti na strani
izdajateljeve evidence izdanih računov). Zapis računa, ki se pošilja naknadno, mora v
podatku ReferenceInvoice (R_3.14.1, R_3.14.2, R_3.14.3 in R_3.15) vsebovati
podatke o prvi izdaji računa (o računu, katerega popravek pošiljamo) ter v podatku
SpecialNotes (R_3.20) vsebovati tekst »CHSEQ#nDTYYYY-MMDDTHH:MM:SS«, pri
čemer »n« pomeni zaporedno številko naknadne spremembe računa (n=1,2,3,4,…),
»YYYY-MM-DDTHH:MM:SS« pa datum in čas spremembe računa.
Naveden tekst se vpisuje le v primeru naknadnega neposrednega spreminjanja
podatkov na računu (brez storniranja prvotnega računa in izdaje novega).
Vrednost racun-k (k kot knjiga) se uporabi takrat, ko se na FURS prijavlja račun iz
vezane knjige. Do te situacije lahko pride, ker izdajatelj (še) ne uporablja elektronske
naprave, ki je on-line povezana s ISFU, ampak prijavlja račune naknadno v okviru
možnosti, ki jih v prehodnem obdobju še dopušča zakon. Do te situacije lahko pride
tudi v primerih, ko je zmanjkalo elektrike in računa ni bilo mogoče izdati drugače, kot
zavesti v vezano knjigo računov.
Obstajata pa še dve posebni vrednosti: version in update. Večina lahko na ta dva
ukaza kar takoj pozabi, saj je v SimplyTax vgrajen mehanizem popolnoma
samodejnega posodabljanja. Ob uporabi vrednosti version vam v response datoteko
(ali na ekran, če uporabite še /console) zapišemo trenutno pri vas instalirano verzijo
in aktualno verzijo na našem strežniku.
Z uporabo ukaza update ročno sprožite obnovitev verzije programa (če sta verziji na
lokalnem disku in na serverju različni).
V primeru uporabe teh dveh vrednosti se ne pričakuje noben nadaljnji parameter
razen /console.
Oba ukaza sta na voljo le za kontrolen potrebe ali če bi obstajali realni argumenti, da
se autoupdate opcija v .confug datoteki želi izklopiti, česar pa absolutno ne
priporočamo.
<Delovanje>
Parameter je obvezen, možne vrednosti test, test-lc, prod
V bistvu gre za to, da se klicatelj lahko sam odloči kdaj bo iz testnega delovanja prešel
v produkcijskega. Po sedanjih informacijah bo produkcijsko delovanje omogočeno
01.12.2015, obvezno pa bo najkasneje 02.01.2016. Za prehod iz testnega v
produkcijsko delovanje je potrebno na isti direktorij instalirati predhodno pridobljen
produkcijski certifikat in za ta parameter navesti vrednost prod.
Če je vrednost parametra test, se za testiranje uporabi certifikat, ki ga je za testne
namene pridobilo podjetje IS.Edico d.o.o.. Certifikat je zapakiran v sam program
SimplyTax.exe, parameter o geslu (peti fiksni parameter) je pri klicu potrebno podati,
vendar se ignorira, saj se dejansko uporabi vgrajeno geslo. Na ta način lahko opravite
popolno integracijo in pridobivate testne EOR številke – vse do dejanske produkcije.
Lahko pa si uporabnik pridobi svoj lasten testni certifikat in za testne namene uporabi
tega. V tem primeru je potrebno za vrednost tega parametra navesti test-lc (kot test z
lastnim certifikatom). Program testni certifikat uporabi za testno podpisovanje in za
prijavo v FURS-ove servise.
Določitev ustreznega certifikata poteka na enak način kot določitev produkcijskega. V
obeh primerih program preveri ali se na direktoriju kjer se nahaja program
SimpleTax.exe ali na direktoriju od koder se izvede klic programa, nahaja natančno en
primeren certifikat in ga samodejno uporabi. Če po tem načinu certifikata ne najde ali
jih je več kot eden, vrne error. V teh primerih, ko je certifikat nameščen na drugi
lokaciji ali se na istem prodajnem mestu fakturira za več zavezancev in je posledično
nameščenih več certifikatov, je potrebno pri klicu ustrezen certifikat natančno navesti
(parameter s predpono CER#).
Produkcijska komunikacija se začne šele takrat, ko se drugi parameter postavi na
vrednost prod (trenutek prehoda torej določa klicatelj) in ima SimplyTax.exe dostop
do dejanskega produkcijskega certifikata (ki pa se ga ta trenutek še ne da pridobiti).
<SWid>
Parameter je obvezen, poda se davčno številko ponudnika SW, ki integrira SimplyTax.
<TxtDatoteka> Parameter je obvezen, vsebuje pot in ime datoteke v katero ste pripravili podatke o
računu (v primeru prijavljanja računa) ali o prostoru (v primeru prijavljanja prostora
oziroma lokacije). Najvarneje je, če ta parameter navedete v dvojnih narekovajih.
Podrobnejša navodila za pripravo tekstovne datoteke s podatki o računu se nahajajo
v ločenem dokumentu.
<CertGeslo>
Parameter je načelno obvezen, poda se geslo za uporabljeni certifikat. Izjemoma ga v
primeru, da je vrednost drugega parametra (Delovanje) enaka test, ni potrebno
navajati, saj se v tem primeru uporabi vgrajeno geslo vgrajenega testnega certifikata
izdanega podjetju IS.Edico d.o.o.. Če v svoji programski opremi vnaprej pripravite
nastavitev gesla in ga tudi v tem primeru dejansko podate v klicu, ni nič narobe,
enostavno se bo ignoriral, dokler se vrednost parametra Delovanje ne bo spremenila
na test-lc ali prod.
/console
/debug
Je opcijski parameter za testno poganjanje ukaza iz komandne vrstice (cmd,
command, power shell itd.). Če je parameter prisoten, se vsebina response-a izpiše
tudi na zaslonu. Ne gre torej za preusmeritev, v response datoteki je še vedno vse kot
običajno, le ni je potrebno vzporedno odpirati in gledati, ker imate response kar
sproti na ekranu.
Je opcijski parameter za testno spremljanje porabljenega časa po korakih. Če ga
uporabite, se v delovni direktorij ustvari datoteka log.txt v kateri so zabeleženi
bistveni koraki s časi v ms.
RD#<ResponseDatoteka>
Če parameter ni naveden, se privzame vrednost iz .config datoteke. Po defaultu je
nastavljena na response/STResponse.txt, kar pomeni, da se bo datoteka z vsebinami,
ki jih potrebuje klicatelj, zapisala na direktorij response, ki se nahaja znotraj
direktorija, kamor ste instalirali SimpleTax.
V večuporabniškem okolju (če je SimplyTax instaliran na mrežnem disku in ga kliče
več blagajn v istem omrežju ali če je instaliran na terminalskem strežniku) je potrebno
parameter obvezno navesti, da se zagotovi klicatelju lasten response.
Predlagamo, da parameter vedno navajate in si nedvomno določite natančno
lokacijo, kjer pričakujete vrnjene podatke.
V response datoteki je naveden ZOI, EOR in ime datoteke z ustrezno pripravljeno
črtno kodo. Sama datoteka s črtno kodo se nahaja na istem mestu kot response
datoteka in ima generično ime, navedeno v response datoteki.
Bolj natančen opis podatkov v response datoteki se nahaja v ločenem dokumentu.
QRV#<Velikost>
Velikost črtne kode – približna višina v cm.
Možne vrednosti so od 2 do 5 in približno ustrezajo višini slike, ki jo vrne program.
Če parameter ni naveden, je privzeta vrednost 2.
QRT#<Tip>
Tip željene črtne kode.
Možne vrednosti so QR, Code128, PDF417.
Če parameter ni naveden, se privzame QR.
QRF#<Format>
Željeni format, v katerem naj program vrne sliko, ki vsebuje izdelano črtno kodo.
Možne vrednosti so JPG, PNG, IMG, GIF, WMF in TIFF
(po potrebi lahko dodamo še kakšne željene formate, le sporočiti nam morate).
Če parameter ni naveden, se privzame JPG.
CER#<PotDoCertifikata>
Parameter ni obvezen, ker program sam pogleda ali se na direktoriju, kjer je
instaliran, nahaja natanko en uporabniški certifikat in ga v tem primeru avtomatsko
uporabi. V primeru, da certifikata na tem mestu ni ali da jih je več (recimo v primeru,
ko se na isti strojni opremi izdajajo računi za več davčnih zavezancev), program javi
napako.
V tem primeru je pri klicu potrebno navesti lokacijo in ime konkretnega certifikata
(naj spomnimo - geslo za uporabljeni certifikat je peti obvezen parameter).
DT#<ŠteviloSekund>
DT kot Delay Time. Parameter ni obvezen, omogoča pa nastavitev časa, ko se sprejme
odločitev, da komunikacija z ISFU ni vzpostavljena in se EOR ne da pridobiti. Kot
rezultat bo pri EOR navedena napaka z opisom Timeout. Tak račun bo potrebno
poslati v naknadno potrjevanje. Brez navedbe parametra se uporabi default vredost 5
sekund. Če v tem času po pošiljanju http requesta ni response-a, je povezava
razpoznana kot neuspešna.
Primer1 – testni klic z vgrajenim certifikatom, samo obvezni parametri :
SIMPLYTAX.EXE racun test 99280124 "c:\simplytax\racun.txt"
Primer2 – testni klic z lastnim testnim certifikatom, samo obvezni parametri,
sprotni ogled odgovora na zaslonu:
SIMPLYTAX.EXE racun test-lc 99280124 "c:\simplytax\racun.txt" testnogeslo /console
Primer3 – testni klic z lastnim testnim certifikatom, navedeni tudi vsi neobvezni parametri:
SIMPLYTAX.EXE racun test-lc 99280124 "c:\fakturiranje\temp\rac.txt" 23df45fgh67
RD#''c:\fakturiranje\response\response.txt'' QRT#QR QRF#PNG QRV#3
CER#''Cert_25365169_testni.p12''
Primer4 - testni klic za prijavo prostora, minimalen nabor parametrov :
SIMPLYTAX.EXE prostor test 99280124 "c:\simplytax\prostor.txt"
Klic prijave prostora ima enake parametre kot prijava racuna, razen parametrov za črtno kodo.
Morebiti pomotoma podani parametri, ki določajo črtno kodo, se pri prijavi prostora enostavno
ignorirajo. Klic prijave prostora mora biti izveden preden se iz tega prostora/lokacije prijavi prvi izdan
račun.
Naj dodatno opozorimo, da je davčna številka, podana pri klicu kot tretji obvezni parameter, davčna
številka ponudnika programske opreme, ki integrira SimplyTax v svojo rešitev za fakturiranje, ne pa
morebiti davčna številka davčnega zavezanca, ki izdaja fakturire. Vsi podatki izdajatelja so del računa
(ali podatkov lokacije) in so podani v txt datoteki, ki jo pri klicu podate kot četrti parameter.