Är Dokumenter.
Äre Wee, fir se ze schécken.

01 / DEN OFLAF

Virbereeden. Kontrolléieren. Bestätegen.

Eroplueden a Virbereedung léise keng Kommunikatioun aus. Erstellt nom Start vun der Beta fir d’éischt Äre Guteneo-Beräich am Browser a bestätegt Är E-Mail-Adress. Verbannt duerno e registréierten OAuth-Client mat den néidege Berechtegungen.

1. Lued d’PDF-Datei erop. Schéckt d’Originaldatei am Feld file. Waart op de Status ready : Eng 201-Äntwert kann nach en Dokument a Quarantän bezeechnen.
2. Bereet d’Sendung vir. Wielt d’Dokument an den Empfänger. Behält d’Äntwert, hir id, hire Fangerofdrock an déi zeréckginn Zommen. Eng eventuell Käschtegrenz gëtt an EUR-Cent uginn.
3. Standardfräigab. Leet d’Persoun weider op https://guteneo.com/#/app/dispatch/{id}. Si kontrolléiert d’PDF-Datei, den Empfänger, d’Optiounen an d’Käschten a gëtt duerno an hirer Guteneo-Sessioun d’Fräigab. De fakultativen Expertmodus follegt engem begrenzte Mandat, dat virdrun ënner Mäi Kont fir de betraffenen Assistent aktivéiert gouf.
4. Bestätegen a verfollegen. De Client kann duerno Folgendes opruffen: POST /api/dispatches/{id}/confirm, mat engem eegenen Idempotenzschlëssel fir dës Bestätegung. Liest duerno de Status vun der Sendung nach eng Kéier.

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" }
  }'

Dës Beispiller si Ufrovirlagen, keng geliwwert Zougangsdonnéeën. D’Ëmweltvariabel enthält en Zougrëffstoken, deen Ären OAuth-Client kritt huet. Setzt en ni an eng URL oder an e Code-Repository. Kee Beispill gëtt vun dëser Säit aus ausgeféiert.

D’REST-Resultat ass déi onveraarbecht Sendung. D’Feld approvalUrl gehéiert zur MCP-Äntwert. Baut bei REST de Browserlink mat der zeréckginner Kennung. E Jo am Gespréich an eng Wierkzeugberechtegung erstellen weder eng mënschlech Fräigab nach en Expertmandat. Den Expert-Oflaf iwwer MCP benotzt eng rezent Kontroll an duerno eng delegéiert Fräigab; e respektéiert d’Grenze vum Mandat an d’Bestätegunge vun Ärem Assistent.

Liest fir Bréifpost als éischt d’Virlag mat GET /api/postal/requirements?country=LU, mat der Angab vum Land vum Empfänger. Benotzt nom Erstellen an Importéiere vun der PDF-Datei POST /api/postal/preflights : Guteneo kontrolléiert genee dës PDF-Datei a gëtt Folgendes zréck: reviewUrl. Am Standardmodus mécht d’Persoun dëse Link op, liest d’Säiten no an autoriséiert d’Iwwerdroung un den Drockubidder. Den Expertmodus erfuerdert e Postmandat, dat dësen Datentransfert separat ofdeckt; e léist kee Versand aus. Frot no der Analys vum Entworf Folgendes un: POST /api/postal/preflights/{id}/quote, a loosst duerno d’Devis fräiginn. Dës Schrëtt bleiwe vum Versand getrennt. En ongewëssen Transfert däerf ni automatesch widderholl ginn.

02 / AUTHENTIFIZÉIERUNG

Genee Berechtegungen.

Cliente benotzen Authorization Code mat PKCE S256, eng genee registréiert Retour-URI an e kontrolléierte Parameter state . D’Audience ass https://guteneo.com/mcp, och fir déi dokumentéiert REST-Routen. Et gëtt weder e perséinlechen API-Schlëssel nach e Passwuert, dat un en Assistent weiderzeginn ass.

Autorisatioun

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

Code-Austausch

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

HTTP-Token

Authorization: Bearer <access_token>

Benotzt en Zougrëffstoken, ni en ID-Token. En ëffentleche Client enthält kee Client-Geheimnis. D’Organisatioun gëtt duerch d’Memberschaft an déi autoriséiert Verbindung bestëmmt. Kee Parameter erlaabt et, fräi en anere Beräich ze wielen. Bei méi Beräicher gëtt d’Verknëppung an de Verbindunge vum Dashboard gemaach. D’Lieserroll verbitt Schreifzougrëffer, och mat engem Scope. Wärend der Beta ass e verifizéierte Kont fir all Roll néideg; Zweefaktor-Authentifizéierung ass net obligatoresch.

Kee Scope autoriséiert eng mënschlech Fräigab. D’Fräigabroute am Browser, d’Administratioun an d’Rechnunge gehéieren net zu dëser Entwéckler-API. OAuth-Berechtegungen ersetzen d’Kontrolle vu Roll, Ofsender, Kredit oder Kanal net.

Fir Assistenten ass MCP Streamable HTTP als Transport virgesinn op https://guteneo.com/mcp. Integratiounsdateie sinn disponibel an den Installatiounsinstruktiounen. All Client muss weider registréiert an a senger richteger Ëmwelt getest ginn.

03 / DOKUMENTER

En Original bleift en Original.

POST /api/documents behält déi eropgeluede Byte. De PDF ass privat, duerch säi SHA-256 identifizéiert a gëtt an enger isoléierter Ëmwelt analyséiert a kontrolléiert. GET /api/documents/{id}/content gëtt nëmmen e fäerdegt Dokument zeréck, mam Header X-Document-SHA256 an ouni ëffentleche Cache.

POST /api/documents/render erstellt en neien A4-PDF aus bereinegtem HTML. Skripten, matgeliwwert Stiler an extern Ressourcë ginn ewechgeholl. Dëst Rendering däerf net benotzt ginn, fir en Original aus sengem Text nozebauen. Den URL-Import ass dem MCP-Wierkzeug virbehalen: import_document, op all ëffentlecher HTTPS-Domain, ouni Ëmleedung. Et ass keng REST-Route.

D’Feld analysis weist, ob d’Kontroll leeft, fäerdeg ass, widderholl muss ginn oder blockéiert ass, mat enger Erklärung an enger nächster Aktioun. Frot wärend enger lafender Kontroll Folgendes of: GET /api/documents/{id} héchstens all 15 Sekonnen. De Server geréiert begrenzt automatesch Widderhuelungen. Bitt en ausdrécklechen Neistart un iwwer POST /api/documents/{id}/rescan nëmme wann déi zeréckginn Aktioun ass rescan. Behält datselwecht Dokument. Et muss net nei eropgeluede ginn.

04 / ZOUVERLÄSSEGKEET

Eng Ufro, eng Sendung.

Den Header Idempotency-Key ass fir Virbereedung a Bestätegung néideg: 1 bis 200 Zeechen, ouni Zeilenëmbréch oder NUL-Zeechen. Behält e feste Schlëssel pro logeschem Virgank a benotzt en anere Schlëssel fir d’Bestätegung. De selwechte Schlëssel mat engem aneren Inhalt féiert zu IDEMPOTENCY_CONFLICT.

De Fangerofdrock fingerprint bënnt de fräiginnene Contenu, den Empfänger, d’Dokument, d’Optiounen an d’Käschten. D’Zoustëmmung gëllt héchstens 15 Minutten a ka mat der Devis méi fréi oflafen. D’Bestätegung reservéiert d’Käschtegrenz a schreift d’Aarbecht an der selwechter Transaktioun an.

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

• prepared : Virbereedung gespäichert, nach net an der Warteschlaang.
• queued : Bestätegung ugeholl, Aarbecht ausstoend.
• submitting / submission_unknown : Den Ubidder kann d’Ufro scho kritt hunn. Keng automatesch Widderhuelung a keng nei Ersatzsendung.
• accepted : Vum Ubidder ugeholl; dat ass kee Liwwerbeweis. Kuckt déi Evenementer duerno.

Liest no engem HTTP-Timeout fir d’éischt d’Sendung nach eng Kéier. Eng Annulatioun ass nëmme virum Ufank vun der Iwwerdroung méiglech, fir prepared oder queued. CANCELLATION_TOO_LATE heescht, datt eng Annulatioun net méi garantéiert ass.

Äntwerten ënnerscheeden ëmmer tëscht mode: simulation an production. Salden a Käschtegrenze si ganz Zuelen an EUR-Cent. Eng Devis mat Brochdeeler enthält och quote_customer_nanoeur : 1 EUR entsprécht enger Milliard nanoEUR. D’Ofbuchung an Cent follegt der geneeër kumuléierter Zomm vun der Organisatioun, ouni all E-Mail op een Cent opzerronnen. Dës Felder kënnen a Lëschte feelen oder null sinn. Dat heescht net, datt de Präis null ass.

Fir Fax v3 liwwert faxPricing d’Präisspann ouni Steieren an nanoEUR an déi fest Käschtegrenz an Cent. D’Grenz gëtt bei der Bestätegung reservéiert. Kuckt duerno settlement.status : Eng Liwwerung ka fäerdeg sinn, wärend d’Ofrechnung nach dëse Status huet reserved. Nëmmen settled liwwert de validéierte Verbrauch an d’Ofbuchung vum Saldo. De qualifizéierten Tarif begrenzt Faxe op héchstens zéng Säiten, och wann d’PDF-Datei importéiert konnt ginn.

Am Produktivbetrib erfuerdert all Kanal eng qualifizéiert privat Präisgestaltung an eng nach gëlteg Devis. Keen Ubiddermontant, dee vum Client geliwwert gëtt, kann dës ersetzen. Déi onverbindlech Präisser op der Startsäit si keng API-Devis.

05 / GRENZEN A FEELER

Waartzoustänn aplangen.

PDF

10 MiB · héchstens 100 Säiten

E-Mail-HTML an -Text

128 KiB UTF-8 pro Contenu

CSV

256 KiB · héchstens 500 Zeilen

Lëschten

30 Elementer standardméisseg · héchstens 100

Authentifizéiert API

180 Ufroe pro Minutt an Organisatioun

Nei PDF-Kontrollen

10 pro Dag an Organisatioun

Fir Uploaden a Renderinge gëllen och deeglech Kontingenter pro Organisatioun. Lëschte ginn Folgendes zréck: items an nextCursor ; schéckt dësen opake Cursor onverännert zréck. CSV-Kontrolläntwerten trennen rows, errors an duplicates : En HTTP-Erfolleg heescht net, datt all Zeil gëlteg ass.

E Feeler enthält { "error": { "code", "message" } }, heiansdo eng Lëscht fields. Behält de Code an X-Correlation-ID fir d’Diagnos, ouni d’Dokument, den Empfänger oder den Token ze protokolléieren.

• 401 / 403 : Authentifizéierung oder Berechtegung; ONBOARDING_REQUIRED erfuerdert fir d’éischt eng Umeldung am Browser.
• 409 : Onpassend Fräigab, Devis, Kredit, Kontingent oder Status. Korrigéiert d’Ursaach. Ännert de Schlëssel net, fir de Versand ze erzwingen.
• 413 / 423 : Contenu ze grouss oder Dokument net opruffbar.
• 429 : Ufroe verlangsamen. D’HTTP-Grenz gëtt Folgendes zréck: Retry-After: 60 ; Dokumentkontingenter enthalen dësen Header net onbedéngt.
• 503 : Néideg Konfiguratioun oder Service net disponibel. Déi ëffentlech Demonstratioun äntwert dogéint mat 403 PREVIEW_ONLY.

GET /api/usage ënnerscheet Wëllkommenskredit, Reservatiounen a monatlech Grenzen. De Kredit erneiert sech net. Bei engem onbekannten Ubidderresultat bleift d’Reservatioun bestoen; dat rechtfäerdegt ni en automateschen neie Versand.