Die PaperOffice API für Entwickler: der vollständige Leitfaden

Wo die Spezifikation zu finden ist

Die Endpunkt-Spezifikation wird live aus dem API-Katalog generiert. Nutzen Sie diese Dateien, anstatt Endpunkt-Listen aus Artikeln zu kopieren:

• Kompakter Index für KI-Clients: https://api.paperoffice.ai/latest/docs/llms.txt
• Vollständige Referenz: https://api.paperoffice.ai/latest/docs/llms-full.txt
• OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
• Agent-Skill: https://api.paperoffice.ai/latest/docs/skill.md
• Postman-Sammlung: https://api.paperoffice.ai/latest/docs/postman

Die Dokumentationsrouten sind öffentlich und benötigen kein Token. Importieren Sie die Postman-URL in Postman, VS Code oder Bruno und laden Sie sie erneut herunter, wenn sich die Dokumentationsversion ändert. Die Produktions-Basisadresse ist https://api.paperoffice.ai/latest; verwenden Sie /dev ausschließlich für die Entwicklung.

Ein Schnellstart mit einem KI-Coding-Assistenten: Geben Sie ihm die Adresse von llms-full.txt und beschreiben Sie die benötigte Funktion, beispielsweise eine Funktion, die ein Bild sendet und den erkannten Text zurückgibt.

Authentifizierung und Token-Typen

Die meisten Produkt-Endpunkte erfordern ein Bearer-Token im Authorization-Header. Sie erstellen Tokens in der PaperOffice App unter Konto → API.

• Systemschlüssel (po_sk_): Server-zu-Server-Integration mit vollem API-Zugriff. Verwenden Sie diesen niemals im Browser.
• Benutzertoken (po_ut_): Der Geltungsbereich eines einzelnen Benutzers, beispielsweise für MCP. Die Rechte richten sich nach dem Benutzer und der Lizenz.
• Gruppentoken (po_gt_): Erbt die Rechte und die Whitelist der Workspaces einer Benutzergruppe.
• Veröffentlichbarer Schlüssel (po_pk_): Für die Verwendung in einem Browser. Jede Anfrage benötigt eine Herkunft, die der Schlüsselinhaber eingetragen hat, ein Lebenszeitbudget begrenzt den Verbrauch, und das Löschen, die Kontoverwaltung, das Schlüsselmanagement und Zahlungsänderungen bleiben gesperrt. Er ist nicht für MCP zugelassen.

Ohne Token sind nur Infrastruktur-Endpunkte wie die Spezifikation, der Health-Check und der Konnektivitätstest erreichbar. Eine Produktanfrage ohne Token wird mit HTTP 403 und dem Code TIER_RESTRICTED beantwortet, nicht mit HTTP 401.

Jobs: Warten, Polling und Ergebnisse

Die Verarbeitung läuft als Jobs ab. Job-Pfade verwenden das Muster handler___command mit drei Unterstrichen, beispielsweise POST /job/add/paperoffice_aiocr___generate für die Texterkennung. Die Punkt-Notation wird mit JOB_CONFIG_INVALID abgelehnt.

• Standardmäßig hält die Anfrage die Verbindung für eine Weile aufrecht. Wenn der Job rechtzeitig abgeschlossen wird, erhalten Sie das Ergebnis direkt. Andernfalls erhalten Sie HTTP 202 mit einer Job-ID und einer Poll-Adresse, und der Job läuft weiter.
• HTTP 202 ist ein Erfolg, kein Fehler. Pollen Sie GET /job/get/{job_id} alle 5 bis 10 Sekunden, bis der Status abgeschlossen ist. Das Ergebnis befindet sich dann in job_result.
• Mit client_wait=false erhalten Sie die Job-ID sofort und starten das Polling von Anfang an.
• Alle Antworten sind JSON. Clients sollten das stabile code-Feld lesen, nicht den lokalisierten Nachrichtentext.

Sie sehen wartende, laufende und abgeschlossene API-Jobs in der App unter Konto → API → Job-Warteschlange. Die vollständige Liste der Fehlercodes befindet sich in der Spezifikation; typische Fälle sind fehlende oder ungültige Parameter (400), ein fehlendes oder ungültiges Token (401), nicht genug Credits (402), eine verbotene Aktion (403) und zu viele Anfragen (429, beachten Sie Retry-After).

Start-SLA: Wann ein Job startet

Das optionale Feld processing_lane steuert, wann ein Job in der Warteschlange startet, nicht wann er endet. client_wait steuert, ob die Verbindung auf das Ergebnis wartet; die beiden Felder sind unabhängig voneinander.

Ohne processing_lane gilt der Standard des Workspaces, sonst best effort. Jeder Tarif enthält best effort ohne Zuschlag. Schnellere Start-Lanes sind optional und kosten mehr. Die aktuellen Lanes und ihre Preise sind live über die API-Preisliste verfügbar; Details finden Sie in der API-Dokumentation.

Webhooks

Webhook-Endpunkte empfangen Job- und Kontoevents, beispielsweise job.completed, job.failed, job.progress sowie Events für Dokumente, Workspaces und Aufgaben. Kontohinweise wie ein leeres Kontoguthaben oder ein widerrufener Schlüssel sind keine Webhook-Events.

• Payloads werden mit HMAC-SHA256 im Header X-Paperoffice-Signature signiert. Berechnen Sie die Signatur über den rohen Anfragekörper mit Ihrem Webhook-Geheimnis und lehnen Sie die Anfrage ab, wenn sie nicht übereinstimmt.
• Webhooks werden über die API registriert, aufgelistet, aktualisiert, getestet und gelöscht.

Abrechnung und Nutzung

API-Aufrufe verbrauchen Credits aus dem gemeinsamen Pool der Organisation, demselben Pool wie die App. Einige Status- und Health-Abfragen werden nicht berechnet; Details finden Sie in der API-Dokumentation. Aufrufe, die aufgrund ungültiger Eingaben abgelehnt werden, werden ebenfalls berechnet; durch Rate-Limits begrenzte Aufrufe nicht.

Die Aufrufe mit ihren Credits sehen Sie unter API & Entwickler → API-Nutzung: Das Live-Protokoll zeigt jede Anfrage, der Verlauf zeigt die Nutzung nach Datum, Handler und Aktion. Wenn die Credits aufgebraucht sind, werden Aufrufe abgelehnt, bis das Guthaben aufgeladen ist oder die automatische Aufladung greift. Die Ratenlimits hängen von Ihrem Plan ab; die aktuellen Limits und die Antwort-Header beschreibt die API-Dokumentation. Mehr zu Credits: Abrechnung und Credits in PaperOffice AI.

MCP: KI-Assistenten verbinden

MCP verbindet KI-Assistenten wie Claude, ChatGPT, Grok und Cursor direkt mit PaperOffice. Die Authentifizierung erfolgt über OAuth 2.1 oder ein Benutzer- oder Gruppentoken; Systemschlüssel und veröffentlichbare Schlüssel sind für MCP gesperrt. Der Produktions-Host ist https://mcp.paperoffice.ai, mit Profilen wie /claude, /chatgpt, /grok, /cursor und /dms. Einrichtung, Berechtigungen und Datenfluss: PaperOffice mit Claude, ChatGPT, Grok und Cursor nutzen.

Häufig gestellte Fragen

• Wo finde ich alle Endpunkte? In llms.txt, llms-full.txt und der OpenAPI-Datei. Sie werden live generiert.
• Welches Token sollte mein Server verwenden? Ein Systemschlüssel, niemals in einem Browser. Für einen Browser verwenden Sie einen veröffentlichbaren Schlüssel mit einer Herkunft (Origin) und einem Budget.
• Ist HTTP 202 ein Fehler? Nein. Der Job läuft noch; pollen Sie nach dem Ergebnis.
• Kosten schnellere Start-Lanes mehr? Ja. Best Effort hat keinen Zuschlag; die aktuellen Preise finden Sie in der API-Preisliste.
• Werden abgelehnte Aufrufe berechnet? Aufrufe, die aufgrund ungültiger Eingaben abgelehnt werden, werden berechnet; durch Rate-Limits begrenzte Aufrufe nicht.