Vos documents.
Votre façon de les envoyer.

01 / LE PARCOURS

Préparer. Vérifier. Confirmer.

Le dépôt et la préparation ne déclenchent aucune communication. Après l’ouverture de la bêta, commencez par créer votre espace Guteneo dans le navigateur et vérifier votre adresse e-mail. Connectez ensuite un client OAuth enregistré avec les droits nécessaires.

1. Déposez le PDF. Envoyez le fichier original dans le champ file. Attendez son état ready : une réponse 201 peut encore désigner un document en quarantaine.
2. Préparez l’envoi. Choisissez le document et le destinataire. Conservez la réponse, son id, son empreinte et les montants retournés. Votre plafond éventuel est exprimé en centimes EUR.
3. Validation standard. Orientez la personne vers https://guteneo.com/#/app/dispatch/{id}. Elle vérifie le PDF, le destinataire, les options et le coût, puis approuve dans sa session Guteneo. Le mode expert facultatif suit un mandat limité, activé au préalable dans Mon compte pour l’assistant concerné.
4. Confirmez et suivez. Le client peut alors appeler POST /api/dispatches/{id}/confirm, avec une clé d’idempotence propre à cette confirmation. Relisez ensuite l’état de l’envoi.

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": "+352000000000" }
  }'

Ces exemples sont des modèles de requête, pas des accès fournis. La variable d’environnement contient un jeton d’accès obtenu par votre client OAuth ; ne le placez jamais dans une URL ou dans un dépôt de code. Aucun exemple n’est exécuté depuis cette page.

Le résultat REST est l’envoi brut. Le champ approvalUrl appartient à la réponse MCP ; en REST, construisez le lien navigateur avec l’identifiant retourné. Un « oui » dans une conversation et une autorisation d’outil ne créent ni approbation humaine ni mandat expert. Le parcours MCP expert utilise une revue récente puis l’approbation déléguée ; il respecte les limites du mandat et les confirmations de votre assistant.

Pour le courrier, lisez d’abord le gabarit avec GET /api/postal/requirements?country=LU, en indiquant le pays du destinataire. Après avoir créé et importé le PDF, utilisez POST /api/postal/preflights : Guteneo contrôle le PDF exact et retourne un reviewUrl. En mode standard, la personne ouvre ce lien pour relire les pages et autoriser le dépôt chez Pingen. Le mode expert exige un mandat postal couvrant séparément ce transfert de données ; il ne déclenche aucune expédition. Après l’analyse du brouillon, demandez POST /api/postal/preflights/{id}/quote, puis faites approuver le devis. Ces étapes restent distinctes de l’expédition ; un transfert incertain ne doit jamais être relancé automatiquement.

02 / AUTHENTIFICATION

Des permissions précises.

Les clients utilisent Authorization Code avec PKCE S256, une URI de retour enregistrée exactement et un paramètre state vérifié. L’audience est https://guteneo.com/mcp, aussi pour les routes REST documentées. Il n’existe pas de clé API personnelle ni de mot de passe à transmettre à un assistant.

Autorisation

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

Échange du code

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

Jeton HTTP

Authorization: Bearer <access_token>

Utilisez un jeton d’accès, jamais un ID token. Un client public ne contient aucun secret client. L’organisation est déterminée par l’adhésion et la connexion autorisée ; aucun paramètre ne permet de choisir librement un autre espace. Avec plusieurs espaces, l’association se fait dans les connexions du tableau de bord. Le rôle de lecteur interdit les écritures, même avec un scope. Pendant la bêta, un compte vérifié est requis pour tous les rôles ; la double authentification n’est pas obligatoire.

Aucun scope n’autorise l’approbation humaine. La route navigateur d’approbation, l’administration et la facturation ne font pas partie de cette API développeurs. Les droits accordés par OAuth ne remplacent pas les contrôles de rôle, d’expéditeur, de crédit ou de canal.

Pour les assistants, le transport prévu est MCP Streamable HTTP sur https://guteneo.com/mcp. Les fichiers d’intégration sont disponibles depuis les instructions d’installation. Chaque client doit encore être enregistré et testé dans son environnement réel.

03 / DOCUMENTS

Un original reste un original.

POST /api/documents conserve les octets déposés. Le PDF est privé, identifié par son SHA-256 et soumis à une analyse ainsi qu’à une validation dans un environnement isolé. GET /api/documents/{id}/content restitue uniquement un document prêt, avec l’en-tête X-Document-SHA256 et sans cache public.

POST /api/documents/render fabrique un nouveau PDF A4 à partir de HTML nettoyé. Les scripts, styles fournis et ressources externes sont retirés. Ce rendu ne doit pas servir à reconstruire un original à partir de son texte. L’import d’une URL est réservé à l’outil MCP import_document, sur tout domaine public en HTTPS, sans redirection ; ce n’est pas une route REST.

Le champ analysis indique si la vérification est en cours, terminée, à relancer ou bloquée, avec une explication et une prochaine action. Pendant une vérification en cours, consultez GET /api/documents/{id} toutes les 15 secondes au maximum. Le serveur gère les reprises automatiques limitées. Proposez une relance explicite via POST /api/documents/{id}/rescan seulement lorsque l’action retournée est rescan. Conservez le même document : aucun nouveau dépôt n’est nécessaire.

04 / FIABILITÉ

Une demande, un envoi.

L’en-tête Idempotency-Key est obligatoire pour préparer et confirmer : 1 à 200 caractères, sans retour à la ligne ni caractère NUL. Gardez une clé stable par opération logique ; utilisez une autre clé pour la confirmation. Réutiliser une clé avec un contenu différent produit IDEMPOTENCY_CONFLICT.

L’empreinte fingerprint lie le contenu, le destinataire, le document, les options et le coût approuvés. L’accord dure au maximum 15 minutes et peut expirer plus tôt avec le devis. La confirmation réserve le plafond et inscrit le travail à effectuer dans la même transaction.

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

• prepared : préparation enregistrée, pas encore mise en file.
• queued : confirmation acceptée, travail en attente.
• submitting / submission_unknown : le fournisseur peut déjà avoir reçu la demande. Aucune relance automatique ni nouvel envoi de remplacement.
• accepted : accepté par le fournisseur ; ce n’est pas une preuve de livraison. Consultez les événements suivants.

Après un délai d’attente HTTP, relisez d’abord l’envoi. Une annulation est possible seulement avant le début de la soumission, pour prepared ou queued. CANCELLATION_TOO_LATE signifie que l’annulation n’est plus garantie.

Les réponses distinguent toujours mode: simulation et production. Les soldes et plafonds sont des entiers en centimes EUR. Un devis fractionnaire expose aussi quote_customer_nanoeur : 1 EUR vaut un milliard de nanoEUR. Le débit en centimes suit le cumul exact de l’organisation, sans arrondir chaque e-mail à un centime. Ces champs peuvent être absents des listes ou null ; cela ne signifie pas un prix nul.

Pour le fax v3, faxPricing fournit la fourchette HT en nanoEUR et le plafond ferme en centimes. Le plafond est réservé à la confirmation. Consultez ensuite settlement.status : une livraison peut être terminée alors que le décompte est encore reserved. Seul settled fournit la consommation validée et le débit du solde. Le tarif qualifié limite le fax à dix pages au maximum, même si le PDF a pu être importé.

En production, chaque canal exige une tarification privée qualifiée et un devis encore valide. Aucun montant fournisseur fourni par le client ne peut les remplacer. Les tarifs indicatifs de la page d’accueil ne constituent pas un devis API.

05 / LIMITES ET ERREURS

Prévoir les cas d’attente.

PDF

10 Mio · 100 pages maximum

HTML et texte e-mail

128 Kio UTF-8 par contenu

CSV

256 Kio · 500 lignes maximum

Listes

30 éléments par défaut · 100 maximum

API authentifiée

180 requêtes par minute et organisation

Réexamens PDF

10 par jour et organisation

Les dépôts et rendus ont aussi des quotas quotidiens propres à l’organisation. Les listes renvoient items et nextCursor ; renvoyez ce curseur opaque sans le modifier. Les réponses de validation CSV séparent rows, errors et duplicates : un succès HTTP ne signifie pas que chaque ligne est valide.

Une erreur contient { "error": { "code", "message" } }, parfois une liste fields. Conservez le code et X-Correlation-ID pour le diagnostic, sans journaliser le document, le destinataire ou le jeton.

• 401 / 403 : authentification ou permission ; ONBOARDING_REQUIRED demande d’abord une connexion au navigateur.
• 409 : approbation, devis, crédit, quota ou état incompatible. Corrigez la cause ; ne changez pas de clé pour forcer l’envoi.
• 413 / 423 : contenu trop volumineux ou document non consultable.
• 429 : ralentissez. La limite HTTP renvoie Retry-After: 60 ; les quotas documentaires n’ont pas nécessairement cet en-tête.
• 503 : configuration ou service requis indisponible. La démonstration publique répond quant à elle 403 PREVIEW_ONLY.

GET /api/usage distingue le crédit de bienvenue, les réservations et les plafonds mensuels. Le crédit ne se renouvelle pas. Une issue fournisseur inconnue conserve la réservation ; elle ne justifie jamais une nouvelle expédition automatique.