Comment un programme demande ses pages

Un programme écrit le document qu'il veut, envoie cette description par le réseau, et reçoit les pages finies dans la foulée. Voici comment, d'abord en mots simples, puis dans le détail exact.

Ce qui se passe, en mots simples

Pensez à une commande de gâteau. Vous écrivez sur un bout de papier ce que vous voulez — la taille, les mots écrits dessus, l'image au milieu — vous tendez le papier par-dessus le comptoir, et un peu plus tard le gâteau arrive. Vous ne voyez jamais le four, et vous n'en avez pas besoin.

Ici, cela marche pareil. Votre programme écrit ce que le document doit contenir : ce paragraphe ici, ce tableau là, cette image dans le coin. Il envoie ce papier par le réseau à notre serveur de documents. Le serveur dessine les pages et rend le PDF fini tout de suite, en réponse à cet appel-là.

Ce bout de papier s'écrit sous une forme sur laquelle toutes les machines s'entendent, appelée JSON. C'est du texte ordinaire, fait de noms et de valeurs, et il se lit pareil quel que soit le langage dans lequel votre programme est écrit.

Il n'y a rien à installer pour cela. Votre programme sait déjà envoyer quelque chose par le réseau, et c'est tout ce qu'on lui demande.

La même chose, pour qui écrit le programme

Votre programme envoie un formulaire au serveur. Une partie de ce formulaire porte la description du document. Chaque autre partie est un fichier sur lequel le document s'appuie : une feuille à en-tête à poser sous les pages, un profil de couleur, les données que porte une facture électronique. Ce à quoi sert un fichier est décidé par la description qui le nomme, jamais par le fichier lui-même.

La réponse, c'est le document. Pas un lien à aller chercher plus tard, pas un numéro de dossier à redemander : les octets du PDF fini reviennent dans la réponse à cet appel-là.

Deux lignes de plus dans la réponse disent combien de temps le travail a pris — une pour la lecture de la description, une pour le dessin des pages, toutes deux au millième de milliseconde près. C'est ainsi qu'on distingue le temps passé sur le réseau du temps passé à dessiner.

Une demande peut aller jusqu'à un demi-gigaoctet, ce qui fait beaucoup de papier à en-tête, et celui qui tient le serveur peut fixer une taille plus petite. Une demande au-dessus est renvoyée, avec cette taille écrite dans la réponse.

Qui a le droit d'appeler, à quelle fréquence, et pendant combien de temps un document peut être dessiné : tout cela se règle devant le serveur, par ce qui fait déjà face au réseau. Le serveur, lui, reçoit le nom du compte et dessine ce que ce compte a le droit de faire.

Les noms exacts

De quoi la demande et sa réponse sont faites
L'adresse qui dessine un document	`POST /render`
L'adresse qui dit que le service est debout	`GET /health`
La forme sous laquelle la demande est envoyée	`multipart/form-data`
La partie qui porte la description	`json_data`
Comment la clé voyage	`Authorization: Bearer <key>`
Ce qui revient	`application/pdf`
Le temps passé à lire la description	`X-HQF-Parse-Ms`
Le temps passé à dessiner les pages	`X-HQF-Render-Ms`

Une demande entière, aussi courte que possible

Ceci demande une page avec une ligne de texte dessus. Enregistrez-la à côté de votre programme, envoyez-la, et un PDF revient.

{
  "standard_fonts": [{ "name": "sans", "face": "helvetica" }],
  "items": [
    {
      "type": "text",
      "rect": { "llx": 56, "lly": 700, "urx": "{page_width} - 56", "ury": 780 },
      "content": ["Invoice 2026-014"],
      "font": "sans",
      "font_size": 24
    }
  ]
}

Et voici la ligne unique qui l'envoie.

curl -X POST https://your-server/render \
  -H "Authorization: Bearer <your key>" \
  -F "json_data=@hello.json;type=application/json" \
  -o hello.pdf

L'aller-retour, dessiné

Entre deux cases il y a toujours deux flèches : la première dit ce qu'on demande, la seconde dit ce qui revient.

Votre propre programme tourne chez le client
à l'aller : le document décrit en texte, et les fichiers sur lesquels il s'appuie au retour : le PDF fini, et le temps qu'a pris le dessin
Le serveur PDF à l'adresse que vous appelez
à l'aller : un appel par chose à dessiner : un paragraphe, un tableau, une image au retour : les pages, dessinées
La bibliothèque PDF à l'intérieur du serveur PDF

Deux morceaux, et pourquoi il y en a deux

Le serveur ne dessine rien lui-même. Il lit la description, la vérifie, puis appelle la bibliothèque une instruction à la fois : pose ce paragraphe, commence ce tableau, place cette image ici. C'est la bibliothèque qui écrit le fichier.

Ils sont deux parce qu'ils font deux métiers différents. La bibliothèque sait dessiner et ne sait rien du réseau. Le serveur connaît le réseau — qui appelle, jusqu'à quelle taille une demande peut aller, combien de pages un compte a le droit de faire — et ne sait rien du dessin.

Il y a une raison plus terre à terre encore. La bibliothèque travaille avec des polices d'écriture déjà chargées, prêtes à dessiner, alors qu'une description arrivée par le réseau n'en porte que le nom. Transformer ce nom en une police que la bibliothèque peut utiliser, c'est justement le travail du serveur, et c'est fait avant que la première lettre se pose sur une page.

C'est pour cela que la bibliothèque peut s'acheter et s'utiliser seule, appelée directement depuis un programme écrit en Rust ou en Python, sans serveur et sans qu'aucune description ne voyage. Et c'est pour cela que le même document sort pareil des deux côtés : c'est la même bibliothèque qui le dessine.

Dessiner un document occupe un processeur du début à la fin : chaque document est confié à un ouvrier à lui, et le serveur continue pendant ce temps à répondre à tous les autres.

Ce qui revient quand la demande n'est pas bonne

Chaque réponse dit ce qui s'est passé, en une phrase, et non par un code à aller chercher ailleurs. Et rien d'à moitié dessiné ne revient jamais : soit les pages sont là, soit la raison l'est.

Une page que le document n'a pas, on vous répond avec votre façon de compter à vous. Demandez un lien vers la page neuf d'un document qui en a cinq : la réponse dit page neuf. La bibliothèque, elle, compte à partir de zéro, et la réponse fait le calcul pour que vous n'ayez pas à le faire.

Toutes les réponses du serveur, par leur numéro
`200`	Les pages sont dans la réponse, et rien d'autre.
`400`	Quelque chose dans la description n'a pas pu servir : une police que personne ne fournit, une position illisible, une feuille à en-tête qui n'est pas un PDF. La réponse dit laquelle, en une phrase.
`402`	L'une des rares choses que porte une clé. La réponse nomme ce qui a été demandé et dit qu'une clé le couvre.
`413`	La demande, ou le document qu'elle produirait, dépasse une taille que le serveur a reçu l'ordre d'accepter. La réponse nomme cette taille.
`500`	Quelque chose s'est mal passé du côté du serveur, et non dans votre demande.

Les questions qu'on pose en premier

Garde-t-on quelque chose de mon document ?

Non, pas les pages. Le PDF fini repart dans la réponse à votre appel, et il n'est jamais écrit sur un disque en chemin.

La description que vous avez envoyée, et tout fichier envoyé avec elle, ne sont gardés que le temps du dessin, et seulement dans la mémoire de la machine. Ni l'une ni les autres ne sont écrits sur un disque, et tout disparaît dès que les pages sont parties.

Une seule chose est écrite sur un disque : la police d'écriture. Si votre compte a le droit d'envoyer ses propres polices, alors une police dont le dessin s'est vraiment servi est gardée dans un dossier qui appartient à ce compte, pour que vous n'ayez jamais à l'envoyer une deuxième fois : ensuite, votre description se contente de la nommer. Une police envoyée mais qui n'a rien dessiné n'est pas gardée, et un dessin qui a échoué ne garde rien du tout. Un compte qui dessine avec les polices déjà présentes sur le serveur ne garde rien non plus.

Pour la facture, quatre choses voyagent du serveur de documents vers ce site, et rien d'autre : le nom du compte, un numéro qui désigne ce dessin-là, le moment où il a eu lieu, et le nombre de pages sorties. Rien de ce qui est écrit sur ces pages ne part avec elles. Elles patientent dans un petit fichier jusqu'à ce que ce site les ait prises, et elles en sortent dès qu'il l'a fait.

Le serveur tient un journal, comme tout programme sur une machine. Il écrit une ligne quand un dessin nomme une chose dont il ne s'est finalement pas servi — une police d'écriture, une image, une couleur que rien n'a choisie — et cette ligne porte le nom du compte et la remarque. Les pages reviennent dans tous les cas : c'est une remarque, pas un refus.

Si vous faites tourner le serveur sur vos propres machines, rien de tout cela ne nous parvient. Le comptage s'allume en lui donnant une adresse où envoyer, et un serveur à qui on n'en a donné aucune n'envoie rien nulle part.

Comment appelle-t-on le serveur, et sous quelle forme ?

Une adresse prend le travail, et la demande lui est envoyée sous forme de formulaire. Une partie de ce formulaire porte la description du document, écrite en texte ordinaire. Chaque autre partie est un fichier sur lequel le document s'appuie. Ce qui revient, c'est le PDF lui-même.

Tout ce qui sait envoyer un formulaire par le réseau peut l'appeler, quel que soit le langage. Le tableau ci-dessus donne l'adresse, la forme et la réponse au mot près, et le petit exemple plus bas est une demande entière qui marche.

Qu'est-ce que cela apporte par rapport à une bibliothèque gratuite ?

Beaucoup de documents s'écrivent chaque jour avec des bibliothèques gratuites, et plusieurs d'entre elles font très bien ce pour quoi elles ont été faites. Ce qui se vend ici est autre chose : un seul morceau qui couvre déjà tout le terrain, et quelqu'un qui en répond.

Le terrain est large. Du texte qui coule, des tableaux qui continuent sur autant de pages qu'il faut, des images, les couleurs d'imprimerie, des codes-barres, des formulaires à remplir, des fichiers faits pour s'ouvrir encore dans vingt ans, des fichiers faits pour être lus à voix haute à quelqu'un qui ne voit pas la page, et la place laissée pour un sceau. Une seule chose à apprendre, une seule à tenir à jour, et un seul endroit où écrire quand une page ne sort pas comme vous l'attendiez.

Le contrôle vient de l'extérieur. Il existe un programme gratuit appelé veraPDF dont tout le métier est d'ouvrir un fichier et de dire s'il suit les règles publiées, et chaque document d'archive montré sur ce site y passe. Nous n'en possédons aucune part, et lui ne sait rien de qui a écrit le fichier qu'il lit.

Le même document est écrit de trois façons — un programme Rust, un programme Python, et une demande au serveur — puis les trois sont relancées et comparées. Là où elles sortent pareil à l'octet près, c'est écrit à côté ; là où elles sortent pareil à l'œil mais pas à l'octet, c'est écrit aussi.

Et il y a un contrat, une société, et quelqu'un à qui écrire. Assembler soi-même plusieurs morceaux gratuits est une bonne façon de travailler, et c'est aussi un travail que quelqu'un doit faire, puis continuer à faire : quand deux d'entre eux ne s'accordent pas, c'est à vous de chercher pourquoi. Ici, c'est à nous.

La bibliothèque achetée d'un coup reste la vôtre : payée une fois, installée autant de fois que vous voulez, et elle ne s'arrête pas de marcher le jour où quelque chose se termine.

Faut-il installer quelque chose ?

Avec un abonnement, non. Vous appelez une adresse par le réseau et les pages reviennent. Rien ne s'installe chez vous et rien n'est à tenir à jour.

Si vous achetez le serveur, c'est un programme à lancer sur vos propres machines, avec une poignée de réglages : où vivent ses polices d'écriture, où vit sa clé, et jusqu'à combien de pages un document peut aller. Il écoute sur la machine elle-même et se place derrière ce qui, chez vous, fait déjà face au réseau.

Si vous achetez la bibliothèque seule, elle entre dans votre programme comme n'importe quelle autre pièce, depuis Rust ou depuis Python. Pas de serveur, pas de réseau, rien à faire tourner à côté.

Comment suis-je facturé ?

Au document et à la page. Chaque dessin est signalé une fois, avec le nombre de pages qu'il a produites, et un mois de dessins s'additionne en une seule facture.

Un envoi qui n'a pas pu partir tout de suite n'est pas perdu : il attend et part plus tard. Et un envoi qui arrive deux fois n'est compté qu'une seule, car chaque dessin porte un numéro à lui.

Quels langages de programmation peuvent l'appeler ?

Tous. La demande est du texte ordinaire envoyé par le réseau : tout ce qui sait faire cela sait demander un document, c'est-à-dire tous les langages d'aujourd'hui.

La bibliothèque du dessous est écrite en Rust et s'appelle tout aussi bien depuis Python, ce dont se sert une équipe qui achète la bibliothèque seule.

Que fait la version gratuite ?

Elle dessine, et elle signe son travail. Chaque page qu'elle produit porte une mention, et les mots de ces pages sont dessinés comme des formes plutôt que comme des lettres : les pages sont belles, et on ne peut rien en extraire.

Quelques rares choses appartiennent à la clé, et une copie gratuite qui en rencontre une le dit clairement et nomme la clé qui les couvre : écrire du texte dans l'une des quatorze polices d'écriture que tout lecteur possède déjà, et reprendre la page d'un autre document qui porte plus de cinquante mots à elle. Une copie gratuite dessine à partir de la police d'écriture que vous envoyez avec la demande.

Quelles règles sont vraiment contrôlées, et par qui ?

Les fichiers faits pour rester lisibles pendant des années, et ceux faits pour être lus à voix haute à quelqu'un qui ne voit pas la page, passent par veraPDF, le contrôleur gratuit cité plus haut, et il les accepte. Il est tenu par l'Open Preservation Foundation et la PDF Association, et nous ne possédons ni l'une ni l'autre.

Les fichiers destinés à une presse d'imprimerie sont tenus aux quatre choses que ce métier réclame, et cela avant qu'un seul octet soit écrit : s'il en manque une, le fichier est refusé plutôt que livré incomplet. Une page de ce site dit lesquelles.

Comment savoir si le service répond ?

Il existe une deuxième adresse dont c'est le seul métier. Elle ne dessine rien, elle ne coûte rien à interroger, et elle répond tant que le service est debout.

Compter vos documents ne retarde jamais un dessin. Les pages reviennent d'abord, et le comptage se fait tout seul ensuite.

Où aller ensuite

Tout ce que la bibliothèque met sur une page Des fichiers faits pour s'ouvrir encore dans vingt ans Des fichiers qu'un imprimeur passe sans poser de question

Voir les prix Voir les exemples

Glossaire

bibliothèque PDF: Un logiciel que vos propres programmes utilisent pour écrire des documents PDF. Il n'a ni fenêtre ni bouton : votre programme lui dit quoi dessiner, et il rend le fichier fini. Ce site l'appelle aussi le moteur, c'est la même chose sous un autre nom. Le serveur est un second programme, qui contient le moteur et répond à qui lui demande un document par le réseau ; et le service de rendu, c'est ce serveur quand il tourne sur nos machines plutôt que sur les vôtres.
octet: L'unité dans laquelle se compte le poids d'un fichier, comme un colis se compte en grammes. Mille octets font un kilo-octet, un million font un méga-octet — la taille d'une photo prise avec un téléphone. Un PDF d'une page pèse ici entre six mille et cent vingt mille, donc cent PDF tiennent dans la place de cinq photos.
veraPDF: Un programme gratuit qui vérifie qu'un fichier respecte vraiment les règles qu'il annonce. C'est celui qu'utilisent les services d'archives, donc c'est celui qui sert ici : un document n'est pas conforme parce qu'on l'affirme, il l'est parce que veraPDF l'a accepté.
Factur-X: Une facture qui sert deux lecteurs à la fois. Pour la personne qui la reçoit, c'est une page ordinaire. Pour son logiciel de comptabilité, ce sont les mêmes montants rangés à l'intérieur du même fichier, sous une forme qu'il lit tout seul : plus rien à retaper. La loi française l'impose entre entreprises.
profil de couleur: Un fichier qui dit à quoi une couleur ressemble pour de vrai. Sans lui, le même rouge ne sort pas pareil sur un écran et sur du papier. Un document destiné à l'imprimerie emporte donc avec lui le profil sur lequel ses couleurs ont été choisies.
police: Le dessin de chaque lettre, de chaque chiffre et de chaque signe qu'un document écrit, rangé dans un fichier à part. Un PDF emporte à l'intérieur de lui-même les polices dans lesquelles il est composé : c'est pour cela qu'il s'ouvre à l'identique sur une machine qui ne les a jamais eues. Sans elles, un lecteur en met une autre à la place, et la mise en page bouge.
code-barres: Des barres noires et des blancs de largeurs différentes, qui représentent un numéro qu'un scanner relit d'un seul passage. Les barres portent le numéro et rien d'autre : le prix, l'article et la livraison se retrouvent à partir de lui. Un code récupéré en image puis redimensionné, ou rogné de trop près, cesse tout simplement d'être lu.

Tous les mots que le site explique