Aus einem anderen Service

Die API ist einfaches HTTP mit JSON, jedes Backend kann sie also aufrufen. Nötig ist nur der Header x-api-key, weshalb das Backend der natürliche Ort dafür ist: der Key verlässt deine Infrastruktur nie.

Aus einem 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-Erzeugung fehlgeschlagen: ${response.status}`)
    }
 
    const { generatedDocuments } = await response.json()
    return generatedDocuments[0].url
}

Aus einer Frontend-App

Ein Browser darf nie einen API-Key halten. Das Erzeugen bleibt deshalb dort, wo es ohnehin schon ist: in deinem Backend, genau wie oben. Das Frontend fragt nur deinen eigenen Endpunkt nach dem Dokument.

Die Übergabe der zurückgegebenen url an den Browser funktioniert nicht: Es handelt sich um einen Endpunkt des Tuix-PDF-Dienstes, und der Browser übermittelt den API-Schlüssel nicht. Laden Sie die Datei in Ihrem Backend herunter und stellen Sie sie von dort bereit, siehe PDF herunterladen.

Browser ──▶ dein Endpunkt ──x-api-key──▶ Tuix PDF Service
        ◀── PDF bytes ─────

Betriebshinweise

• Stapel. Eine Anfrage kann viele payloads enthalten. Der Service rendert bis zu fünf Dokumente parallel und antwortet, wenn der ganze Stapel fertig ist.
• Timeouts. Das Rendern läuft synchron, ein grosser Stapel bedeutet also eine lange Anfrage. Teile grosse Jobs auf oder verlagere sie in einen Hintergrund-Worker.
• Fehler. Ein fehlerhaftes Dokument lässt die ganze Anfrage scheitern, auch für die erfolgreichen. Bei einem erneuten Versuch werden alle Dokumente des Stapels neu gerendert.
• Zuordnung. id kommt bei jedem erzeugten Dokument zurück. Setze sie auf deine eigene Entitäts-ID, dann brauchst du dich nicht auf die Reihenfolge im Array zu verlassen.
• Key pro Nutzer. Gib jedem nutzenden Service einen eigenen API-Key, damit einzelne widerrufen werden können, siehe API-Keys.