API-Dokumentation

anonymous

REST API

Automatisiere die Dokumentenverarbeitung — z. B. aus n8n, Make, Zapier oder eigenen Skripten. Alle Endpunkte nutzen API-Key-Authentifizierung über den HTTP-Header X-API-Key.

Basis-URL

http://app4.phil27.de/sitemap.xml

API-Keys können von einem Admin unter Einstellungen → API-Keys erstellt werden.

Authentifizierung

Übergib den API-Key in einem der folgenden HTTP-Header:

MethodeBeispielEmpfohlen
X-API-Key Header X-API-Key: tpw_abc123… ✓
Authorization Bearer Authorization: Bearer tpw_abc123…
Query-Parameter ?…&api_key=tpw_abc123… Download

POST Dokument verarbeiten

http://app4.phil27.de/sitemap.xml?page=api-process

Request

Content-Type: multipart/form-data

ParameterTypPflichtBeschreibung
fileFile✓ Die zu verarbeitende Datei
operationString✓ Verarbeitungsmodus (siehe Tabelle unten)
languageString OCR-Sprache, Standard: deu+eng

Response (Erfolg)

{
  "success":         true,
  "filename":        "Rechnung_ocr_1718123456.pdf",
  "download_url":    "?page=api-download&file=Rechnung_ocr_1718123456.pdf&api_key=tpw_…",
  "processing_time": 8.34,
  "operation":       "ocr"
}

Response (Fehler)

{
  "success": false,
  "error":   "Fehlermeldung"
}

Beispiel — cURL

curl -X POST \
  -H "X-API-Key: tpw_IHR_KEY_HIER" \
  -F "file=@/pfad/zum/dokument.pdf" \
  -F "operation=ocr" \
  -F "language=deu+eng" \
  "http://app4.phil27.de/sitemap.xml?page=api-process"

Beispiel — PHP

$ch = curl_init('http://app4.phil27.de/sitemap.xml?page=api-process');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: tpw_IHR_KEY_HIER'],
    CURLOPT_POSTFIELDS     => [
        'file'      => new CURLFile('/pfad/dokument.pdf', 'application/pdf', 'dokument.pdf'),
        'operation' => 'ocr',
        'language'  => 'deu+eng',
    ],
    CURLOPT_TIMEOUT => 300,
]);
$json   = json_decode(curl_exec($ch), true);
$dlUrl  = $json['download_url'] ?? null;

Beispiel — Python

import requests

resp = requests.post(
    "http://app4.phil27.de/sitemap.xml?page=api-process",
    headers={"X-API-Key": "tpw_IHR_KEY_HIER"},
    files={"file": open("dokument.pdf", "rb")},
    data={"operation": "ocr", "language": "deu+eng"},
    timeout=300,
)
data = resp.json()
print(data["download_url"])

GET Ergebnisdatei herunterladen

http://app4.phil27.de/sitemap.xml?page=api-download&file={filename}&api_key={key}

Gibt die fertige Datei direkt als Binary-Stream zurück. Der API-Key kann hier als Query-Parameter übergeben werden, damit der download_url aus der Process-Response direkt verwendbar ist.

ParameterQuelleBeschreibung
fileQueryDateiname aus der Process-Response
api_keyQuery oder HeaderDein API-Key

Beispiel — cURL

curl -H "X-API-Key: tpw_IHR_KEY_HIER" \
  "http://app4.phil27.de/sitemap.xml?page=api-download&file=Rechnung_ocr_1718123456.pdf" \
  -o ergebnis.pdf

Verfügbare Operationen

operation Funktion Akzeptierte Dateiformate Ausgabe
ocr PDF → PDF (OCR) PDF PDF
to-docx PDF → DOCX PDF DOCX
to-xlsx PDF → XLSX PDF XLSX
to-pdfa PDF → PDF/A PDF PDF
docx-ocr DOCX → PDF (OCR) DOCX / DOC DOCX
xlsx-ocr XLSX → PDF (OCR) XLSX / XLS XLSX
image-ocr Bild → PDF (OCR) JPG, PNG, TIFF, BMP … PDF

OCR-Sprachen (language)

Sprachen können mit + kombiniert werden (z. B. deu+eng).

deu+eng deu eng fra+deu fra ita spa … weitere je nach installierten Tesseract-Language-Packs

n8n-Integration

Mit zwei HTTP-Request-Nodes lässt sich die komplette Verarbeitungskette in n8n abbilden:

1
HTTP Request — Dokument hochladen & verarbeiten
  • Methode: POST
  • URL: http://app4.phil27.de/sitemap.xml?page=api-process
  • Authentication: Generic Credential Type → Custom Header Auth
  • Header Name: X-API-Key, Value: Dein Key
  • Body Content Type: Form-Data (Multipart)
  • Parameter: file → Binär-Datei aus vorangehendem Node
  • Parameter: operation → z. B. ocr
  • Parameter: language → z. B. deu+eng
  • Timeout: mind. 300 s

Antwort enthält download_url, z. B.:
?page=api-download&file=Rechnung_ocr_1718123456.pdf&api_key=tpw_…

↓
2
HTTP Request — Ergebnisdatei herunterladen
  • Methode: GET
  • URL: http://app4.phil27.de/sitemap.xml{{ $json.download_url }}
  • Response Format: File

Da download_url den api_key bereits enthält, ist kein zusätzlicher Header nötig.

Da OCR von großen PDFs mehrere Minuten dauern kann, unbedingt den Timeout im HTTP-Request-Node auf mindestens 300 Sekunden setzen.

HTTP-Statuscodes

CodeBedeutung
200Erfolgreich
400Ungültige Anfrage (fehlende Parameter)
401API-Key fehlt oder ungültig
404Datei nicht gefunden
500Interner Serverfehler
503Dienst nicht verfügbar (DB-Verbindung fehlt)