Skip to content

Python SDK

A typed Python client for the necodoc public API (/api/v1), generated by openapi-generator from the API’s OpenAPI document: pydantic v2 models, urllib3 transport, Python 3.10+.

The package lives in the necodoc repository (packages/sdk-python) and isn’t on PyPI yet. Install it from a checkout:

Terminal window
pip install ./packages/sdk-python
# or: uv add ./packages/sdk-python
import os
import necodoc
config = necodoc.Configuration(host="https://necodoc.example.com/api/v1")
config.api_key["apiKey"] = os.environ["NECODOC_API_KEY"] # nd_…
client = necodoc.ApiClient(config)

There’s one class per API group: RenderApi, TemplatesApi, BatchesApi, GenerationsApi, CombineApi. Method names are the operation ids from the API reference in snake case (postRender → post_render).

from necodoc.models import RenderRequest, RenderRequestHeader
pdf: bytes = necodoc.RenderApi(client).post_render(
RenderRequest(
html="<h1>Invoice {{ number }}</h1>",
data={"number": "A-1001"},
footer=RenderRequestHeader(html="<p>{{ page }} / {{ pages }}</p>", height=12),
)
)
open("invoice.pdf", "wb").write(pdf)

Render and generate answer 200 with either the PDF or JSON, so the SDK always hands back bytes. With response="json", parse them with the model:

from necodoc.models import GenerateRequest, GenerationResult
body = necodoc.TemplatesApi(client).post_templates_by_id_versions_by_version_generate(
template_id, "latest", GenerateRequest(data={"client_name": "Acme"}, response="json")
)
result = GenerationResult.from_json(body)
# result.generation_id, result.download_url (signed, 1 hour), result.pdf_path
from necodoc.models import GenerateRequest, SigningOptions, SigningPackage
body = necodoc.TemplatesApi(client).post_templates_by_id_versions_by_version_generate(
template_id,
"latest",
GenerateRequest(data={"client_name": "Acme"}, signing=SigningOptions(True)),
)
package = SigningPackage.from_json(body)
# package.boxes[i].top_left, package.formats.docusign (envelope JSON)

GenerationsApi.get_generations_by_id_signing_package(generation_id) returns the same for an earlier generation, already typed.

With var_async=True (the async field), post_render returns a PendingGeneration (202). Poll GenerationsApi.get_generations_by_id(id) until status is success or error, then fetch the PDF with get_generations_by_id_pdf.

Non-2xx answers raise necodoc.ApiException (subclasses per status, e.g. UnprocessableEntityException). error.status is the status and error.body the API’s error JSON: { error, code, fieldErrors? }. On 429, wait for the Retry-After header (error.headers).

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

Terminal window
NECODOC_URL=http://localhost:3000 NECODOC_API_KEY=nd_… \
NECODOC_TEMPLATE_ID=<uuid> NECODOC_TEMPLATE_DATA='{"client_name": "Acme"}' \
uv run --with ./packages/sdk-python python packages/sdk-python/examples/smoke.py

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.