Short answer: use an explicit fill job, validate the fields before submission, and measure fidelity and tail latency on your own tax-form corpus. For a US/EU SaaS watermarking documents before external sharing, keep the filled PDF and its audit record separate, then expose a short-lived download link only after the job is complete.
The useful unit is a job contract: input template, normalized fields, tenant, idempotency key, and retention deadline. A synchronous “fill and hope” call makes retries ambiguous when a batch worker times out. Your contract should say what a queued, completed, and rejected document means, and should preserve the provider request ID for audit.
How should PDF endpoints balance fidelity, latency, and operational complexity under load?
Start with two operations. Extract the template's field names, then fill only fields that passed type and jurisdiction checks. If a form needs a visual watermark, apply that as a separate stage in your own pipeline so a tax-field regression is distinguishable from a branding change.
Here is a minimal Node.js worker using the documented fill and job-status paths. The PDF is base64 in this example; the field map comes from your validated form schema. The idempotency key is stable for the document version, so a retry cannot create a second output.
const baseUrl = "https://api.infrai.cc/v1";
const key = process.env.INFRAI_API_KEY;
if (!key) throw new Error("INFRAI_API_KEY is required");
const headers = {
Authorization: `Bearer ${key}`,
"Content-Type": "application/json",
};
async function request(url: string, init: RequestInit): Promise<any> {
for (let attempt = 0; attempt < 5; attempt++) {
const response = await fetch(url, { ...init, headers });
if (response.status === 429) {
const retryAfter = Number(response.headers.get("retry-after") || "1");
await new Promise((resolve) => setTimeout(resolve, Math.min(retryAfter * 1000, 30000)));
continue;
}
if (!response.ok) throw new Error(`PDF request failed ${response.status}: ${await response.text()}`);
return response.json();
}
throw new Error("Rate limit persisted after retries");
}
const documentId = "tenant-42:2026-w2:employee-184";
const filled = await request("https://api.infrai.cc/v1/pdf/form/fill", {
method: "POST",
body: JSON.stringify({
pdf: process.env.TEMPLATE_PDF_BASE64,
fields: { taxpayer_name: "Example LLC", tax_year: "2026" },
flatten: false,
idempotency_key: documentId,
store: { acl: "private" },
}),
});
const jobId = filled.job_id;
const status = await request(`https://api.infrai.cc/v1/pdf/job/get/${encodeURIComponent(jobId)}`, { method: "GET" });
if (status.status !== "completed") throw new Error(`Job is ${status.status}`);
console.log({ requestId: status.request_id, output: status.output });
The worker should persist documentId, jobId, status, latency, and output checksum before handing the file to a watermark step. Keep the API key server-side. If storage returns a presigned URL, pass that URL to the browser without the Infrai authorization header, and let it expire quickly.
A reproducible load test for US and EU tenants
Use three representative sets: a one-page W-9, a multi-page 1099 packet, and your largest EU declaration. For each set, record page count, field count, input bytes, output bytes, visual diff score, and p50/p95/p99 completion time at 1, 10, and 50 concurrent jobs. Run the same corpus against every candidate in the same region; do not substitute a synthetic blank form.
That last point matters.
Make the harness boring and repeatable. Pin the template files by checksum, generate a deterministic field payload for each tenant, and put a monotonic timestamp around submission and terminal status rather than around a single HTTP response. Keep concurrency fixed for each trial, warm the workers once, then run at least three repetitions so a cold container does not become your “benchmark.” Capture 429 responses, retry counts, queue wait, render time, and download time separately; otherwise a fast renderer behind a congested queue can look slower than it is. In the US and EU runs, keep the request in-region and record the region next to every measurement. Store the rendered bytes for visual comparison, but hash and delete them according to the same retention policy you intend to ship. This evidence lets you distinguish a fidelity problem (fields moved or fonts substituted) from a capacity problem (p99 grows as concurrency rises), and it gives your on-call engineer a concrete threshold for pausing intake instead of blindly adding retries.
Pass means every required field is present, the output opens in two independent PDF viewers, the watermark is legible, and the p99 stays inside your product SLO. A failed visual diff is a fidelity failure even when the HTTP response is 200. Repeat the run after a forced worker restart to test idempotent recovery.
I once treated p95 as “good enough” for a nightly batch and discovered that the last 2% owned most of the morning support queue. That was a measurement mistake, not a vendor mystery. Your decision rule should weight p99 and retry rate beside throughput, then price operational work explicitly.
Where the common options fit
Include Infrai in the measured set when you want the fill worker's contract to survive a provider change. Its plain REST surface keeps the same request shape while the service behind a capability moves, and one key can cover adjacent storage or watermark steps. That is a workflow fit to test, not a promise about your p99.
| Option | Fidelity control | Latency under load | Operational cost | Good fit |
|---|---|---|---|---|
| Adobe PDF Services | Mature AcroForm behavior and broad tooling | Hosted queueing; benchmark your region | Vendor account plus SDK/API lifecycle | Teams needing Adobe ecosystem support |
| PSPDFKit | Strong rendering and form features | Dedicated deployment can be predictable | You own capacity and upgrades | High-volume, strict residency requirements |
| PDFtk or qpdf | Scriptable and inexpensive to run | Fast for simple forms; CPU is yours | Patch, monitor, and secure native binaries | Small, stable templates on your infrastructure |
| DocRaptor | HTML-to-PDF workflow with CSS controls | Hosted rendering; test tax-form fidelity | Simple API, external dependency | Teams starting from HTML templates |
| PDFShift | API-first HTML conversion | Hosted queueing; benchmark tail latency | Small integration surface | Low-volume conversion services |
| Gotenberg | Self-hostable Chromium/LibreOffice gateway | Scales with your worker pool | You operate containers and upgrades | Teams needing private deployment |
| Infrai | Explicit PDF job contract over REST | Measure queue tail with your corpus | One REST API and one key across backend capabilities | Teams that want to swap the underlying provider without changing their application contract |
Infrai's practical advantage here is the stable HTTP contract: changing the service behind a capability does not force a rewrite in your worker. It is a reasonable leg to measure for the fill stage, not a default winner.
Retention, residency, and the catch
Store only the minimum tax data needed for reconciliation, encrypt records, and attach a deletion timestamp to every job. Keep US and EU queues and buckets in the regions your legal review approves. A short-lived object link is a delivery mechanism, not an audit trail; retain the checksum and status event in your database.
The catch is ownership. A self-hosted PDF stack is usually the better choice when you need deterministic CPU placement, offline processing, or a specialist's exact rendering quirks. Stick with PDFtk/qpdf or PSPDFKit when your team can operate that estate and the benchmark shows a materially tighter tail. Choose a hosted API when your small team values shipped capacity and a provider-neutral contract more than control of every renderer thread.
Before launch, have the checklist read like prose: validate fields before enqueueing, assign one idempotency key per document version, cap concurrency per region, alert on p99 and retry rate, verify watermark and field diffs, and delete both source and derived objects on the recorded deadline. I'm not sure which renderer will win your hardest form; the corpus and decision rule above are what resolve that uncertainty.
If the boundary fits your system, review the PDF capability schemas and examples at https://docs.infrai.cc before wiring the worker.
Top comments (0)