Skip to content

.NET SDK

A typed .NET client for the necodoc public API (/api/v1), generated by openapi-generator (generichost library) from the API’s OpenAPI document: System.Text.Json models, HttpClient through Microsoft.Extensions.Http, one typed response per status. Targets net8.0.

The project lives in the necodoc repository (packages/sdk-dotnet/src/Necodoc.Sdk) and isn’t on NuGet yet. Reference it from a checkout:

Terminal window
dotnet add reference path/to/necodoc/packages/sdk-dotnet/src/Necodoc.Sdk/Necodoc.Sdk.csproj
# or build a package: dotnet pack packages/sdk-dotnet/src/Necodoc.Sdk -c Release

The APIs are registered with dependency injection, in a host or a plain ServiceCollection:

using Microsoft.Extensions.DependencyInjection;
using Necodoc.Sdk.Api;
using Necodoc.Sdk.Client;
using Necodoc.Sdk.Extensions;
using Necodoc.Sdk.Model;
var services = new ServiceCollection();
services.AddLogging();
services.AddApi(options =>
{
// The third argument is the prefix: none, the key goes in x-api-key as is.
options.AddTokens(new ApiKeyToken(apiKey, ClientUtils.ApiKeyHeader.X_api_key, ""));
options.AddApiHttpClients(client =>
client.BaseAddress = new Uri("https://necodoc.example.com/api/v1")); // no trailing slash
});
var provider = services.BuildServiceProvider();
var render = provider.GetRequiredService<IRenderApi>();

There’s one interface per API group: IRenderApi, ITemplatesApi, IBatchesApi, IGenerationsApi, ICombineApi. Method names are the operation ids in Pascal case with Async (postRender → PostRenderAsync). In a host, use builder.ConfigureApi(...) instead.

var response = await render.PostRenderAsync(new RenderRequest(
html: "<h1>Invoice {{ number }}</h1>",
data: new Dictionary<string, object> { ["number"] = "A-1001" },
footer: new RenderRequestHeader("<p>{{ page }} / {{ pages }}</p>", 12)));
if (response.TryOk(out var pdf))
{
await using var file = File.Create("invoice.pdf");
await pdf.CopyToAsync(file);
}

Render and generate answer 200 with either the PDF or JSON, so the SDK always hands back a stream. With response: Json, deserialize it with the SDK’s serializer options:

var json = provider.GetRequiredService<JsonSerializerOptionsProvider>().Options;
var templates = provider.GetRequiredService<ITemplatesApi>();
var data = new Dictionary<string, object> { ["client_name"] = "Acme" };
var generated = await templates.PostTemplatesByIdVersionsByVersionGenerateAsync(templateId, "latest",
new GenerateRequest(data: data, response: RenderRequestResponse.Json));
var result = JsonSerializer.Deserialize<GenerationResult>(generated.Ok()!, json)!;
// result.GenerationId, result.DownloadUrl (signed, 1 hour), result.PdfPath

With json, templates and data from the previous example:

var signing = await templates.PostTemplatesByIdVersionsByVersionGenerateAsync(templateId, "latest",
new GenerateRequest(data: data, signing: new SigningOptions(true, default)));
var package = JsonSerializer.Deserialize<SigningPackage>(signing.Ok()!, json)!;
// package.Boxes[i].TopLeft, package.Formats.Docusign (envelope JSON)

IGenerationsApi.GetGenerationsByIdSigningPackageAsync(generationId) returns the same for an earlier generation, already typed (.Ok() is a SigningPackage).

With async: true, PostRenderAsync answers 202: response.TryAccepted(out var pending) gives a PendingGeneration. Poll GetGenerationsByIdAsync until Status is success or error, then fetch the PDF with GetGenerationsByIdPdfAsync.

Calls don’t throw on API errors. Check IsOk, or TryUnprocessableContent(out var error) and friends for the typed Error body ({ error, code, fieldErrors? }); RawContent has the raw JSON. On 429, wait for the Retry-After header.

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

Terminal window
cd packages/sdk-dotnet/examples/Smoke
NECODOC_URL=http://localhost:3000 NECODOC_API_KEY=nd_… \
NECODOC_TEMPLATE_ID=<uuid> NECODOC_TEMPLATE_DATA='{"client_name": "Acme"}' dotnet run

Everything except this README and examples/ is generated. 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.