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+.
Install
Section titled “Install”The package lives in the necodoc repository (packages/sdk-python) and isn’t on PyPI yet. Install
it from a checkout:
pip install ./packages/sdk-python# or: uv add ./packages/sdk-pythonCreate a client
Section titled “Create a client”import osimport 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).
Render HTML to a PDF
Section titled “Render HTML to a PDF”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)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 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_pathSigning packages
Section titled “Signing packages”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.
Async renders
Section titled “Async renders”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.
Errors
Section titled “Errors”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).
Smoke example
Section titled “Smoke example”examples/smoke.py renders HTML, generates from a template as JSON and as a
signing package:
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.pyRegenerate
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.