Call it from another service

The API is plain HTTP with JSON, so any backend can call it. The only requirement is the x-api-key header, which makes a backend the natural place to render from: the key never leaves your infrastructure.

From a backend service

const renderInvoice = async (order: Order) => {
    const response = await fetch(
        `${process.env.API_BASE_URL}/api/applications/${process.env.TUIX_PDF_APPLICATION_ID}/pdf-files`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'x-api-key': process.env.TUIX_PDF_API_KEY!,
            },
            body: JSON.stringify({
                payloads: [
                    {
                        id: order.id,
                        templateId: process.env.TUIX_PDF_TEMPLATE_ID,
                        data: { customerName: order.customer, total: order.total },
                    },
                ],
            }),
        },
    )
 
    if (!response.ok) {
        throw new Error(`PDF render failed: ${response.status}`)
    }
 
    const { generatedDocuments } = await response.json()
    return generatedDocuments[0].url
}

From a frontend app

A browser must never hold an API key, so the render itself stays where it already is: in your backend, exactly as above. The frontend only asks your own endpoint for the document.

Passing the returned url on to the browser does not work: it is an endpoint of the Tuix PDF Service, and the browser sends neither the API key. Download the file in your backend and serve it from there, see Download a PDF.

browser ──▶ your endpoint ──x-api-key──▶ Tuix PDF Service
        ◀── PDF bytes ─────

Operating notes

• Batching. One request may carry many payloads. The service renders up to five documents in parallel and answers when the whole batch is done.
• Timeouts. Rendering is synchronous, so a large batch means a long request. Split large jobs, or run them in a background worker.
• Errors. One failing document fails the entire request, nothing is returned for the successful ones. On a retry, all documents in that batch are rendered again.
• Correlation. id is echoed back on every generated document. Set it to your own entity ID to match results without relying on array order.
• Keys per consumer. Give every consuming service its own API key, so one can be revoked on its own. See API Keys.