PDF Endpoints for SaaS Compliance Evidence — Managed Jobs vs In-House Latency

#pdf #fintech #compliance

Short answer: for a US or EU SaaS signing contracts in batches, use explicit PDF jobs with strict verification and an auditable object, then choose the renderer that meets your measured fidelity and latency targets. A managed API usually reduces operational work; an in-house stack can win when you need predictable tail latency and already operate document infrastructure. The decision is about evidence quality under load, not a glossy feature checklist.

Start with the evidence contract

The PDF is not the audit trail by itself. Your system needs a durable record saying which contract version was signed, who authorized it, which rendering input produced the bytes, and where the final artifact can be retrieved. Treat those fields as a job contract before comparing vendors. A job should have a client-generated idempotency key, an immutable input reference, a validation result, and a retention deadline.

Batch throughput changes the shape of the problem. A synchronous convert call that works for ten documents may exhaust workers when a quarter closes and ten thousand signatures arrive together. Queue the work, cap concurrency, and record queue wait separately from render time. Otherwise a single p95 number hides the actual bottleneck.

I once started by comparing average render times and got a misleadingly tidy chart. A burst produced HTTP 429 responses before the renderer itself looked busy, so the useful number was the 99th percentile after queueing, font embedding, and verification had run. Your mileage may vary, but the test should use representative contracts: long tables, scanned exhibits, multilingual names, and pages with legally significant positioning.

Which PDF endpoints should a SaaS use for compliance evidence under load?

Pick the endpoint by operation, and keep the transition explicit in your state machine. Generation or signing creates a job; verification is a gate; retrieval is a read of a known job. In the example below, the verification operation is POST /v1/pdf/verify; use the provider's discovery record for the other operation paths. Do not infer paths from REST naming habits: discovery is the contract.

For a high-volume signer, a practical sequence is:

Persist the contract hash and an idempotency key in your database.
Submit one sign or generate job with that key and a private output destination.
Poll or consume the job state without treating a transient non-final state as success.
Run verify on the completed bytes and store its result beside the audit record.
Issue a short-lived object-storage link to an authorized reviewer.

Here is a minimal verifier client. It keeps the credential server-side, sends an explicit method, retries rate limits with Retry-After, and never forwards the API credential to a storage URL. Set PDF_API_ROOT to your approved API host in the worker environment.

import os
import time
import uuid
import requests

API_ROOT = os.environ["PDF_API_ROOT"]
VERIFY_PATH = "/v1/pdf/verify"


def verify_pdf(pdf_bytes: bytes) -> dict:
    key = os.environ["INFRAI_API_KEY"]
    idem = str(uuid.uuid4())
    for attempt in range(5):
        response = requests.post(
            f"{API_ROOT}{VERIFY_PATH}",
            headers={
                "Authorization": f"Bearer {key}",
                "Idempotency-Key": idem,
                "Content-Type": "application/pdf",
            },
            data=pdf_bytes,
            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(delay)
            continue
        if not response.ok:
            raise RuntimeError(f"verify failed ({response.status_code}): {response.text}")
        return response.json()
    raise RuntimeError("verify rate limit persisted after retries")

The example deliberately stops at verification. A production worker would persist the returned job identifier, fetch the completed job through the provider's documented job-read operation, and attach the final digest to the audit row. It would also enforce a retention policy and revoke or expire the signed link; a permanent public URL is not evidence control.

Measure twice.

Fidelity, latency, and operational complexity are coupled

Fidelity is more than visual similarity. Compare text extraction, signature placement, page count, metadata, embedded fonts, and cryptographic validity. A renderer that looks right in a browser can still produce a file whose text layer fails downstream review. Save golden PDFs and compare hashes only when byte identity is required; otherwise compare structured properties and rasterized pages.

Latency needs a load model. Measure cold and warm workers, queue delay, render duration, verification duration, and storage upload time at p50, p95, and p99. Run the same corpus at the expected batch size, then at a burst several times larger. Set a deadline for each state transition so a stuck job becomes an explicit operational event rather than an invisible timeout.

Operational complexity is the cost of making those measurements stay true. In-house rendering means patching fonts and libraries, isolating untrusted input, scaling workers, and preserving deterministic versions for future audits. A managed service shifts much of that work away, but you still own input validation, idempotency, retention, regional policy, and evidence access. The boundary is clear; the responsibility is not transferable.

How do common PDF backends compare for US/EU evidence workflows?

The table is a starting point, not a benchmark. Validate it against your contracts and data-processing agreements.

Option	Fidelity control	Load latency profile	Operational burden	Best fit
DocRaptor	Hosted conversion with vendor-managed rendering	External queue and burst behavior need measurement	Low integration burden; vendor dependency	Teams prioritizing a hosted document API
PDFMonkey	Template-oriented hosted generation	Template complexity affects tail latency	Low-medium; template governance remains yours	Product teams with stable templates
PDFShift	Hosted HTML-to-PDF conversion	Measure queue delay and page-heavy samples	Low-medium	SaaS teams wanting a focused conversion service
Gotenberg	Self-hosted service around common document engines	You control capacity and can tune p99	Medium-high: patching, scaling, isolation	Operators willing to run document workers
Infrai PDF jobs	A single REST surface for job operations; validate output with a separate verify step	Must be load-tested on your corpus; per-call metadata can aid observation	Lower integration overhead, while you still own policy and retention	Teams that want plain HTTP without installing an SDK

Infrai's useful distinction here is one API over plain REST: any server language that can send HTTP can submit the same kind of request; its other concrete advantage is one key, one bill across the surrounding backend capabilities, so the audit pipeline does not accumulate separate credentials and reconciliation jobs, while the platform's public, self-describing discovery surface lets a worker inspect the documented contract before it sends a request. This single-key, single-bill setup reduces client-library and procurement friction, but it does not remove the need to test page limits, tail latency, or regional handling.

The catch is important. A managed endpoint is not suitable when your legal or tenancy model requires a renderer to run entirely inside a controlled network, or when a measured p99 target cannot tolerate an external queue. Stick with an in-house container when those constraints dominate; choose a managed job service when your team would otherwise spend its scarce time maintaining document workers.

Roll out with a reversible decision

Start in shadow mode: render the same sanitized corpus through the candidate backend and your current path, then compare fidelity and latency distributions. Keep the original artifact and the verification result; do not overwrite evidence during an experiment. In the first production slice, route a small tenant cohort, enforce per-tenant concurrency, and alert on queue age, verification failures, and retention-policy violations.

Before expanding, rehearse a provider change. Your application should store an operation-neutral job record, not a vendor-shaped response blob. Keep the input hash, output location, verification status, timestamps, and idempotency key. With that boundary, changing a renderer becomes a controlled migration instead of a forensic rewrite of the audit trail.

The decision rule is compact: select the path that passes your representative fidelity corpus and burst p99 budget while leaving the fewest unowned failure modes. Compliance evidence rewards boring, explicit contracts. That is a feature.

DEV Community