Construire un document multipage avec NextPDF Connect

En bref

Crée un document de plusieurs pages avec NextPDF Connect. add_page ajoute une page qui hérite de la géométrie par défaut du document ou redéfinit son orientation. Après chaque add_page, le curseur est replacé sur la marge supérieure gauche de la nouvelle page. Tu utilises quatre outils, tous Core : create_pdf, add_text, add_page et output_pdf.

Installation

composer require nextpdf/server

Configure un transport : MCP stdio, REST ou gRPC. Aucun palier de licence n’est requis.

Vue d’ensemble conceptuelle

Un document est un arbre de pages. Chaque page est un nœud accessible via cet arbre (ISO 32000-2 §7.7.3). Une page porte ses propres attributs de géométrie, dont la boîte de média, qui définit la zone visible (ISO 32000-2 §7.7.3.3). create_pdf crée automatiquement la première page, et add_page ajoute chaque nouvelle page à la suite. Omets page_size/orientation pour hériter des valeurs par défaut du document. Définis orientation: "landscape" pour faire pivoter une page A4 en 297×210 mm.

Surface de l’API

Outil	Rôle	Niveau de risque
`create_pdf`	Ouvre la session et crée la première page	Sûr
`add_text`	Écrit du texte à la position du curseur	Attention
`add_page`	Ajoute une page (héritage ou redéfinition)	Attention
`output_pdf`	Génère et renvoie le PDF	Approbation requise / Revue (base64)

Les noms d’outils correspondent aux noms de protocole du registre. Le catalogue d’outils fait foi. Les outils dont tu disposes dépendent du palier installé.

Exemple de code — Démarrage rapide

En prose :

create_pdf (A4 portrait, titre, auteur) → document_id.
add_text (titre, grande police, centré), puis add_text (paragraphe d’introduction, police de corps).
add_page avec uniquement le document_id → hérite du format A4 portrait. Le nouveau page_number est renvoyé et le curseur est réinitialisé.
add_text pour le titre de section et le corps en page 2.
add_page avec orientation: "landscape" → une page A4 en paysage.
add_text pour le contenu en paysage.
output_pdf → base64.

Exemple de code — Production

Valide chaque réponse. Après add_page, attends-toi à ce que le contenu commence en haut de la nouvelle page. La réinitialisation du curseur est un comportement intentionnel, pas un défaut. Surveille position.page dans les réponses de add_text pour détecter quand le contenu a débordé sur une page ultérieure. Appelle output_pdf exactement une fois, puis n’utilise plus le document_id.

Cas limites & pièges

Réinitialisation du curseur. Après add_page, le curseur est placé à la marge supérieure gauche de la nouvelle page. S’attendre à ce qu’il reprenne depuis la page précédente est l’erreur la plus fréquente.
document_id requis. Tous les outils sauf create_pdf exigent le document_id. L’omettre est une erreur.
Orientation invalide. Seuls "portrait" et "landscape" sont valides.
Édition après la sortie. L’ajout de contenu après output_pdf avec destroy: true échoue, car la session n’existe plus.

Performance

Un document texte multipage respecte le budget de pages, et la sortie pèse quelques Ko. Le profil est structural : le /ID de la bande-annonce et les horodatages ne sont pas stables d’une exécution à l’autre.

Notes de sécurité

Le mode base64 n’a aucun effet de bord. La sortie vers fichier est verrouillée (section HITL). Le document_id est un identifiant opaque. Ne le partage pas entre des requêtes concurrentes.

Conformité

Affirmation	Spécification	Clause	reference_id
Les pages sont accessibles via l’arbre de pages.	ISO 32000-2	§7.7.3
Un objet page définit ses propres attributs de géométrie.	ISO 32000-2	§7.7.3.3

Contexte commercial

Sans objet : tous les outils sont Core.

Disponibilité des transports

Transport	Disponible	Notes
MCP (stdio)	Oui	`tools/call` par outil.
REST	Oui	Une opération par outil.
gRPC	Oui	Appel unaire par outil.

Niveau de risque HITL

create_pdf est Sûr ; add_text et add_page sont Attention ; output_pdf est Approbation requise, rétrogradé en Revue en mode base64. La sortie vers fichier reste en Approbation requise. Voir output-approval et niveaux de risque HITL.

Enveloppe JSON de la barrière de confirmation

Sortie base64 ici :

{ "allowed": true }

Le formulaire de défi est présenté dans output-approval.