---
source: https://carbone.io/documentation/developer/api-sdks/java.html
title: "Generate documents and reports with Java SDK"
description: "Generate report with Java"
generated_at: "2026-07-13"
---

# Java SDK

Generate report with Java

Java SDK to generate reports through the [Carbone Cloud API](/documentation/quickstart/getting-started/generate-a-document.md) in a few lines of code.

The source code is available on Github: [https://github.com/carboneio/carbone-sdk-java](https://github.com/carboneio/carbone-sdk-java)

## Install

```java
<dependency>
    <groupId>io.carbone</groupId>
    <artifactId>carbone-sdk</artifactId>
    <version>2.0.0</version>
</dependency>
```

## Quickstart with the Java SDK

Try the following code to render a report in 10 seconds. Just insert your API key, the template path you want to render, and the JSON data-set as a string. Get your API key on your Carbone account: [https://account.carbone.io/](https://account.carbone.io/).

```java
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(API_KEY);
String json = "{ "data": { "id": "AF128","firstname": "John", "lastname": "wick"}, "reportName": "invoice-{d.id}","convertTo": "pdf"}";

/** Generate the document */
try{
    CarboneDocument report = carboneServices.render(json ,"/path/to/template.docx");
}
catch(CarboneException e)
{
    // handle error
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

// Get the name of the document with the `getName()`. For instance the name of the document, based on the JSON, is: "invoice-AF128.pdf"
try (FileOutputStream outputStream = new FileOutputStream(report.getName())) {
    /** Save the generated document */
    outputStream.write(report.getFileContent());
} catch (IOException ioe) {
    // handle error
}
```

## Carbone SDK Constructor

**Definition**

```java
public CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(String... config);
```

**Example**

Example of a new SDK instance for Carbone Cloud: Get your API key on your Carbone account: [https://account.carbone.io/](https://account.carbone.io/).

```java
// For Carbone Cloud, provide your API Access Token as the first argument:
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create("API_TOKEN");
Example of a new SDK instance for Carbone On-premise or Carbone On-AWS:

// Define the URL of your Carbone On-premise Server or AWS EC2 URL:
CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.SetCarboneUrl("ON_PREMISE_URL");
// Then get a new instance by providing an empty string to the "create" function:
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create("");
```

## Generate and Download Document

**Prototype**

```java
public CarboneDocument render(String jsonData, String pathOrTemplateID) throws CarboneException;
```

The render function generates a document using a specified template and data. It takes two parameters:

-   jsonData: A stringified JSON containing the data to populate the template.
-   pathOrTemplateID: The path to your local file or a template ID.

The render function returns a CarboneDocument, it provides two methods:

-   getFileContent(): Return the document as byte\[\].
-   getName(): Return the document name as String.

Function Behavior

1.  Template File Path as Second Argument:
    -   If a template file path is provided, the function first checks if the template has been uploaded to the server.
    -   If the template has not been uploaded, it calls the addTemplate function to upload the template and generate a new template ID.
    -   The function then calls renderReport followed by getReport to generate and retrieve the report.
    -   If the provided path does not exist, an error is returned.
2.  Template ID as Second Argument:
    -   If a template ID is provided, the function calls renderReport to generate the report. It then calls getReport to retrieve the generated report.
    -   If the template ID does not exist, an error is returned.

🔎 Tip: Providing the Template File Path is the best solution, you won't have to deal with template IDs.

**Example**

```java
try{
    CarboneDocument report = carboneServices.render(json ,"/path/to/template.xlsx");
    // report.getFileContent() returns the generated document as byte[]
    // report.getName() returns the document name as String
}
catch(CarboneException e)
{
    // handle error
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}
```

## Add Template

**Definition**

```java
public String addTemplate(byte[] templateFile) throws CarboneException, IOException;
```

or

```java
public String addTemplate(String templatePath) throws CarboneException, IOException;
```

Add a template as path String or as byte\[\] and the function returns the template ID as String.

**Example**

Add a template as file path:

```java
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    String templateId = carboneServices.addTemplate("/path/to/template.docx");
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(templateId);
```

Add a template as byte\[\]:

```java
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    String templateId = carboneServices.addTemplate(Files.readAllBytes(Paths.get("/path/to/template.docx")));
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(templateId);
```

## Delete Template

**Definition**

```java
public boolean deleteTemplate(String templateId) throws CarboneException;
```

Delete a template by providing a template ID as String, and it returns whether the request succeeded as a Boolean.

**Example**

```java
ICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);

try{
    boolean result = carboneServices.deleteTemplate(templateId.get());
}
catch(CarboneException e)
{
    System.out.println("Error message : " + e.getMessage() + "Status code : " + e.getHttpStatus());
}

System.out.println(result);
```

## Related topics

- [Rust SDK](/documentation/developer/api-sdks/rust.md)
- [Python SDK](/documentation/developer/api-sdks/python.md)
- [PHP SDK](/documentation/developer/api-sdks/php.md)
- [NodeJS SDK](/documentation/developer/api-sdks/nodejs.md)
- [Javascript SDK](/documentation/developer/api-sdks/javascript.md)
- [Go SDK](/documentation/developer/api-sdks/go.md)