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.
Install
Section titled “Install”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:
cd packages/sdk-java && mvn install -DskipTests<dependency> <groupId>dev.necodoc</groupId> <artifactId>necodoc-sdk</artifactId> <version>0.1.0</version></dependency>Create a client
Section titled “Create a client”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.
Render HTML to a PDF
Section titled “Render HTML to a PDF”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.
Generate from a template, as JSON
Section titled “Generate from a template, as JSON”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()Signing packages
Section titled “Signing packages”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).
Async renders
Section titled “Async renders”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.
Errors
Section titled “Errors”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()).
Smoke example
Section titled “Smoke example”examples/Smoke.java renders HTML, generates from a template as JSON and as a
signing package:
cd packages/sdk-javamvn -q compile dependency:build-classpath -Dmdep.outputFile=target/classpath.txtNECODOC_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.javaRegenerate
Section titled “Regenerate”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.