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.cz.client.*;
import eu.fisver.cz.model.*;
import eu.fisver.cz.test.utils.*;
import java.security.KeyStore.PrivateKeyEntry;

...
//---- Forming a request object ----
InvoiceRequest req = new InvoiceRequest();

RequestHeader header = new RequestHeader(req);
header.setFirstSending(true);
header.setVerification(false);

Data data = new Data(req);
data.setTaxNumber(taxNumber);
data.setBusinessPremisesId(1);
data.setCashRegisterId("CASH");
data.setReceiptSerial("RCPT123");
data.setSaleDateTime(new Date());
data.setTotalAmount(34113.00);
data.setSaleRegime(1);
data.setTotalAmountForTravelService(11.2);

//---- 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 ----
InvoiceResponse res;
try {
    res = fc.registerInvoice(req, sc); // Signs request and verifies response
    ValidationCode vc = res.getAcknowledgement().getValidationCode();  // Read returned Validation Code
} 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="fisverClient" class="eu.fisver.cz.client.FisverClient">
    <property name="url" 
      value="https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3" />
</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.cz.client.*;
import eu.fisver.cz.model.*;
import eu.fisver.cz.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 FisverClient fc;
    
    ...
    
    protected ModelAndView handleRequestInternal(HttpServletRequest 
        request, HttpServletResponse response) throws Exception {

        InvoiceRequest req = createInvoiceRequest(); // See 1st example      
         //---- Fetching key and cert ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Sending request and read response ----
        InvoiceResponse res;
        try {
            res = fc.registerInvoice(req, sc); // Signs request and verifies response
            ValidationCode vc = res.getAcknowledgement().getValidationCode();  // Read returned Validation Code
        } catch (VolatileException e) { 
            ... // 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="fisverClient"
      class="eu.fisver.cz.client.FisverClient"
      auto-create="true">
    <property name="urlString">
      https://pg.eet.cz:443/eet/services/EETServiceSOAP/v3
    </property>
  </component>
  ...
</components>

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

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

import org.jboss.seam.annotations.Name;

@Name("OtherComponent")
public class OtherComponent {
    // Inject the client object
    @In(value="fisverClient")
    FisverClient fc;
    
    public void sendRequest(InvoiceRequest req) throws Exception {

         //---- Fetching key and cert ----
        PrivateKeyEntry pke = getFromKeyStore("myAlias");
        SignatureCredentials sc = new SignatureCredentials(pke);
        
        //---- Sending request and read response ----
        InvoiceResponse res;
        try {
            res = fc.registerInvoice(req, sc); // Signs request and verifies response
            ValidationCode vc = res.getAcknowledgement().getValidationCode();  // Read returned Validation Code
        } catch (VolatileException e) { 
            ... // Temporary exception - schedule for a later retry
        } catch (RequestMessageException e) { 
            ... // Invalid request
        } catch (ResponseMessageException e) { 
            ... // Invalid response
        }
        ...
    }
}