L’API qui crée vos PDF

Votre programme décrit en JSON le document qu’il veut, l’envoie en un appel, et le PDF fini revient dans la réponse.

Résumé

Pensez à commander un gâteau. Vous écrivez ce que vous voulez dessus, vous tendez cette description par-dessus le comptoir, et le gâteau revient par le même comptoir un moment plus tard. Rien d’autre ne se passe, et vous ne voyez jamais la cuisine.

La description, ici, est un texte que votre programme écrit. Il dit ce qui va sur la page : cette phrase à cet endroit, ce tableau en dessous, ce logo dans le coin, ce QR code en bas. Tout ce dont la page a besoin et que le texte ne peut pas contenir — une photographie, un papier à en-tête — voyage à côté.

Cette description 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 de la même façon quel que soit le langage dans lequel votre programme est écrit.

Ce qui revient, c’est le document fini, prêt à être envoyé à un client ou à un imprimeur. Il revient dans la réponse à l’appel lui-même, tout de suite.

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à.

Rien ne s’installe pour appeler cette adresse : votre programme sait déjà envoyer quelque chose par le réseau, et c’est tout ce qu’on lui demande.

Il y a vingt-cinq choses que vous pouvez mettre sur une page : des paragraphes, des tableaux, des photographies, des pages prises dans un autre document, les cinq sortes de code-barres et de code carré, des formes simples, les champs d’un formulaire à remplir, et des liens cliquables. Chacune a ici une page à elle, avec le plus court exemple qui la dessine.

À côté d’elles, quatre-vingts clés règlent tout ce qui entoure le contenu du document : la liste de ce qui va sur les pages et, avec elle, le format de la feuille, les polices, ce que le fichier dit de lui-même, la façon dont un lecteur s’y retrouve, les couleurs et le rendu final. Chacune de ces clés a elle aussi sa page, si bien que cette section compte cent cinq pages : une par élément que vous pouvez placer sur une page, et une par clé.

Deux morceaux, et pourquoi il y en a deux

Le serveur ne crée aucun fichier PDF lui-même. Il lit la description, la vérifie, puis appelle la bibliothèque une instruction à la fois : compose 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 créer des pages et ne sait rien du réseau. Le serveur connaît le réseau — qui appelle, jusqu’à quelle taille une requête peut aller, combien de pages un compte a le droit de faire — et ne sait rien de la création des pages.

La bibliothèque travaille avec des polices déjà chargées et prêtes à tracer, alors qu’une description qui arrive par le réseau n’en contient que le nom. Transformer ce nom en une police que la bibliothèque sait employer est exactement le travail du serveur, et c’est fait avant que la première lettre ne 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 qu’un document sort identique des deux côtés, page pour page : c’est la même bibliothèque qui l’écrit.

Créer un PDF occupe un processeur du début à la fin : chaque requête est traitée par un processus qui n’a qu’elle à faire, et le serveur continue pendant ce temps à répondre à tous les autres.

L’aller-retour, dessiné

  1. Votre propre programme tourne sur vos propres machines
  2. Le serveur à l’adresse que vous appelez
  3. La bibliothèque dans le serveur

Ce qui a été remarqué pendant la création

À côté du document fini, la réponse dit ce qui a été remarqué pendant la création. C’est une remarque, pas un refus : les pages sont bien les pages que vous avez demandées, et une remarque les laisse exactement telles qu’elles sont.

La réponse dit toujours combien il y a eu de remarques, et un zéro est une réponse à part entière : rien n’a été remarqué pendant la création du PDF.

Deux choses font l’objet d’une remarque aujourd’hui. La première est quelque chose que votre description a envoyé et qu’aucune page n’a jamais employé — une police, une photographie, une couleur, un calque. Cet élément a fait le voyage et il est entré dans le fichier : celui-ci est donc plus lourd que les pages ne l’exigeaient.

La seconde est une police accompagnée d’une note de licence de son créateur, qui dit comment elle peut être transmise. Le document est écrit avec cette police incorporée, et la remarque répète ce que dit la note de licence, pour que vous puissiez la comparer à la licence sous laquelle vous avez acheté cette police. Cette licence est la vôtre et reste chez vous : c’est la seule chose que le fichier ne puisse pas contenir.

Dix remarques au plus reviennent dans la réponse, tandis que le compte dit combien il y en a eu réellement. Il n’existe aucun moyen d’obtenir les autres : le serveur les inscrit toutes dans son propre journal.

Techniquement

Un seul POST /render en multipart/form-data : le document décrit en JSON dans la partie json_data, les fichiers qu’il nomme dans les parties voisines, et en retour soit 200 application/pdf, soit un refus numéroté en texte brut.

Le transport

Une seule adresse, une seule méthode : un POST avec un corps multipart/form-data. La partie nommée json_data tient la description entière en JSON. Toute autre partie est un fichier que la description désigne par le nom de cette partie — un PDF employé comme modèle de page ou importé page par page, une image, un profil ICC, un paquet XMP, le XML d’une facture. Il n’y a pas d’étape d’envoi préalable ni d’identifiant de ressource à garder : une partie ne dure que le temps de l’appel qui l’a transportée.

L’authentification se fait par une clé d’API transmise dans l’en-tête Authorization ; ce site la vérifie, en tire un nom de client et transmet ce nom dans son propre en-tête. En cas de réussite, la réponse est 200 avec application/pdf et le nombre de pages. Un refus renvoie un code de statut, une phrase en texte brut et x-hqf-refusal : un mot d’une liste fermée qui nomme le type de refus, et c’est lui que lit un programme. Il n’y a pas d’enveloppe à ouvrir ni de tâche à interroger. Le service que nous faisons tourner répond à un refus en JSON : sous kind, il transmet le mot du serveur ; sous error, il écrit une phrase à lui, qui cite celle du serveur.

Le service que nous faisons tourner refuse aussi de son propre chef, avec des mots qui lui sont propres et que liste la page de son adresse. L’un d’eux vient du compte du mois : quand tous les documents du mois sont consommés, il répond 429, avec Retry-After qui donne la date à laquelle le mois change. Un serveur que vous faites tourner ne compte aucun mois.

De quoi se composent un appel et sa réponse
L’appel qui crée un document, sur un serveur qui vous appartient POST /render
Le service que nous faisons tourner, qui reçoit ses propres appels POST https://hqf-pdf.com/api/v1/render
L’appel qui complète un PDF que vous envoyez, sur un serveur qui vous appartient POST /update
Le même appel, sur le service que nous faisons tourner POST https://hqf-pdf.com/api/v1/update
L’appel qui indique que le service fonctionne GET /health
Le même test de disponibilité sur le service que nous exploitons GET https://hqf-pdf.com/api/v1/health
La forme dans laquelle s’envoie le corps multipart/form-data
La partie qui contient la description json_data
Toute autre partie un fichier que la description nomme
Le trajet de la clé d’API Authorization: Bearer <key>
Ce que ce site transmet au serveur x-hqf-client: <name>
Ce que contient une réussite 200 application/pdf
Combien de pages compte le document fini x-hqf-pages
Combien de choses ont été remarquées pendant la création du PDF x-hqf-warnings
Une remarque, répétée une fois par remarque transportée x-hqf-warning
Combien de constats séparent le document des normes demandées x-hqf-findings
Un constat, répété une fois par constat transporté x-hqf-finding
Ce que contient une erreur text/plain
Le mot qui désigne la sorte d’un refus x-hqf-refusal
L’identifiant propre à ce refus x-hqf-refusal-id
Les valeurs mentionnées par le refus, en JSON encodé en pour-cent x-hqf-refusal-values
Le corps d’un refus sur notre service hébergé, y compris ces trois mêmes éléments application/json {"error": "…", "kind": "…", "id": "…", "values": {…}}
La version du service qui a répondu x-hqf-version

L’appel qu’accepte le service que nous faisons tourner, et toutes ses réponses

Le corps, partie par partie

Le corps est un formulaire en plusieurs parties, et chaque partie a un nom.

  • json_data contient la description du document, soit ses quatre-vingts clés. C’est la seule partie dont le nom est imposé.
  • Toute autre partie est un fichier dans lequel la requête puise, sous le nom que la description lui donne : un PDF posé sous les pages, nommé par templates, une image nommée par un élément image, un profil ICC nommé par output_intent ou par un espace icc, le XML nommé par invoice, un paquet de métadonnées nommé par une image. Ce qu’une partie est découle du JSON qui la nomme, jamais de la partie elle-même.
  • Le corps est gardé en mémoire en entier, et sa taille est plafonnée à 536 870 912 octets — 512 Mio — sauf réglage contraire sur le serveur.
  • Le service que nous faisons tourner plafonne de son côté le corps d’un appel à 536 870 912 octets, soit 512 Mio, et répond 413 en nommant body_too_large au-delà. Les deux plafonds sont deux réglages distincts, si bien qu’un serveur que vous faites tourner peut être réglé plus bas ou plus haut que celui décrit plus haut.

L’en-tête que ce site pose

Le serveur n’authentifie personne : ce site reçoit l’appel, vérifie la clé d’API et nomme le client à qui elle appartient, dans l’en-tête x-hqf-client. Le serveur lit ce nom et crée le PDF selon ce que prévoit le compte : ses polices, son plafond de pages, ses droits. Une requête qui nomme un client que le serveur ne connaît pas, ou qui n’en nomme aucun, est traitée avec les réglages par défaut. On peut se fier à cet en-tête parce que rien d’autre que ce site ne peut l’écrire : le serveur écoute sur la boucle locale et rien hors de cette machine ne l’atteint, et ce site réécrit l’en-tête à neuf sur chaque requête qu’il transmet.

Ce que rend une réussite

  • Le code de statut 200, et les octets du PDF comme corps.
  • Content-Type: application/pdf.
  • x-hqf-pages, combien de pages compte le document fini.
  • x-hqf-warnings, combien de choses le moteur a remarquées en écrivant le document, et un x-hqf-warning par remarque transmise.
  • x-hqf-findings, combien de constats séparent le document fini des normes que check a demandé de vérifier, et un x-hqf-finding par constat transmis. Les deux accompagnent une réponse qui contient un document, qu’une norme ait été demandée ou non.
  • Un serveur à vous répète l’en-tête une fois par valeur. Le service que nous faisons tourner ne donne le nom qu’une fois, ses valeurs séparées par des virgules ; la règle pour les découper est sur la page de ce service.

Ce qu’un rendu remarque

Une remarque est quelque chose que le moteur a noté en écrivant un document qu’il a écrit jusqu’au bout : les octets renvoyés sont ceux qu’un rendu sans rien à remarquer aurait renvoyés, et le code de statut reste 200. x-hqf-warnings donne leur nombre et accompagne toute réponse rendue, 0 compris ; une réponse qui ne contient pas cet en-tête vient d’un serveur plus vieux que l’en-tête lui-même.

x-hqf-warning est ensuite répété une fois par remarque transmise, dans l’ordre où le moteur les a faites. Dix au plus, pour mille octets en tout, selon celle des deux limites qui est atteinte la première. La remarque qui dépasse les octets restants est coupée et se termine sur %E2%80%A6, des points de suspension, et les remarques qui la suivent ne figurent que dans le journal du serveur — lequel les garde toutes en entier, au niveau INFO, sous le nom du client pour qui le rendu a été fait. Le compte annonce le nombre total dans tous les cas, si bien qu’un client qui lit x-hqf-warnings: 50 à côté de dix en-têtes sait exactement où il en est.

Ce sont ces deux chiffres qui permettent de livrer la réponse. Un serveur frontal plafonne la taille des en-têtes d’une réponse, et un document qui déclare cinquante ressources qu’il ne trace jamais produirait cinquante en-têtes : la réponse entière serait rejetée avant d’atteindre le client, et un document écrit sans faute arriverait sous la forme d’une panne du service.

  • Une ressource que la requête a déclarée et avec laquelle aucune page n’a rien dessiné — une police, une image, un dessin, un espace de couleur, un état graphique, un dégradé, un motif ou un calque. Elle est écrite dans le fichier et mise à la disposition de chaque page, et aucun flux de contenu ne la désigne. La remarque s’écrit the image Im2 is never drawn with, dans les mots du moteur.
  • Une police incorporée contre ce que son propre marqueur fsType permet : un marqueur qui interdit l’incorporation, un qui demande à entrer en entier là où seules les lettres dessinées sont entrées, ou un qui n’autorise que les images que la police contient là où des contours sont entrés. La remarque nomme la police comme la police se nomme elle-même, et le nom par lequel la requête la choisit — the font Foo (F1) must not be embedded without the owner's permission. La licéité de l’incorporation dépend de la licence sous laquelle la police a été achetée, et c’est à vous de la lire.
  • Chaque valeur est encodée en pour-cent et se décode comme une URL : chaque octet hors de l’ASCII imprimable s’écrit %XX, le signe pour cent lui-même %25 et la virgule %2C, si bien que Café arrive sous la forme Caf%C3%A9. Un en-tête ne contient que de l’ASCII, alors qu’une ressource est nommée par l’auteur de la requête et qu’une police se nomme elle-même dans sa propre licence : une remarque peut donc contenir tout ce que contiennent ces deux noms. Un client HTTP qui réunit les remarques en une seule valeur les sépare par une virgule ; comme aucune remarque n’en contient, découper cette valeur aux virgules restitue chaque remarque. Une remarque tronquée l’est toujours entre deux caractères : ce qui arrive se décode donc, et donne du texte.

La version qui a répondu, et la sonde de santé

GET /health renvoie un 200 et un petit objet JSON : version, le numéro de la version qui a répondu, licensed, si une licence couvre la date du jour, et faces, le nombre de polices que contient la bibliothèque générale. C’est ce que lit un superviseur ou un répartiteur de charge pour savoir que le service répond, et ce que lit un déploiement pour savoir que la version installée est bien celle qui répond maintenant.

Le même numéro figure sur chaque réponse que le service envoie, dans l’en-tête x-hqf-version : sur un document créé, sur un refus comme sur la sonde. Le client l’inscrit dans son propre journal à côté de l’appel qu’il a passé, de sorte qu’un document revenu erroné est rattaché à la version qui l’a créé ; et après un déploiement, on le lit pour distinguer une instance remplacée d’une instance restée en arrière. Une réponse qui ne contient pas cet en-tête vient d’une version plus ancienne que l’en-tête lui-même. Ce numéro appartient au service : le moteur a le sien, sur la page de la bibliothèque, et ce site en a un troisième, au bas de chaque page.

Le modèle

Une requête a un seul niveau supérieur : une liste d’éléments, et à côté les ressources que ces éléments nomment. Les polices, les espaces de couleur, les dégradés, les états graphiques, les calques et les dessins sont déclarés chacun une fois sous un nom, et un élément renvoie à ce nom. Une ressource se trouve par son nom, où qu’elle soit déclarée, et tout ce qui compte est écrit — un nom qu’un élément réclame et qu’aucune déclaration ne contient est refusé, avec le nom dans le message.

Les pages sont créées par ce qu’on pose dessus, elles ne sont pas déclarées d’avance. Un élément dit sur quelles pages il se pose ; la valeur par défaut, un tableau vide, veut dire toutes les pages, et c’est ainsi qu’un pied de page ou un filigrane s’écrit une seule fois. Un tableau qui déborde de son cadre se poursuit dans le cadre suivant et crée les pages qu’il lui faut, et les éléments posés sur toutes les pages l’y suivent.

La géométrie est en points typographiques avec l’origine en bas à gauche, comme le veut le format lui-même. Toute coordonnée peut être une expression arithmétique entre guillemets portant sur les dimensions de la page et le numéro de page courant, si bien qu’une marge de droite s’écrit "{page_width} - 56" plutôt qu’un nombre que votre programme aurait dû calculer. Un élément peut recevoir un nom, et un autre s’accrocher à son bord, ce qui garde une mise en page juste quand la hauteur d’un bloc n’est connue qu’une fois composé.

Ce qu’une requête contient en plus de ce qu’elle crée

La même requête énonce les métadonnées du document, la norme d’archivage qu’il déclare, l’intention de sortie au regard de laquelle ses couleurs se lisent, la compression de ses flux, le sommaire et les destinations nommées, les fils d’articles, les étiquettes de page, les préférences de lecture que le logiciel de lecture respecte, et le XML de facture qu’un document Factur-X contient. Un seul appel crée un fichier fini qui déclare ses normes : il n’y a ni second passage ni outil de retouche.

Les réponses, et ce qu’elles disent

La validation est complète et a lieu avant que rien ne soit dessiné : le serveur refuse une requête plutôt que de créer un document qui aurait perdu quelque chose en silence. Un refus est une phrase qui nomme la clé ou le nom en cause, et elle mérite d’être journalisée mot pour mot.

À côté d’elle se tient x-hqf-refusal, un mot d’une liste fermée : client_name, call_number, form, body_too_large, description, drawing, too_many_pages, needs_a_licence, server. C’est lui qu’un programme teste pour choisir la suite ; la phrase, elle, est écrite pour une personne. Un mot absent de cette liste vient d’un serveur plus récent que cette page. Le service que nous faisons tourner transmet ces mots tels quels sous kind, à côté de mots à lui, qu’énumère la page consacrée à son adresse.

Une clé qu’aucun objet de la requête ne lit est refusée nommément, où qu’elle se trouve ; sans ce refus, une clé mal orthographiée serait ignorée sans avertissement. Une clé écrite deux fois dans le même objet est refusée nommément. Les combinaisons contradictoires — une matrice avec une rotation, un lien qui déclare à la fois une cible courte et une action complète, une cellule de tableau qui contient deux choses — sont également refusées nommément.

Une page que le document n’a pas est refusée partout où une clé en nomme une — un signet, une destination nommée, la zone d’un fil d’articles — et le message nomme cette page dans la numérotation qu’a employée la requête : demandez la page neuf d’un document de cinq pages, le message dit page neuf.

Seules les bornes d’une règle de pages font exception : from et to peuvent désigner des pages au-delà de la dernière, car un titre courant est écrit avant que le nombre de pages du document soit connu.

Un document se crée vite : environ une seconde pour 60 pages, et environ 26 secondes pour 5 000 pages, le maximum qu’une requête peut demander. Ces deux durées ont été mesurées sur la machine où tourne ce site. Le site attend jusqu’à 125 secondes qu’un document soit prêt, soit plusieurs fois le temps qu’exige même le plus volumineux. Si un document dépasse un jour ce délai, l’appel revient sous le statut 500 avec un numéro d’incident, notre équipe est prévenue, et ce document n’est pas retiré de votre mois.

Les tableaux d’une même requête peuvent contenir au plus 2 097 152 entrées en tout, tous tableaux confondus. Chaque ligne, chaque largeur de colonne, chaque cellule et chaque ligne de texte dans une cellule compte pour une entrée. Au-delà, la requête est refusée avec le statut 400 et le mot description.

Toutes les réponses du service, par leur numéro
200 Le PDF est le corps. À côté figurent le nombre de pages et ce qui a été remarqué pendant la création : un compte, et un en-tête par remarque.
400 La requête doit être corrigée et renvoyée ; le corps de la réponse est une phrase en texte brut. Cas connus : le JSON ne se lit pas ; la partie json_data est absente ; une police nommée n’est déclarée nulle part ; une coordonnée ne peut pas être lue ; un lien ou un signet mène à une page que le document n’a pas, nommée dans la numérotation qu’emploie la requête elle-même ; une norme déclarée et un réglage que cette norme écarte se contredisent ; un niveau de compression n’est pas compris entre 1 et 9 ; un modèle de page fourni n’est pas un PDF qui se lit.
402 La requête demande quelque chose que seule une clé de licence couvre, sous x-hqf-refusal: needs_a_licence, ou sous kind sur le service que nous exploitons. La phrase nomme ce qui a été demandé et précise qu’une clé de licence le couvre. Tous les cas : du texte composé dans une police sans contour d’où tracer les glyphes — les quatorze polices standard, une police dont les glyphes sont des dessins, un programme Type 1 ; une page importée d’un autre document qui affiche plus de dix mille mots qui lui sont propres ; une page importée dont les mots ne peuvent pas être comptés du tout ; une déclaration d’accessibilité, ou d’archivage au niveau qui repose sur le fait de dire ce que les marques d’une page représentent ; une destination qui mène à un élément de l’arbre de structure. Les trois derniers tiennent à ce qu’une copie gratuite trace chaque glyphe comme une forme : le document n’a aucun arbre de structure sur lequel ils pourraient reposer.
413 Le corps de la requête dépasse la taille que le serveur accepte, ou le document dépasse 5 000 pages. La phrase nomme la taille ou le plafond de pages.
500 L’écriture du PDF ou du magasin de polices n’a pas abouti. Le problème vient du service, non de la requête.

Le service que nous exploitons répond à certains appels avant même qu’un serveur ne les lise : un appel sans clé d’API reçoit un 401, un appel passé un mois où il ne reste plus aucun document reçoit un 429, et il en existe d’autres. Chacune de ces réponses est décrite, avec la marche à suivre, sur la page de l’adresse concernée. L’appel qu’accepte le service que nous faisons tourner, et toutes ses réponses

Schéma de la requête

Toutes les clés d’une requête, avec leur type, leur caractère obligatoire ou non, et ce qu’elles valent quand on les laisse de côté. Chaque chiffre a été relevé sur les sources du serveur et vaut pour la version en production.

La plus petite requête qui crée un PDF

Une police déclarée, un élément, une ligne de texte. Enregistrez, envoyez, et un PDF d’une page revient.

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

Le même appel, écrit trois fois

Aucun des trois n’est une bibliothèque à installer : le serveur répond par le réseau, donc n’importe quel langage capable d’envoyer un formulaire l’appelle. En voici trois — un terminal, Python et JavaScript.

Copiez celui des trois qui correspond à vos outils. Chacun envoie la description et un fichier qu’elle emploie, et écrit la réponse directement sur le disque.

Ce que créent les bibliothèques Rust et Python

Depuis un terminal

Une partie contient la description, une partie par fichier qu’elle emploie. Le nom d’une partie est le nom sous lequel la description appelle ce fichier.

# invoice.json holds the smallest request above, plus
#   "templates": { "start": "letterhead.pdf" }
# The service we run takes a call of its own:
# POST https://hqf-pdf.com/api/v1/render described on
# https://hqf-pdf.com/en/api/pdf-api-endpoint/
curl -X POST https://your-server/render \
  -H "Authorization: Bearer $HQF_PDF_KEY" \
  -F "json_data=@invoice.json;type=application/json" \
  -F "letterhead.pdf=@letterhead.pdf" \
  -o invoice.pdf

Depuis Python

La clé d’API vient de l’environnement, et la réponse est le PDF lui-même : écrivez donc le corps directement dans un fichier. Le nombre de pages figure sur toute réponse qui rapporte un document.

import json
import os
import pathlib

import requests

KEY = os.environ["HQF_PDF_KEY"]
LETTERHEAD = pathlib.Path("letterhead.pdf")

description = {
    "templates": {"start": "letterhead.pdf"},
    "items": [
        {
            "type": "text",
            "rect": {"llx": 56, "lly": 700, "urx": "{page_width} - 56", "ury": 780},
            "content": ["Invoice 2026-014"],
            "font": "DejaVuSans",
            "font_size": 24,
        }
    ],
}

# The service we run takes a call of its own: POST https://hqf-pdf.com/api/v1/render
# described on https://hqf-pdf.com/en/api/pdf-api-endpoint/
answer = requests.post(
    "https://your-server/render",
    headers={"Authorization": f"Bearer {KEY}"},
    files={
        "json_data": ("request.json", json.dumps(description), "application/json"),
        "letterhead.pdf": ("letterhead.pdf", LETTERHEAD.read_bytes()),
    },
    timeout=120,
)
answer.raise_for_status()
pathlib.Path("invoice.pdf").write_bytes(answer.content)
print(answer.headers["x-hqf-pages"], "pages")

Depuis JavaScript

Un corps de formulaire et le fetch standard, exécutés par Node. La clé d’API vient de l’environnement et le modèle de page d’un fichier posé à côté du programme, et un refus arrive sous la forme d’une phrase en texte brut.

import { readFile, writeFile } from "node:fs/promises";

const key = process.env.HQF_PDF_KEY;
const letterhead = new Blob([await readFile("letterhead.pdf")]);

const description = {
  templates: { start: "letterhead.pdf" },
  items: [
    {
      type: "text",
      rect: { llx: 56, lly: 700, urx: "{page_width} - 56", ury: 780 },
      content: ["Invoice 2026-014"],
      font: "DejaVuSans",
      font_size: 24,
    },
  ],
};

const body = new FormData();
const asJson = JSON.stringify(description);
body.append("json_data", new Blob([asJson], { type: "application/json" }));
body.append("letterhead.pdf", letterhead, "letterhead.pdf");

// The service we run takes a call of its own:
// POST https://hqf-pdf.com/api/v1/render
// described on https://hqf-pdf.com/en/api/pdf-api-endpoint/
const answer = await fetch("https://your-server/render", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}` },
  body,
});
if (!answer.ok) {
  throw new Error(await answer.text());
}
await writeFile("invoice.pdf", new Uint8Array(await answer.arrayBuffer()));

Les clés d’une requête

Le premier niveau d’une requête compte quatre-vingts clés, toutes facultatives : chacune prend par défaut la valeur indiquée dans la colonne voisine, si bien qu’une requête ne précise que ce dont elle a besoin. Chaque clé renvoie à sa propre page.

Toutes les clés JSON d’une requête, au premier niveau
Clé JSON Type Par défaut À quoi cela sert
items tableau [] Tout ce qui est dessiné sur les pages, dans l’ordre de dessin.
page objet 595.276 × 841.89 Le format de feuille auquel chaque page est coupée, en points, sauf si une page indique le sien.
page_sizes tableau [] Une feuille à elle pour une page numérotée.
page_boxes tableau [] Les boîtes de recadrage, de fond perdu, de coupe et de dessin d’une page, ce qu’un imprimeur lit avant tout le reste.
page_turns tableau [] Dans quel sens une page est présentée à celui qui ouvre le fichier.
page_tab_orders tableau [] L’ordre dans lequel le clavier parcourt les champs d’une page.
page_shows tableau [] Comment une page arrive, et combien de temps elle reste, quand le logiciel de lecture montre le document en plein écran.
source objet — Un PDF envoyé avec la requête, dont les pages ouvrent le document, chacune à sa taille, sous tout ce que dessinent les éléments.
supplied_pdfs objet — La façon dont les PDF fournis avec la requête sont lus : jusqu’où un de leurs flux a le droit de se déplier.
structure objet — Ce dont le document dit être fait, dans l’ordre de lecture, pour qu’un programme le lise comme une personne le lirait plutôt que dans l’ordre où l’encre est tombée.
accessible chaîne — La norme d’accessibilité que le document déclare, vérifiée au regard de ce qu’il contient vraiment.
simple_fonts tableau [] Une police atteinte par des codes d’un octet, ajustés à un texte donné : une page plus légère, et un écartement des mots qui a un code à atteindre.
color_fonts tableau [] Une police dont les signes choisis apparaissent dans les couleurs que leur donne son fichier, couche par couche, d’après l’une de ses palettes.
fonts_described_only tableau [] Les polices dont le document ne contient que la description, sans leur programme.
font_permissions chaîne warn Ce que fait au document une police dont l’indicateur interdit l’incorporation.
whole_font_ceiling entier — Taille en octets jusqu’à laquelle un fichier de police est incorporé en entier dans le document.
attachments tableau [] Les pièces jointes du document, à côté de ses pages.
referenced_files tableau [] Les fichiers que le document nomme sans les contenir, rangés à côté de lui ou servis depuis une adresse.
collection objet — Comment un logiciel de lecture dispose les pièces jointes en portefeuille : les colonnes, l’ordre des lignes, et le fichier ouvert en premier.
page_files tableau [] Les pièces jointes qu’une page revendique comme siennes.
font_files tableau [] Les pièces jointes qu’une police revendique comme siennes.
font_metadata tableau [] La fiche d’identité propre à une police.
metadata_files tableau [] Les pièces jointes que revendique la fiche du document.
metadata_packet chaîne — La partie fournie qui contient la fiche du document, rédigée ailleurs et reprise telle quelle.
page_viewports tableau [] Les zones d’une page où un lecteur mesure, et dans quelles unités.
page_metadata tableau [] La fiche d’identité qu’une page contient, à côté de celle du document.
tilings tableau [] Une case répétée pour remplir une forme : hachure, tissage, fond.
fonts tableau [] Les polices transportées dans la requête en base64, chacune sous un nom que les éléments appellent, avec les caractères qu’elles gardent et ce qu’elles dessinent pour un caractère dont elles n’ont pas le glyphe.
type1_fonts tableau [] Polices Type 1, transportées de la même façon.
standard_fonts tableau [] L’une des quatorze polices que tout logiciel de lecture possède déjà, sous un nom de votre choix.
font_variants tableau [] Une police déclarée avec les ligatures, les petites capitales, les chiffres elzéviriens ou le crénage activés.
type3_fonts tableau [] Une police dont les glyphes sont des dessins, et non des contours.
font_chains tableau [] Deux polices ou plus essayées dans l’ordre : un glyphe qui manque à la première est pris dans la suivante.
templates objet — Les PDF fournis, placés en arrière-plan des pages : start sous les premières pages, page pour page ; middle, d’une seule page, sous toutes les autres pages ; end, ajouté après le contenu avec toutes ses pages, comptées et numérotées comme les autres.
watermarks tableau [] Une ligne que le document pose sur une suite de ses pages, au-dessus ou en dessous de leur contenu.
renumber tableau [] Où la numérotation des pages repart, dans quel style, et avec quel préfixe.
bookmarks tableau [] Le sommaire que le logiciel de lecture ouvre à côté de la page, imbriqué sur autant de niveaux que vous voulez.
destinations tableau [] Des endroits nommés du document qu’un lien ou une action peut viser.
articles tableau [] Des fils de lecture qui mènent le lecteur d’une colonne à la suivante.
document_parts objet — L’arbre des parties qu’un document PDF 2.0 déclare, chacune revendiquant une plage de pages et tenant des valeurs nommées.
private_data objet — Ce qu’un programme laisse dans le document pour lui-même, rangé sous son propre nom. Aucun logiciel de lecture ne le montre.
page_private_data tableau [] Les mêmes, laissées sur une page numérotée plutôt que sur le document.
page_regions tableau [] Rectangles nommés d’une page, qu’une requête ultérieure remplit par leur nom.
metadata objet — Titre, auteur, sujet, mots-clés, le logiciel qui l’a créé, producteur, dates de création et de modification, état de recouvrement, et schémas de votre cru.
information_dictionary booléen true Si le fichier garde sa table d’entrées à côté de son paquet de métadonnées, ou ne dit ce qu’il est que dans ce paquet.
text_as_shapes booléen false Tracer ou non chaque lettre comme une forme, pour que rien ne puisse être sélectionné ni copié sur les pages.
archive chaîne — La norme d’archivage dont le fichier se réclame : pdfa1b, pdfa1a, pdfa2b, pdfa2u, pdfa2a, pdfa3b, pdfa3u, pdfa3a, pdfa4 ou pdfa4f.
protection objet — Les mots de passe sous lesquels le document est verrouillé, et ce que le logiciel de lecture est prié d’autoriser une fois qu’il est ouvert.
invoice objet — Le XML de facture contenu dans le document, avec son profil, sa version, sa relation et sa date.
reading objet — Comment le logiciel de lecture est prié d’ouvrir le fichier : quel panneau, quelle disposition, quelle page, quel grossissement, et quoi envoyer à une imprimante.
base_uri chaîne — L’adresse à partir de laquelle un lien relatif est résolu.
version chaîne celle du moteur La version de PDF que le fichier déclare : de 1.4 à 1.7, ou 2.0.
extensions tableau [] Les extensions de PDF dont le fichier dit se servir, chacune sous son préfixe.
compression objet — Si les flux sont compressés, à quel niveau, et si les petits objets voyagent groupés.
first_page_first booléen false Si le fichier est écrit première page d’abord, pour que le logiciel de lecture montre la page 1 pendant que le reste arrive encore.
output_intent objet sRGB Le profil de couleur qui sert de référence pour interpréter les couleurs du fichier.
images tableau [] Ce qu’une image fournie dit d’elle-même, et la façon dont elle est lue : ses masques, ses échantillons transparents, son orientation et son profil.
color_spaces tableau [] Séparations, palettes indexées, Lab, gris et RVB calibrés, et espaces fondés sur un profil, chacun sous un nom qu’une couleur peut appeler.
shadings tableau [] Les dégradés axiaux et radiaux, chacun sous un nom qu’un remplissage peut appeler.
graphics_states tableau [] Des états nommés contenant les opacités, le mode de fusion, un masque, et ce que demande une presse : la surimpression, l’intention de rendu, la courbe de transfert et la trame.
layers tableau [] Des calques nommés que le logiciel de lecture peut afficher et masquer, et qui disent s’ils s’impriment.
drawings tableau [] Des dessins vectoriels nommés, c’est-à-dire ce qu’un bouton poussoir montre comme icône.
svg_drawings tableau [] Dessins lus dans des fichiers SVG, affichés par leur nom comme les dessins nommés.
transparency objet — L’espace de fusion dans lequel travaille le groupe de la page, et s’il est isolé ou en défonce.
page_units tableau — Le nombre de points que vaut une unité de page, pour une feuille plus grande que les 14 400 points dans lesquels un PDF se mesure.
page_origins tableau [] Où se place la feuille d’une page numérotée dans le dessin : le coin inférieur gauche d’où elle part.
page_review_marks tableau — Les formes qu’une page ajoute par-dessus ce qu’elle dessine : une note, un tampon, une forme tracée à la main.
page_triggers tableau — Ce qu’une page déclenche quand le logiciel de lecture y arrive, et quand il la quitte.
document_triggers objet — Ce que le document déclenche quand le logiciel de lecture s’apprête à le fermer, l’enregistrer ou l’imprimer, et une fois qu’il l’a enregistré ou imprimé.
scripts tableau [] Les scripts que le document enregistre sous un nom, qu’appellent ses champs et ses actions.
print chaîne — La norme d’impression que le document déclare, et pour laquelle il est refusé s’il l’enfreint.
variable_print chaîne — La norme d’impression variable déclarée par le document : un fichier qui regroupe un document par destinataire, refusé s’il enfreint la norme.
check tableau — Les normes contre lesquelles le document fini est mesuré, la réponse revenant à côté du fichier.
page_spaces tableau — Ce que veulent dire les nombres bruts d’une page, espace de couleur par espace de couleur, et comment ses marques se combinent.
page_separations tableau — À quelle plaque d’une feuille séparée correspond une page, et l’encre dans laquelle elle s’imprime.
page_output_intents tableau — L’appareil pour lequel les couleurs d’une page sont déclarées, quand la couverture et l’intérieur ne s’impriment pas sur le même papier.
layer_rules tableau — Un nom sur lequel des éléments sont dessinés et qui vaut pour plusieurs calques à la fois, avec la règle qu’un logiciel de lecture applique pour décider s’il les montre.
layer_configurations tableau — Les jeux nommés d’états de calques que le logiciel de lecture propose à côté de celui sous lequel le document s’ouvre.
layer_families tableau — Les calques dont le logiciel de lecture ne montre qu’un à la fois : en montrer un éteint les autres.
carried_facts tableau [] Des listes nommées de vos propres données, chacune accrochée à un passage d’encre par l’élément qui la nomme. Aucun logiciel de lecture ne les montre.

Les cent cinq pages de cette section

Une page par élément et par clé qu’une requête peut contenir, classée sous la question à laquelle elle répond. Chacune dit ce qu’est la chose, ce qu’elle fait techniquement, le schéma de la requête qu’elle accepte, et montre une requête entière qui l’utilise.

Ce qu’une requête crée

Vingt-cinq choses se posent sur une page, et chacune a ici sa page : ce qu’elle est, ce qu’elle fait techniquement, le schéma de la requête qu’elle prend, et une requête entière qui la montre.

Texte
Les tableaux
Images et pages importées
Les codes-barres et les codes carrés
Formes
Champs de formulaire
  • Un champ que le lecteur remplit text_field Ajouter un champ à remplir : un nom, une adresse, un commentaire sur plusieurs lignes, un mot de passe caché, ou un numéro à raison d’une case par chiffre.
  • Une case que le lecteur coche check_box Ajouter une case à cocher : accepter des conditions, choisir une option, avec la marque de votre choix et la valeur que le formulaire renvoie.
  • Une liste dans laquelle le lecteur choisit choice_field Proposez une liste de réponses : une liste toujours visible, un menu déroulant, ou un menu dans lequel le lecteur peut aussi taper sa propre réponse.
  • Plusieurs boutons, une seule réponse radio_group Mettre des boutons dont un seul reste choisi à la fois, chacun à sa place sur la page, tous rattachés à la même question.
  • L’emplacement réservé à une signature signature_field Réserver sur la page l’endroit où une signature électronique viendra se poser, avec son nom et son encadrement.
  • Un bouton sur lequel le lecteur appuie push_button Mettre un bouton qui agit au lieu de répondre : ouvrir une adresse, aller à une page, envoyer le formulaire ou le remettre à zéro.
Navigation

Ce qu’une requête règle

Quatre-vingts clés se trouvent au premier niveau d’une requête et règlent tout ce qui entoure le contenu du document : la feuille, les polices, l’identité du fichier, la façon dont un lecteur le parcourt, la couleur et le rendu lui-même.

La feuille, et ce qu’on pose dessous
Les polices
Le document dans son ensemble
S’y retrouver
La couleur et la façon dont elle est rendue
Ce qui est dessiné, et ce que cela donne

Les formes dont chaque clé est faite

Une poignée d’objets reviennent partout dans le format. Ils sont écrits une fois ici, et chaque page qui en emploie un le nomme avec ces mots.

Les objets dont les clés JSON sont faites
rect Quatre coordonnées — llx, lly, urx, ury. L’origine est en bas à gauche de la feuille et l’axe vertical monte, ce qui est la convention du format lui-même.
coordonnée Un nombre, ou une expression entre guillemets construite avec + - * / ( ) et les variables {page_width}, {page_height}, {current_page}, {total_pages}, {llx}, {lly}, {urx}, {ury}. Une expression s’imbrique jusqu’à cent niveaux, ce qui permet à un élément de se caler sur la largeur de la page sans que le client calcule quoi que ce soit.
color Un nombre pour un gris, trois pour le rouge, le vert et le bleu, quatre pour les quatre encres d’imprimerie, tous de 0 à 1. Sont aussi acceptés {"gray": n}, et {"space": "name", "components": …} pour un espace que la requête a déclaré.
stroke Une width, et facultativement une color, un motif dash avec sa phase, un cap et un join.
pages Les pages, numérotées à partir de un, sur lesquelles un élément est dessiné. La valeur par défaut, un tableau vide, le dessine sur toutes les pages, et c’est ainsi qu’un pied de page s’écrit une seule fois.
layer Le calque déclaré auquel un élément appartient, et que le logiciel de lecture allume et éteint.
id / relative_to Un élément se nomme lui-même avec id ; un autre se place contre le bord top ou bottom de celui-là avec un offset, si bien qu’un paragraphe suit un tableau dont personne ne connaissait la hauteur d’avance.
transform / rotate Six nombres pour une matrice, ou un nombre de degrés dans le sens inverse des aiguilles d’une montre autour du centre du rectangle. Un élément énonce l’un ou l’autre.

Compléter un PDF que vous envoyez

POST /update reçoit le même corps que POST /render : la description dans json_data et le PDF à compléter dans une partie qui lui est propre. Rien n’est créé à partir des éléments. La réponse est le fichier envoyé, chaque octet à sa place, suivi de ce qui a été ajouté : une signature qu’il contenait déjà couvre toujours ce qu’elle couvrait. L’en-tête x-hqf-pages donne le nombre de pages de ce fichier. Sur le service que nous exploitons, l’appel est décompté comme un document du mois, quel que soit ce nombre, comme un appel à POST /render.

Votre clé de signature ne quitte jamais vos machines : une signature se scelle donc en deux appels, et le serveur ne conserve rien entre les deux. Le premier, prepare_signature, vous rend le fichier avec le champ de signature préparé, /ByteRange écrit et /Contents encore à zéro. Votre propre logiciel signe les deux tronçons que /ByteRange désigne. Avec le second, place_signature, vous renvoyez ce fichier accompagné du bloc produit par votre logiciel ; le bloc est écrit dans la place qui lui était réservée, sans qu’aucun autre octet ne bouge.

  • source — chaîne, obligatoire. Le nom de la partie qui contient le PDF.
  • expansion_limit — entier, facultatif, un nombre d’octets, au plus 1 073 741 824. La taille maximale qu’un flux du PDF peut atteindre une fois décompressé. En son absence, c’est le plafond propre à la bibliothèque qui s’applique.
  • answers — tableau, facultatif, vide par défaut. Les champs à remplir, chacun décrit par un objet à deux chaînes : field, le nom sous lequel le formulaire désigne le champ, et value, la valeur que renverrait le formulaire rempli — pour un champ de saisie, le texte saisi ; pour une case à cocher ou un groupe de boutons radio, l’état à lui donner, ou Off pour le désélectionner ; pour une liste, la valeur que renvoie l’option choisie.
  • prepare_signature — objet, facultatif. field, une chaîne, obligatoire, est le champ de signature à préparer. reserved_bytes, un entier, obligatoire, de 1 à 1 048 576, est le nombre d’octets réservés au bloc. sub_filter vaut adbe_pkcs7_detached ou etsi_cades_detached, et digest_method l’une des valeurs sha256, sha384, sha512, sha3_256, sha3_384, sha3_512 ou shake256 ; en leur absence, les valeurs par défaut de la bibliothèque s’appliquent. name, reason, location et contact sont des chaînes que la signature déclare : qui a signé, pourquoi, où et comment joindre cette personne. signed_at est une date et heure au format ISO 8601. certifies, qui vaut no_changes, form_filling ou annotating, en fait une signature de certification, qui n’autorise ensuite que les modifications qu’il nomme ; en son absence, c’est une signature d’approbation.
  • place_signature — chaîne, facultative. Le nom de la partie qui contient le bloc à écrire dans la place qu’un fichier préparé a réservée. Il ne se combine avec aucune autre opération, puisque le bloc couvre le fichier jusqu’à son dernier octet ; answers et prepare_signature, eux, peuvent être demandés ensemble : les réponses sont alors écrites d’abord, pour que la signature les couvre.
  • Sont refusés avec le code 400 : une description qui ne demande aucune des trois opérations, ou qui combine place_signature avec une autre ; un nom de partie qui ne correspond à aucune partie envoyée ; une place réservée qui dépasse le plafond ; un champ que le formulaire ne contient pas, une réponse qu’il ne propose pas, une valeur donnée dans answers à un champ de signature ; un PDF chiffré ; pour place_signature, un PDF qui ne contient aucune place préparée ; un bloc plus grand que sa place ; un bloc qui n’est pas une structure CMS, ou dont l’empreinte ou la valeur de signature ne correspond pas aux octets du fichier qu’il couvre. Un fichier qui dépasse le plafond de pages est refusé avec le code 413. Remplir un formulaire ou préparer une signature exige une clé de licence : sans elle, un serveur d’évaluation répond 402.

Comment une requête est lue

  • Une clé que le serveur ne connaît pas est refusée nommément.
  • Une clé écrite deux fois dans le même objet est refusée, et le message nomme la clé.
  • Un choix qui n’a aucune valeur propre s’écrit en chaîne nue — "center", "pdfa4". Un choix qui en a une est un objet à une seule clé, qui nomme la variante — {"points": 12}, {"page": 3}.
  • Une clé facultative absente et un null explicite se lisent de la même façon, ce qui permet à un sérialiseur d’écrire l’une ou l’autre.
  • La même description, envoyée deux fois, rend deux fois les mêmes octets, sauf aux deux endroits où le schéma en décide autrement : un passage qui demande le moment du rendu lit l’horloge au moment où la page s’écrit, et un bloc protection qui ne déclare aucune key qui lui soit propre est verrouillé avec trente-deux octets aléatoires fournis par la machine. Partout ailleurs, l’identifiant du fichier est une empreinte de ce qui a été écrit : deux rendus se comparent donc comme deux fichiers.

Les chiffres auxquels le service se tient

Chaque chiffre, et ce qu’il plafonne
Le corps d’une requête, sur un serveur qui vous appartient 536 870 912 (512 Mio)
Le corps d’une requête adressée au service que nous faisons tourner 536 870 912 (512 Mio)
Combien de temps le service que nous faisons tourner attend un document 125 secondes
Profondeur d’imbrication d’une expression 100
Entrées d’une palette indexée 256
Niveau de compression 1 – 9
Correction d’erreur d’un code Aztec 0 – 90 %
Colonnes d’un code PDF417 1 – 30
Niveau de correction d’erreur d’un code PDF417 0 – 8
Polices en chaîne 2 ou plus
Remarques jointes à une réponse 10
Octets que ces remarques totalisent 1 000
Pages du modèle du milieu 1
Jusqu’où un flux d’un PDF fourni se déplie 1 073 741 824
Caractères du nom d’une police enregistrée 64
Pages d’un document 5 000

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 rendu, et seulement dans la mémoire de la machine. Ni l’une ni l’autre n’est écrite sur un disque, et les deux disparaissent au moment où les pages partent.

Deux choses sont écrites sur le disque, et deux seulement. La première, les polices. Si votre compte a le droit d’envoyer ses propres polices, alors une police que le rendu a réellement employée est gardée dans un dossier qui appartient à ce compte, pour que vous n’ayez jamais à l’envoyer une seconde fois — dès lors, votre description se contente de la nommer. Une police envoyée mais qui n’a servi nulle part n’est pas gardée, et un rendu qui a échoué ne garde rien du tout. Un compte qui se sert des polices déjà présentes sur le serveur ne garde rien non plus.

La seconde est une ligne émise quand le serveur tombe en panne de son propre fait, pour que quelqu’un ici soit réveillé. Elle indique le type de panne, le compte, le numéro que citait votre réponse et le moment, et rien de ce que votre description a choisi. Elle attend dans un petit fichier jusqu’à ce que ce site la récupère, et en sort dès que c’est fait.

Rien de ce qui touche à la facture ne vient du serveur. Ce site compte le rendu d’après la réponse qui lui revient et écrit sa propre ligne : le nom du compte, un identifiant qui désigne ce seul rendu, le moment où il a eu lieu, et le nombre de pages créées. Rien de ce qui est écrit sur ces pages n’y figure.

Le serveur tient un journal, comme tout programme sur une machine. Il écrit une ligne pour chaque document qui sort, qui donne le nom du compte, le nombre de pages sorties et le temps qu’il a fallu. Il en écrit une autre quand un rendu mentionne quelque chose qu’il n’a ensuite jamais employé — une police, une image, une couleur que rien n’a choisie — et qui donne 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 compte rendu s’active quand on donne au serveur une adresse où l’envoyer, et un serveur qui n’en a reçu aucune n’envoie rien nulle part.

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

Une adresse prend le travail, et la requête lui est envoyée sous forme de formulaire. Une partie de ce formulaire contient 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 requête complète qui fonctionne.

Qu’est-ce que cela apporte de plus qu’une bibliothèque PDF gratuite ?

Une grande quantité de documents s’écrit chaque jour avec des bibliothèques PDF gratuites, et plusieurs d’entre elles font très bien ce qu’elles se sont donné pour tâche. Ce qui se vend ici est autre chose : un seul ensemble qui couvre déjà tout le terrain, et quelqu’un qui en répond.

Le terrain est vaste. Du texte qui s’écoule, des tableaux qui se poursuivent sur autant de pages qu’il leur en faut, des images, des couleurs d’imprimerie, des codes-barres, des formulaires à remplir, des fichiers faits pour s’ouvrir encore dans des dizaines d’années, des fichiers faits pour être lus à voix haute à quelqu’un qui ne voit pas la page, et la place réservée à un sceau. Une seule chose à apprendre, une seule chose à tenir à jour, et une seule adresse où écrire quand une page ne sort pas comme vous l’attendiez.

La vérification vient de l’extérieur. Il existe un vérificateur gratuit qui s’appelle veraPDF, dont tout le métier est d’ouvrir un fichier et de dire s’il suit les règles publiées, et tout document d’archivage montré sur ce site passe par lui. Nous n’en possédons aucune part, et il ne sait rien de qui a écrit le fichier qu’il a devant lui.

Le même document est écrit de trois façons — un programme Rust, un programme Python, et une requête au serveur — puis les trois sont relancées et comparées. Là où elles donnent le même résultat à l’octet près, c’est noté à côté ; là où le résultat est le même à l’œil mais pas à l’octet, c’est noté 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 une fois pour toutes reste à vous : 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 seul programme à lancer sur vos propres machines, avec une poignée de réglages : où se trouvent ses polices, où se trouve sa clé de licence, et combien de pages un document peut compter au plus. Il écoute sur la machine elle-même et se place derrière le serveur frontal que vous faites déjà tourner, quel qu’il soit.

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. Chaque rendu est déclaré une fois, avec le nombre de pages qu’il a créées, et un mois de rendus s’additionne en une seule facture. Un document compte pour un, quel que soit le nombre de pages qui en sortent : le nombre de pages est consigné à côté du rendu et n’est jamais facturé.

Un rapport qui n’a pas pu partir tout de suite n’est pas perdu : il attend et part plus tard. Et un rapport qui arrive deux fois n’est compté qu’une fois, parce que chaque rendu a un identifiant à lui.

Quels langages de programmation peuvent l’appeler ?

Tous. La requête 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’usage courant.

La bibliothèque sous-jacente est écrite en Rust et s’appelle tout aussi bien depuis Python : c’est avec elle que travaille une équipe qui achète la bibliothèque seule.

Que fait la version gratuite ?

Elle crée des documents, et elle signe son travail. Chaque page qu’elle crée sort avec un filigrane, et chaque lettre de ces pages est tracée comme une forme au lieu d’être écrite comme du texte : les pages ont la bonne apparence, et on ne peut rien en extraire.

Quelques opérations demandent une clé de licence. Sollicitée pour l’une d’elles, une copie sans clé refuse, le dit clairement et nomme la clé de licence qui couvre l’opération : composer du texte dans l’une des quatorze polices que tout logiciel de lecture contient déjà, dans une police Type 1 ou avec des lettres que le programme dessine lui-même, et reprendre une page d’un autre document qui compte plus de dix mille mots à elle seule. Une copie sans clé ne compose du texte que dans une police qui lui fournit des glyphes à tracer : une police jointe à votre requête, ou une police que le service détient déjà.

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 vérificateur gratuit cité plus haut, et il les accepte. Il est maintenu par l’Open Preservation Foundation et la PDF Association, et nous n’avons de part ni dans l’une ni dans l’autre.

Un fichier destiné à une presse d’imprimerie doit satisfaire quatre exigences avant qu’un seul octet soit écrit, et un fichier auquel il en manque une est refusé plutôt qu’écrit. La page des normes d’impression nomme les quatre.

Comment savoir si le service répond ?

Il existe une seconde adresse dont le seul rôle est de le dire. Elle ne crée rien, ne coûte rien à interroger, et répond tant que le service fonctionne.

Compter vos documents ne retarde jamais un rendu. Les pages reviennent d’abord, et le comptage part de son côté ensuite.

Où aller ensuite

Tout ce que la bibliothèque met sur une page Tout ce que le service garde, en entier Ce que nous conservons à votre sujet, et pour combien de temps Des fichiers faits pour s’ouvrir encore dans des dizaines d’années Des fichiers qu’un imprimeur accepte sans poser de question

Voir les prix Voir les exemples