Receipt Generation API

Receipt Generation API: ein PDF-Beleg für jede Zahlung

Wenn in Ihrem System eine Zahlung gelingt, bekommt Ihre Kundschaft einen Beleg im Markenlook — automatisch, in A4, Letter oder Thermobreite, angehängt an die E-Mail, die Sie ohnehin senden.

  • 50 kostenlose Renderings/Monat
  • Ohne Kreditkarte
  • 58 mm, 80 mm, A4 oder Letter

Was ist eine API zur Belegerstellung?

Eine API zur Belegerstellung macht aus einer abgeschlossenen Zahlung ein Dokument, das die Kundschaft behalten kann. Ihr System sendet Betrag, Zahlungsart, Posten und Datum; die API setzt sie in Ihre Markenvorlage ein und liefert ein PDF oder Bild zurück — meist binnen einer Sekunde nach Zahlungseingang, bereit als Anhang für die Bestätigungs-E-Mail.

Drei verschiedene Dinge heißen „Beleg-API". Manche Dienste lesen Belege und machen per OCR aus einem Foto strukturierte Daten. Manche Zahlungsanbieter liefern einen Beleg als Teil ihres eigenen Checkouts, in ihrem Layout. Diese API erstellt das Dokument aus Daten, die Sie schon haben, in Ihrem Design — für die Zahlungen, die Ihr Unternehmen annimmt.

Receipt Generation API: die wichtigsten Fakten
EndpunktPOST https://api.dynamicdocumentapi.com/v1/pdf/from-template oder /v1/images/from-template für einen PNG-Beleg
EingabeIhre Zahlungsdaten als JSON: Betrag, Währung, Zahlungsart, Posten, Steuer, Zeitstempel
PapierA4, Letter oder ein eigenes Format, 80 mm oder 58 mm breit für Rollendrucker; mit single_page folgt die Höhe dem Inhalt
FormatierungJede Währung und Sprache, formatiert mit Unicode-CLDR-Daten; Ihre Zeitzone über das Argument tz von format_date
CodesQR-Codes für einen Link zum erneuten Herunterladen oder eine Bewertungsseite, dazu 16 Barcode-Typen
DuplikateEin Idempotency-Key je Zahlungs-ID: Ein doppelt zugestellter Webhook erzeugt trotzdem nur einen Beleg (24 Stunden)
AuslieferungSignierte URL (standardmäßig 1 Stunde, bis zu 7 Tage), binär für E-Mail-Anhänge, base64, Ihr eigener Speicher (Bezahltarife) oder E-Mail über Ihren eigenen E-Mail-Anbieter (ab Growth)
RenderzeitMedian 216 ms, p95 516 ms1
PreisFree: 50 Renderings/Monat. Bezahlt ab 15 €/Monat (jährlich abgerechnet) für 3.000 Renderings, automatisches Nachladen ab 6 € je 1.000, etwa 0,005 € pro Beleg

1. Gemessen über 1.664 erfolgreiche Renderings auf Engine 2026.4. total_ms = Wartezeit in der Warteschlange plus Verarbeitung im Worker, ohne API-Overhead und Netzwerkübertragung. Belege sind kleine Dokumente und liegen am schnellen Ende dieses Bereichs. Zeiten je Dokument und die Methode: Renderzeit-Benchmark.

Beleg oder Rechnung — was brauchen Sie?

Beide Dokumente entstehen oft aus denselben Daten und werden genauso oft verwechselt. Der Unterschied ist die Richtung des Geldes.

  • Eine Rechnung fordert eine Zahlung. Sie trägt eine Rechnungsnummer, ein Fälligkeitsdatum, Zahlungsbedingungen und in den meisten Ländern eine Reihe gesetzlicher Pflichtangaben. Wenn Sie das brauchen, deckt die Invoice PDF API es ab, einschließlich mehrseitiger Posten und Steuerspalten.
  • Ein Beleg bestätigt eine Zahlung. Er nennt den tatsächlich gezahlten Betrag, die Zahlungsart, die letzten vier Ziffern der Karte, die Uhrzeit und die Transaktionsreferenz. Er ist kürzer, wird im Nachhinein ausgestellt und hat nie ein Fälligkeitsdatum.

Viele Unternehmen senden beides: eine Rechnung mit der Bestellung, einen Beleg bei Zahlungseingang. Eine Vorlagenbibliothek kann beide enthalten, jeweils mit demselben Kopf, Logo und derselben Fußzeile.

Einen Beleg aus einem Zahlungsereignis erzeugen

Auslöser ist ein Webhook Ihres Zahlungsanbieters — Stripe, Adyen, Mollie, PayPal oder Ihre eigene Kasse. Ihr Handler macht aus dem Ereignis Belegdaten und ruft die API mit der Zahlungs-ID als Idempotenzschlüssel auf.

curl https://api.dynamicdocumentapi.com/v1/pdf/from-template \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Idempotency-Key: pi_3Qk8sLd92" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_receipt_thermal",
    "data": {
      "receipt_no": "R-2026-18422",
      "paid_at": "2026-09-25T10:14:02Z",
      "method": "Visa •••• 4242",
      "locale": "en-US",
      "currency": "USD",
      "items": [
        { "name": "Flat white", "qty": 2, "total": 7.80 },
        { "name": "Croissant",  "qty": 1, "total": 3.68 }
      ],
      "subtotal": 11.48, "tax": 1.42, "total": 12.90,
      "reprint_url": "https://shop.example.com/r/R-2026-18422"
    },
    "pdf": {
      "paper": { "width": "80mm", "height": "200mm" },
      "single_page": true,
      "margin": { "top": "4mm", "right": "3mm", "bottom": "4mm", "left": "3mm" }
    },
    "delivery": "binary"
  }' \
  --output receipt.pdf
// Node.js 18+: called from your payment webhook handler
export async function receiptFor(payment) {
  const res = await fetch("https://api.dynamicdocumentapi.com/v1/pdf/from-template", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DYNAMIC_DOCUMENT_API_KEY}`,
      "Idempotency-Key": payment.id, // providers retry webhooks
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_id: "tpl_receipt",
      data: {
        receipt_no: payment.receiptNo,
        paid_at: payment.paidAt,
        method: `${payment.brand} •••• ${payment.last4}`,
        currency: payment.currency,
        items: payment.items,
        total: payment.total,
      },
      pdf: { paper: { size: "A4" } },
      delivery: "binary", // bytes for the email attachment
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return Buffer.from(await res.arrayBuffer());
}
import os
import requests

def receipt_pdf(payment: dict, thermal: bool = False) -> bytes:
    """Called from the payment webhook. Returns PDF bytes."""
    paper = {"width": "80mm", "height": "200mm"} if thermal else {"size": "A4"}
    res = requests.post(
        "https://api.dynamicdocumentapi.com/v1/pdf/from-template",
        headers={
            "Authorization": f"Bearer {os.environ['DYNAMIC_DOCUMENT_API_KEY']}",
            "Idempotency-Key": payment["id"],
        },
        json={
            "template_id": "tpl_receipt",
            "data": payment,
            "pdf": {"paper": paper, "single_page": thermal},
            "delivery": "binary",
        },
        timeout=30,
    )
    res.raise_for_status()
    return res.content
<?php
function receiptPdf(array $payment): string
{
    $ch = curl_init('https://api.dynamicdocumentapi.com/v1/pdf/from-template');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('DYNAMIC_DOCUMENT_API_KEY'),
            'Idempotency-Key: ' . $payment['id'],
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'template_id' => 'tpl_receipt',
            'data'        => $payment,
            'pdf'         => [
                'paper'       => ['width' => '58mm', 'height' => '200mm'], // narrow roll printer
                'single_page' => true,
            ],
            'delivery'    => 'binary',
        ]),
    ]);
    return curl_exec($ch); // PDF bytes
}

Zahlungsanbieter wiederholen Webhooks, dasselbe Ereignis kommt also oft zweimal an. Mit der Zahlungs-ID als Idempotency-Key liefert der zweite Aufruf 24 Stunden lang den bereits gerenderten Beleg zurück, statt einen weiteren zu erzeugen. Mit Testschlüsseln spielen Sie echte Ereignisse gegen eine Ausgabe mit Wasserzeichen nach, ohne Kontingent zu verbrauchen.

Thermorolle, A4 oder Bild — derselbe Beleg

Wo der Beleg landet, bestimmt seine Form. Ein Rollendrucker an der Kasse will einen schmalen, endlosen Streifen; ein Buchhaltungspostfach will A4 oder Letter; eine Bestätigungs-E-Mail wirkt oft besser, wenn der Beleg als Bild erscheint. Alle drei entstehen aus einer Vorlage.

Rollen mit 80 mm und 58 mm

Legen Sie Papierbreite und -höhe fest; ein eigenes Format braucht beide. Mit single_page ersetzt die Höhe des Inhalts die angegebene, und das PDF ist eine durchgehende Seite: Ein Verkauf mit zwei Posten druckt kurz, einer mit zwanzig lang — ohne leeren Rest und ohne abgeschnittene Summen.

"paper": { "width": "80mm", "height": "200mm" },
"single_page": true,
"margin": { "left": "3mm", "right": "3mm" }

A4 und Letter fürs Archiv

Dieselben Daten in einer breiteren Vorlage ergeben das Dokument, das die Buchhaltung erwartet: Ihr Adressblock, die Steuerübersicht, die Transaktionsreferenz. Dreizehn benannte Seitenformate stehen bereit, dazu jede eigene Größe bis 200 Zoll.

PNG für den E-Mail-Text

Manche Kunden öffnen nie Anhänge. Die Image Generation API rendert dieselbe Vorlage als PNG oder JPG, das Sie direkt in der E-Mail zeigen können, mit Viewport und Skalierung Ihrer Wahl.

Währung, Sprache und Zeitzone

Beträge, Dezimaltrennzeichen und Daten folgen den Unicode-CLDR-Regeln für die übergebene Sprache, und das Argument tz von format_date sorgt dafür, dass „10:14" die Ortszeit der Kundschaft meint und nicht UTC.

Erstattungen, Teilzahlungen und Spenden

Eine Vorlage kann jede Variante bedienen, die Ihr Checkout erzeugt, weil das Layout auf die Daten reagiert. Eine Bedingung entscheidet, ob ein Block überhaupt erscheint.

{% if refund %}
  <h1>Refund receipt</h1>
  <p class="ref">Refunds {{ original_no }}</p>
{% elif balance > 0 %}
  <h1>Partial payment</h1>
  <p class="bal">Remaining: {{ balance | format_currency(currency, locale) }}</p>
{% else %}
  <h1>Receipt</h1>
{% endif %}

Derselbe Mechanismus ergänzt eine Trinkgeldzeile für eine Kassenzahlung, einen Spenderblock und die Registernummer einer gemeinnützigen Organisation für eine Spendenquittung oder einen Hinweis, dass in Raten gezahlt wurde. Was jedes Dokument enthalten muss, entscheidet Ihre Steuerberatung; die Vorlage rendert es, und jede Version dieser Vorlage bleibt erhalten — Sie sehen also genau, was eine Kundin oder ein Kunde im letzten März bekommen hat.

Der Beleg bei der Kundschaft

  • E-Mail von Ihrer Domain. Ab Growth verschickt eine E-Mail-Regel in der Vorlage jeden Beleg über Ihr eigenes Konto bei Ihrem E-Mail-Anbieter, sobald er gerendert ist, mit der Datei als Anhang oder als Download-Link. So funktioniert der E-Mail-Versand.
  • Selbst anhängen. "delivery": "binary" liefert die Bytes, bereit für das Anhangsfeld Ihres E-Mail-Anbieters, wenn das System, das bereits Ihre Bestätigungen verschickt, auch den Beleg senden soll.
  • Download-Link. Die Standardantwort enthält eine signierte URL, eine Stunde gültig und mit expires_in bis zu sieben Tage — lang genug für einen Button „Beleg ansehen" in der Bestätigungs-E-Mail.
  • Kundenportal. Speichern Sie die Render-ID zur Zahlung und erzeugen Sie einen frischen Link, sobald die Kundschaft ihre Bestellhistorie öffnet.
  • Druck an der Kasse. Das Thermo-PDF geht aus Ihrer Kassensoftware direkt an einen Rollendrucker.
  • Aufbewahrung nach Ihren Vorgaben. Dateien bleiben so lange, wie Sie es mit retention_days festlegen, bis zum Maximum Ihres Tarifs, und lassen sich jederzeit löschen. Wie lange Sie den Beleg aufbewahren müssen, regelt das Steuerrecht — führen Sie Ihre eigene Archivkopie, etwa in Ihrem eigenen Storage-Bucket.

Was das Erzeugen eines Belegs kostet

Free

€0

50 Belege pro Monat — genug, um den Webhook anzubinden und beide Papierbreiten zu testen.

Starter

€15 / Monat

3.000 Renderings pro Monat, jährlich abgerechnet (19 € bei monatlicher Abrechnung). Etwa 0,005 € pro Beleg.

Checkouts mit hohem Volumen wachsen mit dem Growth-Tarif: 15.000 Renderings für 47 € bei jährlicher Abrechnung, etwa 0,0031 € pro Beleg, mit automatischem Nachladen, wenn ein Monat heiß läuft. Siehe die Kosten pro Beleg in jedem Tarif.

FAQ

Receipt Generation API: häufige Fragen

Was ist der Unterschied zwischen einem Beleg und einer Rechnung?

Eine Rechnung fordert Geld: Sie listet auf, was geschuldet wird, mit Fälligkeitsdatum und Zahlungsbedingungen. Ein Beleg bestätigt, dass Geld angekommen ist: Er nennt gezahlten Betrag, Zahlungsart und Datum. Viele Unternehmen senden beides — eine Rechnung bei der Bestellung, einen Beleg bei Zahlungseingang.

Kann ich Belege in Thermodrucker-Breite erzeugen?

Ja. Legen Sie ein eigenes Papierformat mit 80 mm oder 58 mm Breite fest und schalten Sie single_page ein — dann ersetzt die Höhe des Inhalts die angegebene Höhe, und der Beleg wird nicht in A4-Seiten geschnitten. Ein kurzer Beleg bleibt kurz und ein langer wird einfach länger, genau wie ein Rollendrucker es erwartet.

Können Belege nach einer Stripe-Zahlung automatisch versendet werden?

Ja, aus Ihrem eigenen Webhook-Handler. Meldet Ihr Zahlungsanbieter eine erfolgreiche Zahlung, macht Ihr Code aus dem Ereignis Belegdaten und ruft die API mit der Zahlungs-ID als Idempotenzschlüssel auf. Anbieter wiederholen Webhooks, und dieser Schlüssel sorgt dafür, dass ein doppeltes Ereignis keinen zweiten Beleg erzeugt. Mit einer E-Mail-Regel in der Vorlage (ab Growth) geht der Beleg danach ohne weiteren Aufruf über Ihren eigenen E-Mail-Anbieter hinaus.

Kann ich Spendenquittungen erstellen?

Ja. Eine Spendenquittung ist dieselbe Vorlage mit anderen Feldern: Spender, Betrag, Datum, die Registernummer Ihrer gemeinnützigen Organisation und jede Formulierung, die Ihre Steuerbehörde verlangt. Wie diese Formulierung lauten muss, klären Sie mit Ihrer Steuerberatung; die API rendert, was in Ihrer Vorlage steht.

Kann eine Vorlage Erstattungen und Teilzahlungen abdecken?

Ja. Vorlagen nutzen Bedingungen, dieselbe Datei kann also je nach gesendeten Daten einen Erstattungsbeleg mit negativer Summe drucken, „teilweise bezahlt" mit Restbetrag zeigen oder eine Trinkgeldzeile für eine Kassenzahlung ergänzen.

Liest die API Daten aus Fotos von Belegen?

Nein. Das ist Beleg-OCR und geht in die andere Richtung: ein Bild hinein, strukturierte Daten heraus. Diese API erstellt Belege aus Daten, die Sie bereits haben. Wenn Sie Daten aus gescannten Belegen auslesen müssen, ist ein OCR-Dienst das richtige Werkzeug.

Senden Sie Ihren ersten Beleg kostenlos

50 Renderings im Monat im Free-Tarif, ohne Kreditkarte, automatisches Nachladen in Bezahltarifen.

Kostenlos starten