Ihre Dokumente.
Ihr Weg, sie zu versenden.

01 / DER ABLAUF

Vorbereiten. Prüfen. Bestätigen.

Hochladen und Vorbereitung lösen keine Kommunikation aus. Erstellen Sie nach dem Start der Beta zunächst Ihren Guteneo-Bereich im Browser und bestätigen Sie Ihre E-Mail-Adresse. Verbinden Sie anschließend einen registrierten OAuth-Client mit den erforderlichen Berechtigungen.

1. Laden Sie das PDF hoch. Übermitteln Sie die Originaldatei im Feld file. Warten Sie auf den Status ready : Eine 201-Antwort kann noch ein Dokument in Quarantäne bezeichnen.
2. Bereiten Sie die Sendung vor. Wählen Sie Dokument und Empfänger. Bewahren Sie die Antwort, ihre id, ihren Fingerabdruck und die zurückgegebenen Beträge auf. Eine etwaige Kostenobergrenze wird in EUR-Cent angegeben.
3. Standardfreigabe. Leiten Sie die Person weiter zu https://guteneo.com/#/app/dispatch/{id}. Sie prüft PDF, Empfänger, Optionen und Kosten und gibt die Sendung in ihrer Guteneo-Sitzung frei. Der optionale Expertenmodus folgt einem begrenzten Mandat, das zuvor unter Mein Konto für den betreffenden Assistenten aktiviert wurde.
4. Bestätigen und nachverfolgen. Der Client kann anschließend Folgendes aufrufen: POST /api/dispatches/{id}/confirm, mit einem eigenen Idempotenzschlüssel für diese Bestätigung. Lesen Sie anschließend den Versandstatus erneut.

curl 'https://guteneo.com/api/documents' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN" \
  --form 'file=@./document.pdf;type=application/pdf'

curl 'https://guteneo.com/api/dispatches' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ma-preparation-unique-001' \
  --data '{
    "channel": "fax",
    "documentId": "doc_identifiant_recu",
    "recipient": { "phone": "+33199001234" }
  }'

Diese Beispiele sind Anfragevorlagen, keine bereitgestellten Zugangsdaten. Die Umgebungsvariable enthält ein von Ihrem OAuth-Client erhaltenes Zugriffstoken. Speichern Sie es niemals in einer URL oder einem Code-Repository. Kein Beispiel wird von dieser Seite aus ausgeführt.

Das REST-Ergebnis ist die unverarbeitete Sendung. Das Feld approvalUrl gehört zur MCP-Antwort. Erstellen Sie bei REST den Browserlink mit der zurückgegebenen Kennung. Ein Ja in einer Unterhaltung und eine Werkzeugberechtigung erzeugen weder eine menschliche Freigabe noch ein Expertenmandat. Der Expertenablauf über MCP verwendet eine aktuelle Prüfung und anschließend eine delegierte Freigabe; er hält die Mandatsgrenzen und die Bestätigungen Ihres Assistenten ein.

Lesen Sie für Briefpost zuerst die Vorlage mit GET /api/postal/requirements?country=LU, mit Angabe des Empfängerlandes. Verwenden Sie nach dem Erstellen und Importieren der PDF-Datei POST /api/postal/preflights : Guteneo prüft genau diese PDF-Datei und gibt Folgendes zurück: reviewUrl. Im Standardmodus öffnet die Person diesen Link, prüft die Seiten und genehmigt die Übertragung an den Druckanbieter. Der Expertenmodus erfordert ein Postmandat, das diese Datenübertragung gesondert abdeckt; er löst keinen Versand aus. Fordern Sie nach der Entwurfsanalyse Folgendes an: POST /api/postal/preflights/{id}/quote, und lassen Sie anschließend das Angebot freigeben. Diese Schritte bleiben vom Versand getrennt. Eine ungewisse Übertragung darf niemals automatisch wiederholt werden.

02 / AUTHENTIFIZIERUNG

Gezielte Berechtigungen.

Clients verwenden Authorization Code mit PKCE S256, eine exakt registrierte Rückleitungs-URI und einen geprüften Parameter state . Die Audience ist https://guteneo.com/mcp, auch für die dokumentierten REST-Routen. Es gibt weder einen persönlichen API-Schlüssel noch ein Passwort, das an einen Assistenten weiterzugeben wäre.

Autorisierung

https://pieper.eu.auth0.com/authorize

Code-Austausch

https://pieper.eu.auth0.com/oauth/token

HTTP-Token

Authorization: Bearer <access_token>

Verwenden Sie ein Zugriffstoken, niemals ein ID-Token. Ein öffentlicher Client enthält kein Client-Geheimnis. Die Organisation wird durch Mitgliedschaft und autorisierte Verbindung bestimmt. Kein Parameter erlaubt die freie Wahl eines anderen Bereichs. Bei mehreren Bereichen erfolgt die Zuordnung über die Verbindungen im Dashboard. Die Leserrolle verbietet Schreibzugriffe, auch mit einem Scope. Während der Beta ist für alle Rollen ein verifiziertes Konto erforderlich; Zwei-Faktor-Authentifizierung ist nicht verpflichtend.

Kein Scope erlaubt eine menschliche Freigabe. Die Freigaberoute im Browser, Verwaltung und Abrechnung gehören nicht zu dieser Entwickler-API. OAuth-Berechtigungen ersetzen keine Prüfungen von Rolle, Absender, Guthaben oder Kanal.

Für Assistenten ist MCP Streamable HTTP als Transport vorgesehen unter https://guteneo.com/mcp. Integrationsdateien sind verfügbar in den Installationsanleitungen. Jeder Client muss weiterhin registriert und in seiner tatsächlichen Umgebung getestet werden.

03 / DOKUMENTE

Ein Original bleibt ein Original.

POST /api/documents bewahrt die hochgeladenen Bytes. Das PDF ist privat, durch seinen SHA-256 identifiziert und wird in einer isolierten Umgebung analysiert und geprüft. GET /api/documents/{id}/content liefert nur ein bereites Dokument mit dem Header X-Document-SHA256 und ohne öffentlichen Cache.

POST /api/documents/render erstellt ein neues A4-PDF aus bereinigtem HTML. Skripte, mitgelieferte Stile und externe Ressourcen werden entfernt. Dieses Rendering darf nicht verwendet werden, um ein Original aus seinem Text nachzubauen. Der URL-Import ist dem MCP-Werkzeug vorbehalten: import_document, auf jeder öffentlichen HTTPS-Domain, ohne Weiterleitung. Es ist keine REST-Route.

Das Feld analysis zeigt an, ob die Prüfung läuft, abgeschlossen ist, wiederholt werden muss oder blockiert ist, mit einer Erklärung und einer nächsten Aktion. Fragen Sie während einer laufenden Prüfung Folgendes ab: GET /api/documents/{id} höchstens alle 15 Sekunden. Der Server übernimmt begrenzte automatische Wiederholungen. Bieten Sie einen ausdrücklichen Neustart an über POST /api/documents/{id}/rescan nur wenn die zurückgegebene Aktion lautet rescan. Behalten Sie dasselbe Dokument. Ein erneutes Hochladen ist nicht erforderlich.

04 / ZUVERLÄSSIGKEIT

Eine Anfrage, eine Sendung.

Der Header Idempotency-Key ist für Vorbereitung und Bestätigung erforderlich: 1 bis 200 Zeichen, ohne Zeilenumbruch oder NUL-Zeichen. Verwenden Sie einen festen Schlüssel je logischem Vorgang und einen anderen Schlüssel für die Bestätigung. Die Wiederverwendung eines Schlüssels mit anderem Inhalt führt zu IDEMPOTENCY_CONFLICT.

Der Fingerabdruck fingerprint bindet die freigegebenen Inhalte, Empfänger, Dokumente, Optionen und Kosten. Die Zustimmung gilt höchstens 15 Minuten und kann mit dem Angebot früher ablaufen. Die Bestätigung reserviert die Kostenobergrenze und trägt den auszuführenden Auftrag in derselben Transaktion ein.

curl 'https://guteneo.com/api/dispatches/dsp_identifiant_recu' \
  --header "Authorization: Bearer $GUTENEO_ACCESS_TOKEN"

• prepared : Vorbereitung gespeichert, noch nicht in der Warteschlange.
• queued : Bestätigung angenommen, Auftrag ausstehend.
• submitting / submission_unknown : Der Anbieter kann die Anfrage bereits erhalten haben. Keine automatische Wiederholung und keine neue Ersatzsendung.
• accepted : Vom Anbieter angenommen; dies ist kein Zustellnachweis. Prüfen Sie die nachfolgenden Ereignisse.

Lesen Sie nach einer HTTP-Zeitüberschreitung zunächst die Sendung erneut. Eine Stornierung ist nur vor Beginn der Übermittlung möglich, bei prepared oder queued. CANCELLATION_TOO_LATE bedeutet, dass eine Stornierung nicht mehr garantiert ist.

Antworten unterscheiden immer zwischen mode: simulation und production. Guthaben und Obergrenzen sind Ganzzahlen in EUR-Cent. Ein anteiliges Preisangebot enthält außerdem quote_customer_nanoeur : 1 EUR entspricht einer Milliarde nanoEUR. Die Abbuchung in Cent folgt der exakten kumulierten Summe der Organisation, ohne jede E-Mail auf einen Cent aufzurunden. Diese Felder können in Listen fehlen oder null sein. Das bedeutet keinen Preis von null.

Für Fax v3 liefert faxPricing die Preisspanne ohne Steuern in nanoEUR und die feste Kostenobergrenze in Cent. Die Obergrenze wird bei der Bestätigung reserviert. Prüfen Sie anschließend settlement.status : Eine Zustellung kann abgeschlossen sein, während die Abrechnung noch den Status hat reserved. Nur settled liefert den bestätigten Verbrauch und die Guthabenabbuchung. Der qualifizierte Tarif begrenzt Faxe auf höchstens zehn Seiten, auch wenn die PDF-Datei importiert werden konnte.

Im Produktivbetrieb benötigt jeder Kanal eine qualifizierte private Preisgestaltung und ein noch gültiges Angebot. Kein vom Client übermittelter Anbieterbetrag kann diese ersetzen. Die unverbindlichen Preise auf der Startseite sind kein API-Angebot.

05 / GRENZEN UND FEHLER

Wartezustände einplanen.

PDF

10 MiB · höchstens 100 Seiten

E-Mail-HTML und -Text

128 KiB UTF-8 pro Inhalt

CSV

256 KiB · höchstens 500 Zeilen

Listen

30 Elemente standardmäßig · höchstens 100

Authentifizierte API

180 Anfragen pro Minute und Organisation

Erneute PDF-Prüfungen

10 pro Tag und Organisation

Für Uploads und Renderings gelten auch tägliche Kontingente je Organisation. Listen geben Folgendes zurück: items und nextCursor ; senden Sie diesen undurchsichtigen Cursor unverändert zurück. CSV-Prüfantworten trennen rows, errors und duplicates : Ein HTTP-Erfolg bedeutet nicht, dass jede Zeile gültig ist.

Ein Fehler enthält { "error": { "code", "message" } }, manchmal eine Liste fields. Bewahren Sie den Code und X-Correlation-ID für die Diagnose auf, ohne Dokument, Empfänger oder Token zu protokollieren.

• 401 / 403 : Authentifizierung oder Berechtigung; ONBOARDING_REQUIRED erfordert zunächst eine Anmeldung im Browser.
• 409 : Unvereinbare Freigabe, Angebot, Guthaben, Kontingent oder Status. Beheben Sie die Ursache. Ändern Sie nicht den Schlüssel, um den Versand zu erzwingen.
• 413 / 423 : Inhalt zu groß oder Dokument nicht abrufbar.
• 429 : Anfragen verlangsamen. Die HTTP-Begrenzung gibt Folgendes zurück: Retry-After: 60 ; Dokumentkontingente enthalten diesen Header nicht unbedingt.
• 503 : Erforderliche Konfiguration oder Dienst nicht verfügbar. Die öffentliche Demonstration antwortet dagegen mit 403 PREVIEW_ONLY.

GET /api/usage unterscheidet Willkommensguthaben, Reservierungen und Monatsobergrenzen. Das Guthaben erneuert sich nicht. Bei unbekanntem Anbieterergebnis bleibt die Reservierung bestehen; dies rechtfertigt niemals einen automatischen erneuten Versand.