PDFs aus einer CSV erzeugen mit Java

Was Sie brauchen

• Einen API-Key. Legen Sie ihn in der App unter API-Schlüssel an und exportieren Sie ihn als FORMFEED_API_KEY. Zum Ausprobieren ist ein Test-Key (ff_test_…) richtig. Siehe Quickstart.
• Java. Sie brauchen Java 17 oder neuer; java.net.http.HttpClient und Textblöcke gehören zum JDK.
• Die Vorlage. certificate aus dem Zertifikats-Beispiel, deren Felder genau die Spalten der CSV sind.
• Die CSV. attendees.csv neben dem Programm, mit Kopfzeile. Sie steht weiter unten.
• Genug Einheiten. Batches gehören zu jedem Tarif, und jeder Eintrag zählt mindestens als eine Einheit. Im Free-Tarif wird ein Live-Batch abgelehnt, wenn im Monat weniger Einheiten übrig sind, als der Batch Einträge hat; ein Test-Schlüssel wird nicht gezählt. Die Limits-Seite nennt die Einheiten je Tarif.

Das Programm

Das Programm liest die CSV, macht aus jeder Zeile einen Eintrag, reiht sie mit zip: true als einen Job ein, wartet, bis der Job fertig ist, und speichert das Archiv.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Batch {
  static final String BASE = "https://api-eu.formfeed.dev/v1";
  static final HttpClient CLIENT = HttpClient.newHttpClient();

  static String api(String method, String path, String body) throws Exception {
    HttpRequest.BodyPublisher publisher =
        body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body);
    HttpRequest request = HttpRequest.newBuilder(URI.create(BASE + path))
        .header("Authorization", "Bearer " + System.getenv("FORMFEED_API_KEY"))
        .header("Content-Type", "application/json")
        .method(method, publisher)
        .build();
    HttpResponse<String> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      System.err.println(response.body());
      System.exit(1);
    }
    return response.body();
  }

  /** The value of a top-level JSON field; a project would use Jackson or Gson instead. */
  static String field(String json, String name) {
    Matcher m = Pattern.compile("\"" + name + "\"\\s*:\\s*(?:\"([^\"]*)\"|([^,}\\s]+))").matcher(json);
    return m.find() ? (m.group(1) != null ? m.group(1) : m.group(2)) : "";
  }

  public static void main(String[] args) throws Exception {
    // the JDK has no CSV reader; this file has no quoted fields, so a split does. Otherwise: Commons CSV.
    List<String> lines = Files.readAllLines(Path.of("attendees.csv"));
    List<String> items = new ArrayList<>();
    for (String line : lines.subList(1, lines.size())) {
      String[] v = line.split(",");
      // every field of a CSV is text: the template expects hours as a number
      items.add("""
          {"data": {"name": "%s", "course": "%s", "completed_on": "%s", "hours": %d}}
          """.formatted(v[0], v[1], v[2], Integer.parseInt(v[3])).strip());
    }

    String queued = api("POST", "/renders/batch",
        "{\"template\": \"certificate\", \"zip\": true, \"items\": [" + String.join(",", items) + "]}");
    String id = field(queued, "id");
    System.out.println(id + " " + field(queued, "total") + " queued");

    // the job is always asynchronous: ask for it until it is no longer queued or processing
    String job = queued;
    while (field(job, "status").equals("queued") || field(job, "status").equals("processing")) {
      Thread.sleep(2000);
      job = api("GET", "/jobs/" + id, null);
    }
    System.out.println(field(job, "succeeded") + "/" + field(job, "total") + " rendered, " + field(job, "failed") + " failed");

    String zip = field(job, "zip_url");
    if (!zip.isEmpty() && !zip.equals("null")) {
      CLIENT.send(HttpRequest.newBuilder(URI.create(zip)).build(),
          HttpResponse.BodyHandlers.ofFile(Path.of("certificates.zip")));
    }
  }
}

Ausführen

Es gibt die Job-ID und die Zahl der eingereihten Renderings aus, dann 4/4 rendered, 0 failed, und certificates.zip liegt neben dem Programm, mit einem PDF je Zeile, 0001-document.pdf bis 0004-document.pdf.

export FORMFEED_API_KEY=ff_test_...
java Batch.java

Was an Java besonders ist

• Keine JSON-Bibliothek im JDK. Um ohne Abhängigkeiten auszukommen, ist der Body ein Textblock, und die Werte, die das Programm aus JSON braucht (id und download_url des Renderings, eine Rechnungsnummer), liest ein regulärer Ausdruck. In einem Projekt bauen Sie den Body und lesen die Antwort mit Jackson oder Gson.
• Start aus einer Datei. java Render.java kompiliert und startet in einem Schritt; zum Ausprobieren braucht es kein Build-Tool.
• Direkt auf die Platte. BodyHandlers.ofFile streamt das PDF in die Datei, ohne es im Speicher zu halten.

Die CSV

Eine Kopfzeile, eine Zeile je Dokument. Die Spalten sind die Felder, die die Vorlage erwartet, eine Zuordnungstabelle braucht es also nicht:

name,course,completed_on,hours
Erika Mustermann,Analytical Engines 101,2026-09-10,16
Max Mustermann,Analytical Engines 101,2026-09-10,16
Jane Doe,Print CSS for developers,2026-09-11,8
John Doe,Print CSS for developers,2026-09-11,8

Was ein Batch anders macht

• Immer asynchron. Die Antwort kommt sofort mit dem Status queued. Die Renderings laufen im Hintergrund, so viele gleichzeitig, wie Ihr Tarif erlaubt.
• Eine Vorlage, viele Einträge. Ein template auf oberster Ebene gilt für jeden Eintrag, der keine eigene nennt; ein Eintrag besteht deshalb meist nur aus seinen data.
• Teilweise gescheitert ist ein Zustand. Ein Job, in dem einige Einträge gescheitert sind, endet als partially_failed (failed, wenn alle gescheitert sind). succeeded und failed zählen sie, und jeder Eintrag ist in items ein eigenes Rendering mit eigenem Fehler.
• Das Zip ist optional. Jeder Eintrag behält in items seine eigene Download-URL, und das wollen Sie, wenn die Dokumente an verschiedene Personen gehen. zip: true legt die geglückten zusätzlich in ein Archiv, jedes benannt mit 0001- und dem filename seines Eintrags (document.pdf ohne einen), in der Reihenfolge der Zeilen.
• Oder ein Webhook. Statt zu warten, geben Sie dem Batch eine webhook_url und lassen sich von job.completed benachrichtigen (oder von job.failed, wenn alle Einträge gescheitert sind). Für tausende Dokumente ist das die bessere Form: kein Prozess, der minutenlang wartet.

Wenn die API nein sagt

• Eine Form für jeden Fehler. Fehler sind Problem-Dokumente (RFC 9457) mit type, title, status, detail, einem stabilen code und der request_id, die Sie dem Support nennen; die type-URL führt zu einer Seite über diesen Fehler. Die Liste steht in der Fehlerreferenz.
• Die üblichen. 401 unauthorized bei fehlendem oder widerrufenem Schlüssel, 404 template_not_found bei falschem Vorlagennamen, 422 template_runtime_error, wenn die Vorlage an den Daten scheitert, 429 rate_limited über den Anfragen pro Sekunde des Tarifs, 402 quota_exceeded, wenn die Einheiten des Free-Tarifs verbraucht sind (ein bezahlter Tarif rechnet weitere Einheiten ab, bis zu seiner Obergrenze).
• Sicher wiederholen. Senden Sie beim POST einen Idempotency-Key-Header und wiederholen Sie die Anfrage mit demselben Schlüssel, wenn Sie nicht wissen, ob der erste Versuch ankam: 24 Stunden lang liefert der Schlüssel die erste Antwort, statt erneut zu rendern und zu berechnen. Gespeichert wird die Antwort, sobald der erste Versuch beantwortet ist; wiederholen Sie also nicht, solange er noch laufen kann. Auch Probleme unter 500 werden gespeichert, eine korrigierte Anfrage braucht deshalb einen neuen Schlüssel.

Die Aufgabe um dieses Programm

Dieser Guide ist ein Programm. Was die Aufgabe darum herum braucht, von der Vorlage bis zu Limits und Preis, steht auf der Seite Zertifikate per API erzeugen.

Weitere Guides für Java

• PDF-Rechnung aus JSON erzeugen mit Java
• ZUGFeRD-E-Rechnung erstellen mit Java
• HTML in PDF umwandeln mit Java
• Open-Graph-Bilder erzeugen mit Java
• PDFs zusammenfügen und mit Passwort schützen mit Java
• PDF asynchron rendern und den Webhook prüfen mit Java

FAQ

Wie viele Zeilen darf ein Job haben?

Bis zu 1.000 Einträge je Batch. Teilen Sie eine längere Liste auf mehrere Jobs auf; wie viele Jobs Sie starten, ist nicht begrenzt, und jeder zählt einmal gegen das Rate Limit. Siehe Async und Batch.

Was passiert, wenn eine Zeile falsch ist?

Scheitert die Vorlage an den Daten einer Zeile, scheitert dieser Eintrag, und die anderen rendern trotzdem: Der Job endet als partially_failed, und der gescheiterte Eintrag trägt den Fehler; Sie können die Zeile korrigieren und einzeln erneut rendern. Ein Eintrag, den die API von vornherein ablehnt (ein Feld der Anfrage, das sie nicht annimmt, oder Daten, die mit validate_data nicht zum Schema der Vorlage passen), lässt den ganzen Batch scheitern, bevor etwas eingereiht wird, und das Problem nennt seine Position.

Kostet ein gescheiterter Eintrag Einheiten?

Nein. Gezählt wird nur, was entstanden ist.

Geht das auch ohne Code, mit einer Tabelle?

Ja: Die App nimmt eine CSV- oder Excel-Datei, ordnet die Spalten den Feldern der Vorlage zu und führt den Batch aus. Der Code hier ist dasselbe innerhalb Ihres eigenen Systems.

Batch aus einer CSV in anderen Sprachen

• Node.js (TypeScript)
• Python
• PHP
• Go
• C# (.NET)
• Ruby
• curl