Skip to main content

Java SDK Quickstart

Following the steps described on this page, you'll create a simple Java application that interacts with the Fatture in Cloud API.

If you want to download the complete working example you can find it here.

0️⃣  Prerequisites​

In this guide, we assume that these prerequisites are met:

1️⃣  Step One: Add the dependencies​

In this Quickstart we are going to need some dependencies, OkHttpClient to make the API calls for the OAuth access token retrieval, JSON-java to parse the JSON, and our Java SDK, you can simply add them to your pom.xml or build.gradle file, as shown below:

pom.xml
<dependency>
  <groupId>it.fattureincloud</groupId>
  <artifactId>fattureincloud-java-sdk</artifactId>
  <version>VERSION</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>4.9.3</version>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.9.0</version>
</dependency>
<dependency>
    <groupId>io.vavr</groupId>
    <artifactId>vavr</artifactId>
    <version>0.10.4</version>
</dependency>

You can check the last version of our SDK on Maven Central.

2️⃣  Step Two: Set up the OAuth access token retrieval​

First of all create a java project, create the file Application.java in your src/main/java/ directory, and copy in the following code:

Application.java
import com.google.gson.Gson;
import com.sun.net.httpserver.HttpServer;
import it.fattureincloud.sdk.auth.OAuth2AuthorizationCodeManager;
import it.fattureincloud.sdk.auth.OAuth2AuthorizationCodeResponse;
import it.fattureincloud.sdk.auth.Scope;

import java.io.*;
import java.net.InetSocketAddress;
import java.util.Arrays;
import java.util.List;

class Application {

    public static void main(String[] args) throws IOException {
        int serverPort = 8000;
        HttpServer server = HttpServer.create(new InetSocketAddress(serverPort), 0);
        server.createContext("/oauth", (exchange -> {
            OAuth2AuthorizationCodeManager oauth = new OAuth2AuthorizationCodeManager("CLIENT_ID", "CLIENT_SECRET", "http://localhost:8000/oauth");
            List<Scope> scopes = Arrays.asList(Scope.ENTITY_SUPPLIERS_READ);
            String redirectUrl = oauth.getAuthorizationUrl(scopes, "EXAMPLE_STATE");
            String query = exchange.getRequestURI().getQuery();
            if(query == null) query = "";
            if(query.contains("code")){
                int start = query.indexOf("code=") + 5;
                int finish = query.indexOf("&");
                String code = query.substring(start, finish);
                Gson gson = new Gson();
                OAuth2AuthorizationCodeResponse tokenObj = oauth.fetchToken(code).get();
                String token = gson.toJson(tokenObj);

                saveToken(token);
                String respText = "token salvato correttamente";
                exchange.sendResponseHeaders(200, respText.getBytes().length);
                OutputStream output = exchange.getResponseBody();
                output.write(respText.getBytes());
                output.flush();
                exchange.close();
            }else{
                exchange.getResponseHeaders().set("Location", redirectUrl);
                exchange.sendResponseHeaders(302, 0);
                exchange.close();
            }

        }));
        server.createContext("/quickstart", (exchange -> {
            String token = retrieveToken();

            //the following method is defined in the next step
            String respText = Quickstart.getFirstCompanySuppliers(token);

            exchange.sendResponseHeaders(200, respText.getBytes().length);
            OutputStream output = exchange.getResponseBody();
            output.write(respText.getBytes());
            output.flush();
            exchange.close();
        }));
        server.setExecutor(null);
        server.start();
    }

    public static void saveToken(String token) throws IOException {
        BufferedWriter writer = new BufferedWriter(new FileWriter("token.json"));
        writer.write(token); //saving the oAuth access token in the token.json file

        writer.close();
    }

    public static String retrieveToken() throws IOException {
        BufferedReader reader = new BufferedReader(new FileReader("token.json"));
        String json = reader.readLine();
        Gson gson = new Gson();
        OAuth2AuthorizationCodeResponse obj = gson.fromJson(json, OAuth2AuthorizationCodeResponse.class);
        String token = obj.getAccessToken();
        return token;
    }
}

To make this code work properly the only thing you need to set your client id, client secret and eventually the redirect uri at line 18.

Store the Token safely!

In this QuickStart the access token and refresh token are stored in a file. This is only for educational purposes, the OAuth access token and refresh token are sensitive data and should be saved securely on your database. Also, never share your Client Secret with third-party actors, or publish it to your frontend!

3️⃣  Step Three: Set up the sample​

Retrieve your Company ID!

In this example, we'll show how to retrieve your Company ID using the Java SDK. If you plan to manage only one company, you can insert it directly into your code as a variable. Check the Company-scoped Methods page for more info.

Create a file called Quickstart.java in your working directory and copy in the following code:

Quickstart.java
import it.fattureincloud.sdk.ApiClient;
import it.fattureincloud.sdk.ApiException;
import it.fattureincloud.sdk.Configuration;
import it.fattureincloud.sdk.api.SuppliersApi;
import it.fattureincloud.sdk.api.UserApi;
import it.fattureincloud.sdk.auth.OAuth;
import it.fattureincloud.sdk.model.ListSuppliersResponse;
import it.fattureincloud.sdk.model.ListUserCompaniesResponse;

public class Quickstart {
    public static String getFirstCompanySuppliers(String token) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api-v2.fattureincloud.it");

        // Configure OAuth2 access token for authorization: OAuth2AuthenticationCodeFlow
        OAuth OAuth2AuthenticationCodeFlow = (OAuth) defaultClient.getAuthentication("OAuth2AuthenticationCodeFlow");
        OAuth2AuthenticationCodeFlow.setAccessToken(token);

        UserApi userApiInstance = new UserApi(defaultClient);
        SuppliersApi suppliersApiInstance = new SuppliersApi(defaultClient);

        try {
            // Retrieve the first company id
            ListUserCompaniesResponse userCompanies = userApiInstance.listUserCompanies();
            int firstCompanyId = userCompanies.getData().getCompanies().get(0).getId();

            // Retrieve the list of first 10 Suppliers for the selected company
            Integer companyId = 12345; // Integer | The ID of the company.
            Integer page = 1; // Integer | The page to retrieve.
            Integer perPage = 10; // Integer | The size of the page.

            ListSuppliersResponse result = suppliersApiInstance.listSuppliers(companyId, null, null, null, page, perPage, null);
            return result.getData().toString();

        } catch (ApiException e) {
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
            return e.getResponseBody();
        }
    }
}

4️⃣  Step Four: Run the sample​

Now run your project and visit http://localhost:8000/oauth (or whatever your URL is), you will be redirected to the Fatture in Cloud login page where you will be asked to grant some permissions, according to what scopes you specified previously. Finally, you will see the success message, the access token will be stored in the token.json file ready to be used.

You can now visit http://localhost:8000/quickstart (or whatever your URL is) to test the application.

❓  What now?​

In this example, we used a limited set of the available API methods to show how to use our SDK.

If you want to access the full documentation of the available methods and models, you can check the following resources: