.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.
Install
Section titled “Install”The project lives in the necodoc repository (packages/sdk-dotnet/src/Necodoc.Sdk) and isn’t on
NuGet yet. Reference it from a checkout:
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 ReleaseCreate a client
Section titled “Create a client”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.
Render HTML to a PDF
Section titled “Render HTML to a PDF”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);}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 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.PdfPathSigning packages
Section titled “Signing packages”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).
Async renders
Section titled “Async renders”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.
Errors
Section titled “Errors”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.
Smoke example
Section titled “Smoke example”examples/Smoke/Program.cs renders HTML, generates from a template as JSON and as a
signing package:
cd packages/sdk-dotnet/examples/SmokeNECODOC_URL=http://localhost:3000 NECODOC_API_KEY=nd_… \NECODOC_TEMPLATE_ID=<uuid> NECODOC_TEMPLATE_DATA='{"client_name": "Acme"}' dotnet runRegenerate
Section titled “Regenerate”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.