API Usage

Spring Application

Fisver Java API contains a full object model for Invoice handling together with the corresponding requests and service responses, a proxy class for communication with web-service methods, and an elaborate exception hierarchy.

Fisver Java API is used as described in the following steps:

  1. Instantiating and populating a request with invoice details;
  2. Instiating or fetching a cached local client object used for communication with the service;
  3. Sending a request using a local method of the client class. That will authomatically sign and send a request to the web-service. It will either return a response object, or throw an Exception in case of a failed operation;
  4. Exception tree is organized in a way that clearly identifies the cause, so that a caller would know if the exception was caused by a temporary communication problem, or by an invalid request.

Improved Certificate Management

Certificates and private keys are kept in internal application key-stores, so your application can have full control over them. It does not require the service CA to be imported in the system trust-store, so there is no more annoying screen-locking imposed on the Android OS.

No knowledge of cryptography or Java crypto API is required by the users (programmers) in order to use the API! Request signing and response signature verification is done by a method that communicates with the service. All you have to do is give a reference to the files containing the keys and certificates.

The following are examples of usage in some common cases:

Stand-Alone Application

Stand-alone Java

Stand-Alone applications require the main library JAR to be included in the class-path:

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

...
//---- Forming a request object ----
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)); // automatically calculates tax amount
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");

//---- Fetching key and cert from KeyStore ----
PrivateKeyEntry pke = getFromKeyStore("myAlias");
SignatureCredentials sc = new SignatureCredentials(pke);
SecurityParameters sp = new SecurityParameters(
				TestKeystoreManager.getTLSKeyStore(),
				TestKeystoreManager.getTLSKeyStorePassword(), 
                TestKeystoreManager.getTrustStore());

//---- Instantiate a client ----
FisverClient fc = new FisverClient(sp);

//---- Sending a request and reading a response ----
RacunOdgovor o;
try {
    o = fc.racuni(rz, sc); // Signs request and verifies response
    String jir = o.getJir(); // Read returned JIR (Invoice UID)
} catch (VolatileException e) { 
    ... // Temporary exception - schedule for a later retry
} catch (RequestMessageException e) { 
    ... // Invalid request
} catch (ResponseMessageException e) { 
    ... // Invalid response
}
...

Spring

Spring Application

To use the Fisver Java API in a Spring application, you have to define a bean with a client object and a service URL:

<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.hr.client.FiskalizacijaClient">
    <property name="url" 
      value="https://cis.porezna-uprava.hr:8449/FiskalizacijaService" />
</bean>
...
</beans>

As usual, the bean can be injected in your code either through XML configuration, or by using the @Autowired annotation in the Java source:

import eu.fisver.hr.client.*;
import eu.fisver.hr.model.*;
import eu.fisver.hr.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 {
    // Inject the bean
    @Autowired
    private FiskalizacijaClient fc;
    
    ...
    
    protected ModelAndView handleRequestInternal(HttpServletRequest 
        request, HttpServletResponse response) throws Exception {

        RacunZahtjev rz = kreirajRacunZahtjev(); // See 1st example      
         //---- Fetching key and cert ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Sending request and read response ----
        RacunOdgovor o;
        try {
            o = fc.racuni(rz, sc); // Signs request and verifies response
            String jir = o.getJir(); // Read returned JIR (Invoice UID)
            ... // Temporary exception - schedule for a later retry
        } catch (RequestMessageException e) { 
            ... // Invalid request
        } catch (ResponseMessageException e) { 
            ... // Invalid response
        }
        ...
    }
}

JBoss Seam

Seam Application

To embed Fisver Java API in a JBoss Seam application, define a component in components.xml configuration file, containing the client class and the service URL:

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

Now the Client class can be accessed the same way as any other Seam component:

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

import org.jboss.seam.annotations.Name;

@Name("OtherComponent")
public class OtherComponent {
    // Inject the client object
    @In(value="fiskalizacijaClient")
    FiskalizacijaClient fc;
    
    public void saljiZahtjev(RacunZahtjev rz) throws Exception {

         //---- Fetching key and cert ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Sending request and read response ----
        RacunOdgovor o;
        try {
            o = fc.racuni(rz, sc); // Signs request and verifies response
            String jir = o.getJir(); // Read returned JIR (Invoice UID)
        } catch (VolatileException e) { 
            ... // Temporary exception - schedule for a later retry
        } catch (RequestMessageException e) { 
            ... // Invalid request
        } catch (ResponseMessageException e) { 
            ... // Invalid response
        }
        ...
    }
}