API für PDF-Barrierefreiheit: PDFs automatisiert prüfen und taggen

Wofür eine PDF/UA-API?

Barrierefreiheit scheitert selten am Wissen, sondern an der Menge. Rechnungen, Bescheide, Berichte und Formulare entstehen automatisiert, oft aus Systemen, die kein getaggtes PDF erzeugen. Eine Prüf- und Tagging-Schnittstelle erlaubt es, jedes Dokument im Prozess zu kontrollieren, bevor es an Kundinnen, Kunden oder Bürgerinnen und Bürger geht.

Typische Einsatzszenarien:

• Dokumentenmanagement: Neue Dokumente beim Import prüfen und Befunde als Metadaten speichern.
• Rechnungs- und Bescheidversand: Generierte PDFs vor dem Versand prüfen und Basis-Tags ergänzen.
• CMS-Upload-Prüfung: Redaktionen erhalten beim Hochladen sofort eine Rückmeldung, ob Titel, Sprache oder Tags fehlen.
• Batch-Migration: Bestehende Dokumentarchive systematisch untersuchen und priorisieren, welche Dateien nachgearbeitet werden müssen.

Die Endpunkte im Überblick

Die REST-API umfasst drei Endpunkte. Alle verlangen einen persönlichen Bearer-Token im Authorization-Header.

• POST /api/v1/inspect/: prüft ein PDF, das als Multipart-Feld pdf übertragen wird. Das Dokument wird nicht verändert.
• POST /api/v1/tag/: erzeugt eine nachträglich getaggte Kopie. Neben pdf werden title und language (BCP-47-Code, z. B. de-AT) übergeben.
• GET /api/v1/download/?token=…: lädt das Tagging-Ergebnis herunter, mit demselben Bearer-Header.

Beispiel: PDF prüfen

curl -X POST https://easypdfua.com/api/v1/inspect/ \
  -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -F "pdf=@bericht.pdf"

Die JSON-Antwort besteht aus drei Teilen: status (Erfolg, Operation, API-Version, Zeitpunkt), result mit der Bewertung (pdfUaOk, verdict, warningCount) und details mit dem vollständigen Prüfbericht inklusive Strukturbaum und Warnungen.

Beispiel: PDF taggen und herunterladen

curl -X POST https://easypdfua.com/api/v1/tag/ \
  -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -F "pdf=@bericht.pdf" \
  -F "title=Jahresbericht 2026" \
  -F "language=de-AT"

# Antwort (gekürzt)
{
  "status": { "success": true, "operation": "tag", ... },
  "result": {
    "verdict": "issues_found",
    "outcome": "tagged",
    "output": {
      "downloadUrl": "https://easypdfua.com/api/v1/download/?token=…",
      "sha256": "…",
      "expiresInSeconds": 900,
      "singleUse": true
    }
  },
  "details": { ... }
}

curl -H "Authorization: Bearer $EASYPDFUA_TOKEN" \
  -o bericht-getaggt.pdf "<downloadUrl>"

Die Download-URL ist 15 Minuten gültig und kann genau einmal abgerufen werden. Ist ein PDF bereits getaggt, wird es nur analysiert (outcome: already-tagged-analyzed) und es entsteht keine neue Datei. Mit dem mitgelieferten SHA-256-Hash können Sie die Integrität des Downloads prüfen.

Sicherheit und Datenschutz

• Der Token wird nur einmal vollständig angezeigt. Gespeichert wird ausschließlich ein SHA-256-Hash.
• PDF-Inhalte werden nicht an externe Dienste übertragen und nicht in Protokollen gespeichert.
• Es gelten dieselben konservativen Sicherheitsregeln wie im Browser: Verschlüsselte, signierte oder technisch uneindeutige PDFs werden abgelehnt, statt riskant verändert zu werden.
• Fehler werden als JSON mit error.code und passendem HTTP-Status gemeldet, etwa 401 bei ungültigem Token oder 413 bei zu großen Dateien.

Was das Tagging leistet und was nicht

Das automatische Tagging ist bewusst konservativ. Es ergänzt einen Strukturbaum mit Document-Element und einem Absatz (P) pro Seite, verankert Links als Link-Tags, setzt Titel, Dokumentsprache, PDF/UA-Kennung in den XMP-Metadaten und die Tab-Reihenfolge und repariert, wo eindeutig möglich, fehlende Unicode-Zuordnungen (ToUnicode).

Semantische Strukturen wie Überschriften, Tabellen, Listen und Alternativtexte für Bilder erzeugt die API nicht. Dafür braucht es inhaltliches Verständnis und in der Regel eine manuelle Bearbeitung. Mehr dazu im Ratgeber PDF nachträglich taggen.

Für automatisierte Qualitätssicherung empfehlen wir, Ergebnisse zusätzlich mit veraPDF zu validieren. Der quelloffene Validator lässt sich gut in CI-Pipelines und Batch-Prozesse einbinden. Welche Meldungen dabei typisch sind, erklärt der Ratgeber Häufige PAC- und veraPDF-Fehler.

Zugang zur API

Die API ist Teil des Premium-Tarifs: Dateien bis 50 MB, unbegrenzte Vorgänge und ein persönlicher Token, den Sie im Anwendungsbereich unter „API-Zugriff“ erstellen. Premium ansehen.

Häufige Fragen

Wer kann die API nutzen?

Die API steht ausschließlich Premium-Konten zur Verfügung. Free-Konten sehen den API-Bereich, können aber keinen Token erzeugen.

Wie groß dürfen PDFs sein?

Über die API können Premium-Konten PDFs bis 50 MB pro Datei verarbeiten, ohne Tageslimit für Vorgänge.

Wie lange ist das getaggte PDF abrufbar?

Die Download-URL ist 15 Minuten gültig und nur einmal abrufbar. Danach wird die Datei gelöscht.

Ist das API-Ergebnis eine PDF/UA-Zertifizierung?

Nein. Die Bewertung basiert auf den internen EasyPDFUA-Prüfungen und ist keine normative PDF/UA-Validierung. Eine Gegenprüfung mit veraPDF oder PAC und eine manuelle Prüfung bleiben empfohlen.