Skip to content

Java SDK

A typed Java client for the necodoc public API (/api/v1), generated by openapi-generator (native library) from the API’s OpenAPI document: java.net.http transport, Jackson models, Java 11+, Maven.

The library lives in the necodoc repository (packages/sdk-java) and isn’t on Maven Central yet. Install it into your local repository from a checkout, then depend on it:

Terminal window
cd packages/sdk-java && mvn install -DskipTests
<dependency>
<groupId>dev.necodoc</groupId>
<artifactId>necodoc-sdk</artifactId>
<version>0.1.0</version>
</dependency>
import dev.necodoc.sdk.ApiClient;
import dev.necodoc.sdk.api.RenderApi;
ApiClient client = new ApiClient();
client.updateBaseUri("https://necodoc.example.com/api/v1");
client.setRequestInterceptor(request -> request.header("x-api-key", apiKey)); // nd_…
RenderApi render = new RenderApi(client);

There’s one class per API group: RenderApi, TemplatesApi, BatchesApi, GenerationsApi, CombineApi. Method names are the operation ids (postRender). Each has a …WithHttpInfo variant that also returns the status and headers.

File pdf = render.postRender(new RenderRequest()
.html("<h1>Invoice {{ number }}</h1>")
.data(Map.of("number", "A-1001"))
.footer(new RenderRequestHeader().html("<p>{{ page }} / {{ pages }}</p>").height(BigDecimal.valueOf(12))));
Files.copy(pdf.toPath(), Path.of("invoice.pdf"));

Binary answers arrive as a temporary File.

Render and generate answer 200 with either the PDF or JSON, so the SDK always hands back a file. With response(JSON), read it with the SDK’s Jackson mapper:

ObjectMapper json = JSON.getDefault().getMapper();
TemplatesApi templates = new TemplatesApi(client);
Map<String, Object> data = Map.of("client_name", "Acme");
File body = templates.postTemplatesByIdVersionsByVersionGenerate(templateId, "latest",
new GenerateRequest().data(data).response(RenderRequestResponse.JSON));
GenerationResult result = json.readValue(body, GenerationResult.class);
// result.getGenerationId(), result.getDownloadUrl() (signed, 1 hour), result.getPdfPath()

With json, templates and data from the previous example:

File signingBody = templates.postTemplatesByIdVersionsByVersionGenerate(templateId, "latest",
new GenerateRequest().data(data).signing(new SigningOptions(true)));
SigningPackage signing = json.readValue(signingBody, SigningPackage.class);
// signing.getBoxes().get(i).getTopLeft(), signing.getFormats().getDocusign() (envelope JSON)

GenerationsApi.getGenerationsByIdSigningPackage(generationId, formats, embedPdf, placement) returns the same for an earlier generation, already typed (pass null for defaults).

With async(true), use postRenderWithHttpInfo: on a 202 the file holds a PendingGeneration (read it with the mapper). Poll GenerationsApi.getGenerationsById(id) until the status is success or error, then fetch the PDF with getGenerationsByIdPdf.

Non-2xx answers throw ApiException: getCode() is the status and getResponseBody() the API’s error JSON ({ error, code, fieldErrors? }). On 429, wait for Retry-After (getResponseHeaders()).

examples/Smoke.java renders HTML, generates from a template as JSON and as a signing package:

Terminal window
cd packages/sdk-java
mvn -q compile dependency:build-classpath -Dmdep.outputFile=target/classpath.txt
NECODOC_URL=http://localhost:3000 NECODOC_API_KEY=nd_… \
NECODOC_TEMPLATE_ID=<uuid> NECODOC_TEMPLATE_DATA='{"client_name": "Acme"}' \
java -cp "target/classes:$(cat target/classpath.txt)" examples/Smoke.java

Everything except this README and examples/ is generated (Maven build only). Run pnpm sdk:generate from the repository root (needs Java 11+). docs/adrs/0041-*.md in the repository explains the generator choice and the small compatibility pass applied to the OpenAPI document first.