{"id":39079051,"url":"https://github.com/carboneio/carbone-sdk-java","last_synced_at":"2026-01-17T18:28:52.024Z","repository":{"id":247082178,"uuid":"698893208","full_name":"carboneio/carbone-sdk-java","owner":"carboneio","description":"Generate documents with Carbone, using templates and JSON data-set. Create invoices, reports, certificates, contracts, financial statements, documents like Word files, Excel sheets, CSVs, PowerPoint slides, and more.","archived":false,"fork":false,"pushed_at":"2024-07-06T15:57:42.000Z","size":264,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-07-07T13:58:46.964Z","etag":null,"topics":["automation","document","document-generation","docx","generation","generator","java","maven","odt","pdf","pptx","reporting","xlsx"],"latest_commit_sha":null,"homepage":"https://carbone.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carboneio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-01T09:55:25.000Z","updated_at":"2024-07-06T15:57:45.000Z","dependencies_parsed_at":"2024-07-06T13:58:19.004Z","dependency_job_id":"460a436d-a359-4d45-8eaf-10fe7c07d832","html_url":"https://github.com/carboneio/carbone-sdk-java","commit_stats":null,"previous_names":["carboneio/carbone-sdk-java"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/carboneio/carbone-sdk-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carboneio","download_url":"https://codeload.github.com/carboneio/carbone-sdk-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28515591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:28:00.501Z","status":"ssl_error","status_checked_at":"2026-01-17T18:28:00.150Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","document","document-generation","docx","generation","generator","java","maven","odt","pdf","pptx","reporting","xlsx"],"created_at":"2026-01-17T18:28:51.915Z","updated_at":"2026-01-17T18:28:51.982Z","avatar_url":"https://github.com/carboneio.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carbone API Java SDK\n\nThe Carbone Java SDK provides a simple interface to communicate with Carbone Cloud API to generate documents.\n\n## Install the Java SDK\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.carbone\u003c/groupId\u003e\n    \u003cartifactId\u003ecarbone-sdk\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Quickstart with the Java SDK\n\nTry 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 string. Get your API key on your Carbone account: https://account.carbone.io/.\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(API_KEY);\nString json = \"{ \\\"data\\\": { \\\"id\\\": \\\"AF128\\\",\\\"firstname\\\": \\\"John\\\", \\\"lastname\\\": \\\"wick\\\"}, \\\"reportName\\\": \\\"invoice-{d.id}\\\",\\\"convertTo\\\": \\\"pdf\\\"}\";\n\n/** Generate the document */\ntry{\n    CarboneDocument report = carboneServices.render(json ,\"/path/to/template.docx\");\n}\ncatch(CarboneException e)\n{\n    // handle error\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\n// Get the name of the document with the `getName()`. For instance the name of the document, based on the JSON, is: \"invoice-AF128.pdf\"\ntry (FileOutputStream outputStream = new FileOutputStream(report.getName())) {\n    /** Save the generated document */\n    outputStream.write(report.getFileContent());\n} catch (IOException ioe) {\n    // handle error\n}\n\n```\n\n## Java SDK API\n\n### Table of content\n\n- SDK functions:\n    - [CarboneSDK Constructor](#carbone-sdk-constructor)\n    - [Generate and Download a Document](#generate-and-download-document)\n    - [Generate a Document Only](#generate-document-only)\n    - [Download a Document Only](#download-document-only)\n    - [Add a Template](#add-template)\n    - [Delete a Template](#delete-template)\n    - [Get a Template](#get-template)\n    - [Set Carbone URL](#set-carbone-url)\n    - [Get API status](#get-api-status)\n    - [Set API Version](#set-api-version)\n- [Build commands](#build-commands)\n- [Test commands](#test-commands)\n- [Project history](#-history)\n- [Contributing](#-contributing)\n\n### Carbone SDK Constructor\n\n**Definition**\n\n```java\npublic CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(String... config);\n```\n\n**Example**\n\nExample of a new SDK instance for **Carbone Cloud**:\nGet your API key on your Carbone account: https://account.carbone.io/.\n```java\n// For Carbone Cloud, provide your API Access Token as first argument:\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(\"API_TOKEN\");\n```\n\nExample of a new SDK instance for **Carbone On-premise** or **Carbone On-AWS**:\n```java\n// Define the URL of your Carbone On-premise Server or AWS EC2 URL:\nCarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.SetCarboneUrl(\"ON_PREMISE_URL\");\n// Then get a new instance by providing an empty string to the \"create\" function:\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(\"\");\n```\n\n### Generate and Download Document\n\n**Prototype**\n\n```java\npublic CarboneDocument render(String jsonData, String pathOrTemplateID) throws CarboneException;\n```\n\nThe render function generates a document using a specified template and data. It takes two parameters:\n* jsonData: A stringified JSON containing the data to populate the template.\n* pathOrTemplateID: The path to your local file or a template ID.\n\nThe render function returns a `CarboneDocument`, it provides two methods:\n* **getFileContent()**: Return the document as `byte[]`.\n* **getName()**: Return the document name as `String`.\n\n**Function Behavior**\n\n1. Template File Path as Second Argument: \n    - If a template file path is provided, the function first checks if the template has been uploaded to the server.\n    - If the template has not been uploaded, it calls the addTemplate function to upload the template and generate a new template ID.\n    - The function then calls [renderReport](#generate-document-only) followed by [getReport](#download-document-only) to generate and retrieve the report.\n    - If the provided path does not exist, an error is returned.\n2. Template ID as Second Argument:\n    - If a template ID is provided, the function calls [renderReport](#generate-document-only) to generate the report. It then calls [getReport](#download-document-only) to retrieve the generated report.\n    - If the template ID does not exist, an error is returned.\n\n\u003e 🔎 Tip: Providing the Template File Path is the best solution, you won't have to deal with template IDs.\n\n**Example**\n\n```java\ntry{\n    CarboneDocument report = carboneServices.render(json ,\"/path/to/template.xlsx\");\n    // report.getFileContent() returns the generated document as byte[]\n    // report.getName() returns the document name as String\n}\ncatch(CarboneException e)\n{\n    // handle error\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n```\n\n### Generate Document Only\n\n**Definition**\n\n```java\npublic String renderReport(String renderData, String templateId) throws CarboneException;\n```\n\nThe renderReport function takes a template ID as `String`, and the JSON data-set as `String`.\nIt return a `renderId`, you can pass this `renderId` at [getReport](#download-document-only) for download the document.\n\n**Example**\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\n\nString json = \"{ \\\"data\\\": { \\\"id\\\": \\\"AF128\\\",\\\"firstname\\\": \\\"John\\\", \\\"lastname\\\": \\\"wick\\\"}, \\\"reportName\\\": \\\"invoice-{d.id}\\\",\\\"convertTo\\\": \\\"pdf\\\"}\";\ntry{\n    String renderId = carboneServices.renderReport(jsonObj, \"Use/your/local/path\");\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\nSystem.out.println(renderId);\n```\n\n### Download Document Only\n\n**Definition**\n```java\npublic CarboneDocument getReport(String renderId) throws CarboneException;\n```\n\nDownload a generated document from a render ID as `String`.\n\nThe getReport function returns a `CarboneDocument`, it provides two methods:\n* **getFileContent()**: Return the document as `byte[]`.\n* **getName()**: Return the document name as `String`.\n\n**Example**\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\ntry{\n    CarboneDocument render = carboneServices.getReport(renderId);\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\n// Get the name of the document with the `getName()`.\ntry (FileOutputStream outputStream = new FileOutputStream(render.getName())) {\n    // Save the file\n    outputStream.write(render.getFileContent());\n}\n```\n\n\n### Add Template\n\n**Definition**\n\n```java\npublic String addTemplate(byte[] templateFile) throws CarboneException, IOException;\n```\nor\n\n```java\npublic String addTemplate(String templatePath) throws CarboneException, IOException;\n```\n\nAdd a template as path `String` or as `byte[]` and the function return the template ID as `String`.\n\n**Example**\n \nAdd a template as file path:\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\n\ntry{\n    String templateId = carboneServices.addTemplate(\"/path/to/template.docx\");\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\nSystem.out.println(templateId);\n```\n\nAdd a template as `byte[]`:\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\n\ntry{\n    String templateId = carboneServices.addTemplate(Files.readAllBytes(Paths.get(\"/path/to/template.docx\")));\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\nSystem.out.println(templateId);\n```\n\n### Delete Template\n\n**Definition**\n\n```java\npublic boolean deleteTemplate(String templateId) throws CarboneException;\n```\n\nDelete a template by providing a template ID as `String`, and it returns whether the request succeeded as a `Boolean`.\n\n**Example**\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\n\ntry{\n    boolean result = carboneServices.deleteTemplate(templateId.get());\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\nSystem.out.println(result);\n```\n\n## Get Template\n\n**Definition**\n\n```java\npublic byte[] getTemplate(String templateId) throws CarboneException;\n```\n\nProvide a template ID as `String` and it returns the file as `byte[]`.\n\n**Example**\n\n```java\n// Download the template\ntry{\n    byte[] templateBytes = carboneServices.getTemplate(\"TEMPLATE_ID\");\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\n// Save the template file\ntry (FileOutputStream stream = new FileOutputStream(\"./template.docx\")) {\n    stream.write(templateBytes);\n} catch (IOException ioe) {\n    // handle error\n}\n```\n\n### Set Carbone Url\n\n**Definition**\n\n```java\npublic void SetCarboneUrl(String CARBONE_URL);\n```\n\nSet the API URL for Carbone On-premise or Carbone On-AWS.\n\n**Example**\n```java\nCarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.SetCarboneUrl(\"API_URL\");\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(API_TOKEN);\n```\n\n### Get API Status\n\n**Definition**\n\n```java\npublic String getStatus() throws CarboneException;\n```\n\nThe function requests the Carbone API to get the current status and version as `String`.\n\n**Example**\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(apiKey);\n\ntry{\n    String status = carboneServices.getStatus();\n}\ncatch(CarboneException e)\n{\n    System.out.println(\"Error message : \" + e.getMessage() + \"Status code : \" + e.getHttpStatus());\n}\n\nSystem.out.println(status);\n// Result: \"{\\\"success\\\":true,\\\"code\\\":200,\\\"message\\\":\\\"OK\\\",\\\"version\\\":\\\"4.22.8\\\"}\"\n```\n\n### Set API Version\n\nSpecify the version of the Carbone CLoud API you want to request as second argument of the constructor.\nBy default, all requested are made to the Carbone API version `4`.\n\n```java\nICarboneServices carboneServices = CarboneServicesFactory.CARBONE_SERVICES_FACTORY_INSTANCE.create(\"CARBONE_API_TOKEN\", \"3\");\n```\n\n## Build commands\n\nAt the root of the SDK repository run:\n```sh\nmvn clean \u0026\u0026 mvn compile \u0026\u0026 mvn package\n```\nThen you can create a local build of the SDK:\n``` sh\nmvn install:install-file -Dfile=/your/local/file.jar  -DgroupId=io.carbone -DartifactId=CarboneSDK -Dversion=x.x.x  -Dpackaging=jar\n```\n\nIn another Java project, you can load the local build of the SDK, in the pom.xml:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.carbone\u003c/groupId\u003e\n    \u003cartifactId\u003eCarboneSDK\u003c/artifactId\u003e\n    \u003cversion\u003ex.x.x\u003c/version\u003e\n\u003c/dependency\u003e\n```\nFinally, compile your Java project with the SDK:\n```sh\nclean compile \u0026\u0026 mvn exec:java -Dexec.mainClass=\"local.test.CarboneCloudSdkJava\n```\n\n## Test commands\n\nExecute unit tests:\n```sh\nmvn test\n````\nExecute unit tests with coverage:\n```mvn\nmvn clean test jacoco:report  \n```\nTo get the coverage analysis, open the coverage file:\n`./target/site/jacoco/index.html`\n\n\n## 👤 History\n\nThe package was originaly made by Benjamin COLOMBE @bcolombe from [Tennaxia](https://www.tennaxia.com/), and open-sourced the code.\nThe Carbone.io team is now maintaining the SDK and will bring all futur evolutions.\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome!\n\nFeel free to check [issues page](https://github.com/carboneio/carbone-sdk-java/issues).\n\n## Show your support\n\nGive a ⭐️ if this project helped you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarboneio%2Fcarbone-sdk-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarboneio%2Fcarbone-sdk-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarboneio%2Fcarbone-sdk-java/lists"}