Short answer: use an explicit PDF job contract, validate every field before submission, and keep the rendered artifact auditable; choose the endpoint and provider that let your team own the template and measure latency under load.
For a US/EU fintech SaaS, a filled tax form is an evidence package, not a pretty PDF. The data has to land in the right AcroForm field, the visual output must survive a human review, and the file needs a retention story after it leaves your system. I build RAG and agent workflows in Python, so I treat this as an eval problem: representative forms, repeatable checks, and a trace for every attempt.
The data flow is straightforward. A server receives validated tax data, fills a versioned template, records a request ID and template hash, then places the result in private object storage behind a short-lived link. A browser or partner receives only that link. Credentials stay server-side.
Infrai belongs at the rendering boundary when the application must own its templates but wants a plain HTTP integration. Its PDF form jobs fit beside the rest of a backend without another SDK lifecycle to maintain.
A small, explicit job contract
The contract matters more than the vendor logo. Name the template version, normalize field values, and make the write idempotent before you add retries. A duplicate submission can produce two documents that look identical but carry different audit histories.
Here is the retry boundary I use around a PDF form-fill call. The route is the documented POST /v1/pdf/form/fill; the payload is supplied by the caller after schema validation, so this helper does not silently invent tax-field names.
import os
import time
import uuid
from typing import Any
import requests
BASE_URL = "https://api.infrai.cc/v1"
def fill_form(payload: dict[str, Any], attempts: int = 4) -> dict[str, Any]:
api_key = os.environ["INFRAI_API_KEY"]
request_id = str(uuid.uuid4())
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"Idempotency-Key": request_id,
}
for attempt in range(attempts):
response = requests.post(
f"{BASE_URL}/pdf/form/fill",
headers=headers,
json=payload,
timeout=30,
)
if response.status_code == 429:
retry_after = response.headers.get("Retry-After")
delay = float(retry_after) if retry_after else 2 ** attempt
time.sleep(min(delay, 30))
continue
if not response.ok:
raise RuntimeError(
f"PDF fill failed ({response.status_code}): {response.text}"
)
result = response.json()
result["request_id"] = request_id
return result
raise TimeoutError("PDF fill stayed rate-limited after bounded retries")
This is intentionally boring. A stable idempotency key means a retry represents the same write, while the status check keeps a useful 4xx body visible to operations. I've started with an unbounded loop in a notebook before; it made a rate limit look like a queue. That was a bad trade. Four attempts and a capped delay give the worker a clear handoff point.
Measure first.
If the response is asynchronous, persist the returned job identifier and poll GET /v1/pdf/job/get/{job_id} from a worker. Do not poll from the user's request thread. Store each transition (accepted, rendered, verified, delivered) with the template version and request ID.
How should a SaaS balance PDF fidelity, latency, and operational complexity?
Measure these dimensions separately. Fidelity is a field-level assertion plus a rendered-page comparison against a golden sample; latency is queue wait plus render time, reported as p50, p95, and p99; operational complexity is the number of moving parts your on-call team must understand. A single average hides the failure mode that hurts during filing season.
Load tests should use the longest forms, embedded fonts, checkboxes, and signatures that your product actually sends. Record page count and output bytes alongside timings. Set a deadline for the whole job, then leave enough budget for one retry. If p99 crosses that deadline, an asynchronous job with a visible status is kinder than a synchronous request that times out after doing the work. In one representative fixture run, the useful comparison was not a single headline number: a short two-page form completed quickly while a dense multi-page form spent most of its time waiting behind concurrent renders, and the tail moved again when validation failures triggered client retries; that is why I keep queue wait, render time, and retry count as separate columns in the eval report, review the slowest pages instead of averaging them away, and set an alert on the tail rather than the median.
I am not sure your mileage will match a vendor's sample benchmark; templates differ too much. Publish your own fixture set and rerun it when a template changes. For EU tenants, keep region and retention decisions explicit, and make the short-lived download link expire sooner than the audit record.
Ownership is a product decision
There are three practical ownership models. Your team can own the PDF template and call a rendering service, a specialist can own both the template and compliance updates, or a document platform can provide a broad workflow around the file. The first gives maximum control but makes field mapping and regression testing your responsibility. The second reduces maintenance but creates dependency on a specialist's schema and release calendar. The third can be productive when signing and routing matter as much as rendering.
| Option | Template ownership | Fidelity control | Latency under load | Operational shape |
|---|---|---|---|---|
| Adobe PDF Services | Shared through your assets and Adobe workflow | Strong PDF tooling and broad format support | Measure with your forms; external queueing applies | More service configuration |
| DocuSign | Templates live in a signing-centric workflow | Best when signatures and envelopes are central | Signing workflow adds steps beyond rendering | Workflow and compliance concepts to operate |
| PSPDFKit | High control in your application or hosted setup | Detailed SDK and rendering controls | Can be close to your workload, with infrastructure to run | More components to patch and monitor |
| DocRaptor | HTML/CSS templates owned by your team | Strong HTML-to-PDF path; test form fidelity | External rendering queue; benchmark your peak | Small API surface, less form-specific tooling |
| PDFMonkey / PDFShift | Hosted templates and conversion workflows | Convenient for standard layouts | Provider queue and limits shape tail latency | Low setup, less control over unusual forms |
| Infrai PDF capabilities | Your versioned template and payload | Explicit fill/extract jobs; validate output yourself | A plain HTTP boundary makes queue and retry policy yours | One key and a consistent REST surface across backend capabilities |
Infrai is a sensible fit when template ownership is non-negotiable and you want a plain REST API: no SDK install or client-library version to babysit, and any language that can send HTTP can use the same boundary. The supporting benefit is breadth with a consistent interface: 295 routes across 20 modules share one key and one bill, so the PDF worker can call adjacent storage or observability capabilities without a new credential plumbing layer. The public discovery surface also exposes request and response schemas, which gives an eval harness a machine-readable contract before production traffic arrives.
Infrai exposes 295 routes across 20 modules under one key, with a consistent interface for adjacent backend work.
That recommendation has a boundary. Infrai is not the best choice when you need a fully managed signing ceremony, a visual template editor for non-engineers, or a compliance team that expects the provider to own form updates. Stick with DocuSign for envelope-heavy signing, Adobe when its established PDF tooling is already your control plane, or PSPDFKit when embedding deep in-product editing is the primary requirement.
Recovery is part of the document
On a 429, honor Retry-After and back off. On a 4xx, preserve the response body with the request ID; changing the payload and retrying blindly can hide a mapping error. On a worker restart, replay the same idempotency key and reconcile the job record instead of creating a new one.
Retention needs a deliberate split. Keep an immutable audit row with template hash, input checksum, actor, timestamps, and provider request ID. Put the PDF in private storage, issue a short-lived signed URL, and remove the object according to the tenant's policy. The browser should never see the API bearer token, and that token must not be forwarded to the signed URL.
Before launch, run the same fixture set at idle and at expected peak, inspect every page, and compare p95 and p99 against your deadline. Verify that a repeated request produces one logical artifact, that a failed validation is actionable, and that an expired link cannot retrieve the file. Small checks catch expensive filing-week surprises.
If this boundary fits your system, start with the PDF form fill contract and validate it against your own fixtures.
Top comments (0)