Korištenje modula

Spring Application

Fisver Java API je se sastoji od modela za prikaz objekta zahtjeva i odgovora, klase-posrednika za pozivanje metoda web servisa i nekoliko opcionalnih klasa za dodatnu kontrolu nad procesom.

Korištenje Fisver Java API-ja svodi se na sljedeće korake:

  1. Instanciranje i popunjavanje zahtjeva s računom;
  2. Instanciranje ili dohvaćanje lokalne klijentske klase za komunikaciju sa servisom;
  3. Slanje zahtjeva korištenjem metode lokalne klijentske klase, koja zahtjev potpisuje, https-om sinkrono komunicira s web-servisom CIS-a i na izlazu vraća objekt odgovora, odnosno baca iznimku (Exception) u slučaju neuspjele akcije;
  4. Iznimke su sistematizirane na način da pozivatelj zna koja je pogreška posljedica privremenog uzroka (recimo, problem na vezi), pa ponovljeno slanje istog zahtjeva može uspjeti, a kod koje to nema smisla.

Novo upravljanje certifikatima

Od verzije 3.0 certifikati i privatni ključevi se nalaze u internim aplikacijskim key-storevima, tako da aplikacija ima potpunu kontrolu nad njima. Više nije potrebno posebno unositi CA certifikat u sistemski trust-store i zato na Androidu sustav više ne forsira zaključavanje ekrana!

Od programera se ne zahtijeva nikakvo predznanje teorije kriptografije, niti poznavanje pripadajućih Java kriptografskih klasa! Potpisivanje zahtjeva obavlja se jednostavnim pozivom metode za potpisivanje koja obavlja sav posao, a provjera autentičnosti odgovora radi se automatski prilikom zaprimanja odgovora s web-servisa.

U nastavku je nekoliko tipičnih primjera korištenja u raznim arhitekturama:

Samostalna aplikacija

Stand-alone Java

Kod samostalnih Java aplikacija dovoljno je datoteku fisver.jar uključiti u class-path i napraviti gore opisane korake:

import eu.fisver.si.client.*;
import eu.fisver.si.model.*;
import eu.fisver.si.test.utils.*;
import java.security.KeyStore.PrivateKeyEntry;

...
//---- Kreiranje objekta zahtjeva ----
RacunZahtjev rz = new RacunZahtjev();
rz.setZaglavlje(new ZaglavljeType(UUID.randomUUID()));

RacunType r = new RacunType();
rz.setRacun(r);
r.setOib(oib);
r.setUSustPdv(true);
r.setDatVrijeme(new Date());
r.setOznSlijed(OznakaSlijednostiType.P);
BrojRacunaType br = new BrojRacunaType("123456789/POSL1/12");
r.setBrRac(br);

PdvType pdv = new PdvType();
r.setPdv(pdv);
pdv.getPorez().add(new PorezType(25, 10)); // automatski računa iznos
pdv.getPorez().add(new PorezType(10, 10));
pdv.getPorez().add(new PorezType(0, 10));

r.setIznosUkupno(30.0);
r.setNacinPlac(NacinPlacanjaType.K);
r.setOibOper("01234567890");

//---- Dohvaćanje ključa i certifikata iz KeyStore-a ----
PrivateKeyEntry pke = getFromKeyStore("myAlias");
SignatureCredentials sc = new SignatureCredentials(pke);
SecurityParameters sp = new SecurityParameters(
				TestKeystoreManager.getTLSKeyStore(),
				TestKeystoreManager.getTLSKeyStorePassword(), 
                TestKeystoreManager.getTrustStore());

//---- Instanciranje klijenta ----
FisverClient fc = new FisverClient(sp);

//---- Slanje zahtjeva i čitanje odgovora ----
RacunOdgovor o;
try {
    o = fc.racuni(rz, sc); // Potpisuje i provjerava i autentičnost odgovora
    String jir = o.getJir(); // Čitanje vraćenog JIR-a
} catch (VolatileException e) { 
    ... // Privremena greška - pokušati kasnije ponovo
} catch (RequestMessageException e) { 
    ... // Neispravna poruka zahtjeva
} catch (ResponseMessageException e) { 
    ... // Neispravna poruka odgovora
}
...

Spring

Spring Application

Kod korištenja Fisver Java API-ja unutar Spring aplikacije, u konfiguracijskoj datoteci se definira bean s klasom i opcionalnim URL-om servisa:

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans
	http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
 ...
<bean id="FisBean" class="eu.fisver.si.client.FiskalizacijaClient">
    <property name="url" 
      value="https://cis.porezna-uprava.hr:8449/FiskalizacijaService" />
</bean>
...
</beans>

Bean se u kod može ubaciti bilo kroz XML konfiguraciju, bilo korištenjem @Autowired anotacije unutar klase:

import eu.fisver.si.client.*;
import eu.fisver.si.model.*;
import eu.fisver.si.test.utils.*;
import java.security.KeyStore.PrivateKeyEntry;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.mvc.AbstractController;
			
public class MyController extends AbstractController {
    // Automatsko ubacivanje bean-a s klijentom
    @Autowired
    private FiskalizacijaClient fc;
    
    ...
    
    protected ModelAndView handleRequestInternal(HttpServletRequest 
        request, HttpServletResponse response) throws Exception {

        RacunZahtjev rz = kreirajRacunZahtjev(); // V. prvi primjer      
         //---- Dohvaćanje ključa i certifikata ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Slanje zahtjeva i čitanje odgovora ----
        RacunOdgovor o;
        try {
            o = fc.racuni(rz, sc); // Potpisuje i provjerava i autentičnost odgovora
            String jir = o.getJir(); // Čitanje vraćenog JIR-a
        } catch (VolatileException e) { 
            ... // Privremena greška - pokušati kasnije ponovo
        } catch (RequestMessageException e) { 
            ... // Neispravna poruka zahtjeva
        } catch (ResponseMessageException e) { 
            ... // Neispravna poruka odgovora
        }
        ...
    }
}

JBoss Seam

Seam Application

Za ugrađivanje Fisver Java API-ja u JBoss Seam aplikaciju, u components.xml konfiguracijskoj datoteci se definira komponenta s klasom i opcionalnim URL-om servisa:

<components>
  ...
  <component name="fiskalizacijaClient"
      class="eu.fisver.si.client.FiskalizacijaClient"
      auto-create="true">
    <property name="urlString">
      https://cis.porezna-uprava.hr:8449/FiskalizacijaService
    </property>
  </component>
  ...
</components>

Nakon toga se servisu pristupa kao i bilo kojoj drugoj Seam komponenti. Na primjer, ovako mu se pristupa iz druge komponente, korištenjem Seam injekcije:

import eu.fisver.si.client.*;
import eu.fisver.si.model.*;
import eu.fisver.si.test.utils.*;
import java.security.KeyStore.PrivateKeyEntry;

import org.jboss.seam.annotations.Name;

@Name("OtherComponent")
public class OtherComponent {
    // Automatsko ubacivanje komponente s klijentom
    @In(value="fiskalizacijaClient")
    FiskalizacijaClient fc;
    
    public void saljiZahtjev(RacunZahtjev rz) throws Exception {

         //---- Dohvaćanje ključa i certifikata ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Slanje zahtjeva i čitanje odgovora ----
        RacunOdgovor o;
        try {
            o = fc.racuni(rz, sc); // Potpisuje i provjerava i autentičnost odgovora
            String jir = o.getJir(); // Čitanje vraćenog JIR-a
        } catch (VolatileException e) { 
            ... // Privremena greška - pokušati kasnije ponovo
        } catch (RequestMessageException e) { 
            ... // Neispravna poruka zahtjeva
        } catch (ResponseMessageException e) { 
            ... // Neispravna poruka odgovora
        }
        ...
    }
}