Custom PDF Rendering

​

Übersicht

• Vollständige Design-Kontrolle: Gestalte Belege exakt nach deinen Corporate-Design-Vorgaben
• Eigene Template-Engines: Nutze deine bevorzugte Template-Engine (LaTeX, Typst, etc.)
• Komplexe Layouts: Erstelle mehrseitige Dokumente mit komplexen Tabellen und Grafiken
• Integration mit bestehenden Systemen: Binde deine vorhandene Dokumentengenerierung nahtlos ein

​

Funktionsweise

1. Beleg wird finalisiert: Wenn ein Beleg finalisiert wird, wechselt er in den Status STATUS_FINALIZING
2. Webhook wird ausgelöst: Fynn sendet den invoice.pdf.generation_requested Webhook mit allen Belegdaten
3. PDF generieren: Dein System generiert das PDF mit deiner eigenen Rendering-Engine
4. PDF hochladen: Das fertige PDF wird über die API an Fynn zurückgesendet
5. Finalisierung abschließen: Fynn schließt den Finalisierungsprozess ab (ZUGFeRD-Einbettung, Versand, etc.)

​

Konfiguration

​

1. Feature aktivieren

​

2. Webhook registrieren

POST /webhooks
{
    "url": "https://your-server.com/webhooks/fynn",
    "events": ["invoice.pdf.generation_requested"],
    "version": "v1",
    "enabled": true
}

​

3. Einstellungen konfigurieren

​

Webhook-Payload

{
    "event": {
        "id": "01JKXYZ1234567890ABCDEFGH",
        "type": "invoice.pdf.generation_requested",
        "version": "v1",
        "createdAt": "2026-02-09T10:00:00+00:00"
    },
    "data": {
        "invoice": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "number": "RE-2026-0001",
            "type": "TYPE_INVOICE",
            "status": "STATUS_FINALIZING",
            ...
        }
    }
}

​

PDF hochladen

curl -X POST "https://coreapi.io/api/invoices/{invoiceId}/pdf" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@invoice.pdf"

​

Endpoint-Details

​

Request

• Content-Type: multipart/form-data
• Feld: file - Die PDF-Datei (MIME-Type: application/pdf)

​

Response

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "STATUS_UNPAID",
    "message": "PDF uploaded and invoice finalization continued."
}

​

Fehlercodes

​

Timeout und Fallback

• Mit aktiviertem Fallback: Nach Ablauf des Timeouts generiert Fynn das PDF automatisch mit der internen Rendering-Engine
• Ohne Fallback: Der Beleg bleibt im Status STATUS_FINALIZING bis das PDF manuell hochgeladen wird

​

ZUGFeRD-Einbettung

​

Best Practices

​

Webhook-Verarbeitung

1. Asynchrone Verarbeitung: Bestätige den Webhook sofort (HTTP 200) und verarbeite die PDF-Generierung asynchron
2. Idempotenz: Implementiere Idempotenz, um doppelte Webhook-Aufrufe zu handhaben
3. Retry-Logik: Implementiere Retries für den PDF-Upload bei temporären Fehlern

​

PDF-Anforderungen

• Format: PDF/A-3 wird empfohlen für beste ZUGFeRD-Kompatibilität
• Größe: Maximal 10 MB
• Qualität: Mindestens 150 DPI für eingebettete Bilder

​

Sicherheit

• Validiere die Webhook-Signatur
• Nutze HTTPS für alle API-Aufrufe
• Speichere API-Tokens sicher

​

Beispiel-Implementierung (Node.js)

const express = require('express');
const crypto = require('crypto');
const FormData = require('form-data');
const axios = require('axios');

const app = express();
app.use(express.json());

app.post('/webhooks/fynn', async (req, res) => {
    // 1. Webhook sofort bestätigen
    res.status(200).send('OK');

    // 2. Signatur validieren
    const signature = req.headers['x-fynn-signature'];
    const expectedSignature = crypto
        .createHmac('sha256', process.env.WEBHOOK_SECRET)
        .update(JSON.stringify(req.body))
        .digest('hex');

    if (signature !== expectedSignature) {
        console.error('Invalid webhook signature');
        return;
    }

    // 3. PDF generieren (deine eigene Logik)
    const { invoice } = req.body.data;
    const pdfBuffer = await generateInvoicePdf(invoice);

    // 4. PDF an Fynn hochladen
    const form = new FormData();
    form.append('file', pdfBuffer, {
        filename: `invoice-${invoice.number}.pdf`,
        contentType: 'application/pdf'
    });

    await axios.post(
        `https://coreapi.io/api/invoices/${invoice.id}/pdf`,
        form,
        {
            headers: {
                ...form.getHeaders(),
                'Authorization': `Bearer ${process.env.FYNN_API_TOKEN}`
            }
        }
    );
});

async function generateInvoicePdf(invoice) {
    // Implementiere hier deine PDF-Generierung
    // z.B. mit Puppeteer, PDFKit, LaTeX, etc.
}

​

Troubleshooting

​

PDF wird nicht akzeptiert

• Stelle sicher, dass die Datei ein gültiges PDF ist
• Überprüfe, dass der Beleg im Status STATUS_FINALIZING ist
• Validiere, dass du die richtige Invoice-ID verwendest

​

Webhook wird nicht empfangen

• Überprüfe, dass der Webhook für invoice.pdf.generation_requested registriert ist
• Stelle sicher, dass dein Endpoint erreichbar ist
• Überprüfe die Webhook-Logs in den Fynn-Einstellungen

​

Timeout-Fehler

• Erhöhe den timeoutMinutes-Wert
• Optimiere deine PDF-Generierung
• Aktiviere den Fallback für kritische Situationen

​

API-Referenz