L'API qui dessine vos documents

Le transport

Un seul point d'entrée, une seule méthode : un POST avec un corps multipart/form-data. La partie nommée json_data porte toute la description en JSON. Toute autre partie est un binaire nommé que la description désigne par le nom de cette partie — un PDF employé comme gabarit 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 vit le temps de l'appel où elle a voyagé.

L'authentification est une clé porteuse vérifiée par le proxy inverse, qui la résout en un nom de client et transmet ce nom dans un en-tête à lui. Un succès répond 200 avec application/pdf, plus le temps de lecture et le temps de dessin en millisecondes. Un refus répond un code de statut et une phrase en texte brut. Il n'y a pas d'enveloppe à ouvrir et pas de travail à surveiller.

Le modèle

Une requête est un document plat : une liste d'articles, et à côté les ressources que ces articles nomment. Polices, espaces de couleur, dégradés, états graphiques, calques et dessins sont chacun déclarés une fois sous un nom, et un article renvoie à ce nom. Rien n'est positionnel et rien n'est implicite — un nom qu'un article appelle et qu'aucune déclaration ne porte est refusé, le nom figurant dans le message.

Les pages sont créées par ce qu'on dessine dessus, elles ne sont pas déclarées d'avance. Un article dit sur quelles pages il se pose ; le 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 articles 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 article peut se nommer lui-même 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 porte à côté du dessin

La même requête énonce les métadonnées du document, la norme d'archivage qu'il revendique, l'intention de sortie contre laquelle ses couleurs sont lues, 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 qu'une visionneuse respecte, et le XML de facture que porte un document Factur-X. Un seul appel produit un fichier fini qui revendique ses normes : il n'y a pas de seconde passe ni d'outil de retouche.

Les modes d'échec, et ce qu'ils coûtent

La validation est complète et a lieu avant que rien ne soit dessiné : le serveur décline une requête plutôt que de produire 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.

Les clés inconnues sont ignorées, ce qui rend une requête écrite pour une version plus récente sans danger à envoyer à une plus ancienne. Une clé écrite deux fois dans le même objet est déclinée par son nom. Les combinaisons qui se contrediraient — une matrice avec une rotation, un lien portant à la fois une cible courte et une action complète, une cellule de tableau portant deux choses — sont déclinées par leur nom également.

La plus petite requête qui dessine quelque chose

Une police déclarée, un article, une ligne de texte. Enregistrez-le, envoyez-le, et un PDF d'une page 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
    }
  ]
}

Le même appel, écrit trois fois

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.

Depuis un terminal

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

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 réponse est le PDF lui-même, écrivez donc le corps directement dans un fichier. Les deux en-têtes de durée sont là chaque fois que le dessin a réussi.

import json
import pathlib
import requests

LETTERHEAD = pathlib.Path("letterhead.pdf")

description = {
    "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,
        }
    ],
}

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-render-ms"], "ms drawing")

Depuis JavaScript

Un corps de formulaire et l'appel réseau standard, si bien que les mêmes lignes tournent dans un navigateur et côté serveur. Un refus arrive sous forme d'une phrase en texte brut.

const description = {
  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,
    },
  ],
};

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

const answer = await fetch("https://your-server/render", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}` },
  body,
});
if (!answer.ok) {
  throw new Error(await answer.text());
}
const pdf = new Uint8Array(await answer.arrayBuffer());

Les clés d'une requête

Trente-trois clés se tiennent au premier niveau d'une requête, et une seule est obligatoire. Toute autre clé vaut par défaut la valeur de la colonne d'à côté, si bien qu'une requête énonce ce dont elle a besoin et rien d'autre.

Les vingt et une choses qu'un article peut être

Un article est un objet qui porte un type. Chaque type a une page à lui : ce que c'est, ce qu'un développeur doit en savoir, chaque clé qu'il accepte avec son défaut, et une requête entière qui le montre.

Texte

• Un bloc de texte posé sur la page text Écrire du texte dans un rectangle choisi, avec sa police, sa taille et sa couleur, et mettre en valeur un mot au milieu d'une phrase.
• Du texte en paragraphes, avec retraits et tabulations flow Poser plusieurs paragraphes dans un cadre, avec retrait de première ligne, espace entre eux, listes à puces et colonnes de chiffres alignées.
• Un tampon en travers de la page stamp Poser un mot en travers d'une zone, à la taille qui remplit la boîte : brouillon, payé, copie, annulé, en diagonale ou à plat.

Les tableaux

• Un tableau qui se poursuit de page en page table Des lignes et des colonnes qui coulent sur autant de pages qu'il faut, avec en-tête répété, filets, fonds de couleur et cellules fusionnées.

Images et pages importées

• Une image posée dans un rectangle image Placer dans un cadre choisi une photo ou un logo fourni avec la requête, étiré jusqu'aux bords ou gardé à ses propres proportions.
• Une page d'un PDF fourni, posée sur la page pdf_page Reprendre une page d'un PDF envoyé avec la requête et la poser dans un cadre, à ses proportions, au milieu des autres éléments.

Les codes-barres et les codes carrés

• Un code-barres à barres verticales barcode Dessiner un code-barres lisible par une douchette : Code 128 pour du texte, EAN-13, UPC-A et EAN-8 pour un article du commerce.
• Un code QR carré, lisible au téléphone qr Dessiner un code QR qui porte une adresse web ou un texte, lu par n'importe quel téléphone, avec sa marge blanche tout autour.
• Un code Aztec, sans marge blanche autour aztec Dessiner un code Aztec, celui des billets de train : carré, sans marge autour, avec la part de sécurité que vous choisissez.
• Un code Data Matrix, très petit et très solide data_matrix Dessiner un code Data Matrix, celui des colis et des petites pièces : autant de contenu qu'un code QR dans beaucoup moins de place.
• Un code PDF417, qui porte tout un formulaire pdf417 Dessiner un code PDF417 en barres empilées, celui des cartes d'embarquement : il porte un formulaire entier, pas seulement un numéro.

Formes

• Un tracé libre : lignes, courbes et surfaces path Dessiner une forme point par point, avec des segments droits et des courbes, remplie d'une couleur ou d'un dégradé, et cernée d'un trait.
• Un rectangle plein ou encadré rect Poser un rectangle : un fond de couleur derrière un titre, un cadre autour d'une zone, ou les deux, avec le trait de votre choix.
• Une ligne droite entre deux points line Tirer un trait d'un point à un autre, à l'épaisseur, à la couleur et au pointillé voulus : filet de séparation, soulignement, réglure.

Champs de formulaire

• Une case dans laquelle le lecteur écrit text_field Ajouter une case à remplir : nom, adresse, commentaire sur plusieurs lignes, mot de passe masqué, ou numéro case par case.
• 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 rapportée voulue.
• Une liste dans laquelle le lecteur choisit choice_field Offrir une liste de réponses : liste déroulée, menu qui s'ouvre, ou menu dans lequel le lecteur tape aussi sa propre réponse.
• Plusieurs boutons, une seule réponse radio_group Poser 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 Poser un bouton qui agit au lieu de répondre : ouvrir une adresse, aller à une page, envoyer le formulaire ou le remettre à zéro.

Navigation

• Une zone de la page sur laquelle on clique link Rendre un morceau de page cliquable : il ouvre une adresse web, ou emmène le lecteur à une autre page du même document.

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.

Comment une requête est lue

• Une clé que le serveur ne connaît pas est ignorée, si bien qu'une requête écrite pour une version plus récente se dessine sur une plus ancienne.
• Une clé écrite deux fois dans le même objet est refusée, et le message nomme la clé.
• Un choix sans charge s'écrit en chaîne nue — "center", "pdfa4". Un choix qui porte une charge est un objet à une seule clé, qui nomme la variante — {"points": 12}, {"page": 3}.
• Une clé facultative absente et une clé explicitement à null se lisent de la même façon, ce qui laisse un sérialiseur écrire l'une ou l'autre.
• La même description, envoyée deux fois, rend deux fois les mêmes octets : l'identifiant du fichier est une empreinte de ce qui a été écrit, si bien que deux exécutions se comparent comme des fichiers.

Les chiffres auxquels le service se tient