Home

Billy is a billing library for applications providing them with ability to create, manage, and store billing artifacts such as invoices and credit notes. It also supports the export of the persisted data in PDF and SAF-T formats.

Billy was built to be easily extended to support additional taxing systems for different countries. Billy's core module was based on the OECD's SAF-T schema, providing a standard module from which one can extend and further develop to support new modules for different legislation.

The objective is for all modules to be compliant with the existing regulations for their country/region. However, we do intend to provide a certified library. This should be the responsibility of any application that uses or will use Billy.

Get Billy

You can obtain Billy by downloading the latest release or by cloning the latest sources from GitHub

Maven projects

Add the following maven dependency to your project pom.xml:

<dependency>
   <groupId>com.premiumminds</groupId>
   <artifactId>billy-portugal</artifactId>
   <version>0.0.1-SNAPSHOT</version>
</dependency>

Check out sonatype repository for latest snapshots and releases.

---

Get Started Guide

This guide combines an overview of Billy with a quick tutorial that helps you to get started with it. This guide will focus on the billy-portugal module, the Portuguese implementation of Billy.

Requirements

Configuring billy's database

Billy uses the Java Persistency API and Hibernate to persist all of the billing information in a database.

Initiating Billy

Start by creating a new instance of Billy:

BillyPortugal billyPortugal = new BillyPortugal();

This provides your application with quick access to all main features of Billy.

From here you can access:

1. Builders
2. Services
3. Predefined taxes and contexts for the module(in this case billy-portugal).

Bootstrap Billy

Bootstrap incorporates entities that are essential for any application using one of Billy's modules, for instance, the billy-portugal bootstrap provides you with all the contexts and taxes required for Portuguese legislation, providing an easy and quick start for new applications using Billy.

To bootstrap your application:

** ADD HERE **

Builders

In order to create a new entity in Billy you'll have to obtain an appropriate builder for the entity you wish to create.

The Builders class provides you with all the required builders for each entity. You can obtain them following way:

Builders builders = billyPortugal.builders();

Building Simple Entites

Example of how to build a simple address:

PTAddress.Builder addressBuilder = builders.createAddressBuilder();
addressBuilder.setBuilding("Example Building")
              .setCity("Lisbon")
              .setNumber("1")
              .setISOCountry("PT")
              .setDetails("A big building")
              .setPostalCode("1000-100")
              .setStreetName("Example Street")
              .setRegion("Lisbon");

Build the new entity:

PTAddress address = addressBuilder.build();

Building entities with a persisted entity

In some cases the entity needed for the builder has to all ready be persisted. For example, the invoice builder receives the UID for a business.

PTInvoice.Builder invoiceBuilder = builders.invoices().createInvoiceBuilder();
invoiceBuilder.setBusinessUID(businessUID)
                 // additional sets..
              .setSettlementDate(new Date());

businessUID should be the UID of the previously persisted business entity.

Building entities with builders

Builders may receive other entities' builders. An example is the business entity which needs a builder to define its address.

PTAddress.Builder addressBuilder = builders.createAddressBuilder();
addressBuilder.setBuilding("Example Building")
                  // aditional sets...
              .setRegion("Lisbon");

PTBusiness.Builder businessBuilder = builders.configuration().createBusinessBuilder();
businessBuilder.setAddress(addressBuilder)
                  // aditional sets...
               .setName("My Business");

You can now create the new entity:

PTBusiness business = businessBuilder.build();

This will create all required entities need for the business, in this case it will first build the address using the addressBuilder and then create the new business entity.

Services

BillyPortugal provides you with the needed services for you application.

Services portugalServices = billyPortugal.services();

Persistence

You''ll probably need to persist an entity. You can easily get all the CRUD operations available for each entity through Persistence class.

Persistence persistence = portugalServices.persistence();

Save a new business in the database. This will build the entity then persisit it.

persistence.business().create(businessBuilder);

Issuing Service

To issue a new invoice you'll need its builder as well as all issuing parameters.

Invoice parameters

This encapsulates the needed parameters to issue your invoice, such as PrivateKey, PublicKey, Series, etc.

PTIssuingParams invoiceParameters = PTIssuingParamsImpl();

To set the PrivateKey and PublicKey you can use the provided KeyGenerator to generate your keys.

KeyGenerator gen = new KeyGenerator("private/key/dir/pkey.pem");

invoiceParameters.setPrivateKey(gen.getPrivateKey());
invoiceParameters.setPublicKey(gen.getPublicKey());
invoiceParameters.setSeries("New Series");

Issuing the document

After defining the all the parameters you simple issue the document:

portugalServices.issueDocument(invoiceBuilder, ivoiceParameters);

Export service

SAF-T

PDF