Formats de données

Vous trouverez ici la structure attendue pour vos données. PDFgine n’imprime pas la valeur envoyée telle quelle ; il applique le format déclaré par le modèle, dans la langue du document.

En une phrase : les données arrivent brutes, PDFgine les met en forme. Envoyez une valeur déjà formatée et le document sera correct dans une langue, incorrect dans l’autre.

Type de champ	Comment l’envoyer	Exemple d’entrée	Sortie
`date`	ISO 8601. YYYY-MM-DD pour une date seule, un horodatage complet lorsque l’heure compte. Ne convertissez pas vers un format local.	`"2026-09-06"`	`06/09/2026`
`number`	Un nombre JSON. Sans séparateur de milliers, espaces ni guillemets ; le séparateur décimal est un point.	`24000`	`24 000,00`
`currency`	Envoyez le montant sous forme de nombre brut. La devise ne doit pas y figurer ; elle est définie dans le format de la colonne sous forme de code ISO 4217.	`24000`	`24 000,00 USD`
`percent`	Un rapport sur cent, brut : envoyez 18 pour 18%. Le document ajoute le signe.	`18`	`18,00%`
`string`	Imprimé tel quel. N’envoyez pas une date, un montant ou un ratio sous forme de chaîne ; la mise en forme serait perdue.	`"Northwind Trading Ltd."`	`Northwind Trading Ltd.`
`boolean`	JSON true/false. C’est ce que lisent les blocs conditionnels.	`true`	Détermine la condition ; jamais imprimé comme texte

Un format est déclaré à trois endroits : le champ "format" d’une colonne de tableau et d’une ligne de synthèse, "dataRules.formatter" d’un élément imprimant une seule valeur, et les fonctions format_date et format_money dans un texte combinant plusieurs champs.

Données et modèle

{
  "issueDate": "2026-09-06",
  "currency": "USD",
  "lineItems": [
    { "name": "Site web d’entreprise", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// Côté modèle :
// colonne du tableau :   "format": { "kind": "currency", "currency": "USD", "decimals": 2 }
// colonne de date :    "format": { "kind": "date", "dateStyle": "short" }
// élément de texte :   "{{ referenceNo }} · {{ format_date issueDate }}"

Les IBAN, numéros de téléphone et numéros fiscaux arrivent également sous forme canonique : IBAN sans espaces, téléphone au format E.164 (+442071838750). Le regroupement relève de la présentation et ne doit pas figurer dans les données.

Le nom sous lequel le document est reçu

Un document téléchargé porte le nom "{document type} - {counterparty} - {reference no}". Les trois parties proviennent des données envoyées : document.title, customer et referenceNo. Les parties manquantes sont omises et, si aucune ne permet de produire un nom utilisable, le document utilise son identifiant, par exemple quote-doc_94812af2.pdf.

En-tête de réponse

Content-Disposition: attachment;
  filename="Quote - Müller og Søn ApS - QUO-2026-0042.pdf";
  filename*=UTF-8''Quote%20-%20M%C3%BCller%20og%20S%C3%B8n%20ApS%20-%20QUO-2026-0042.pdf

Le nom figure deux fois dans le même en-tête. Le champ étendu conserve la langue du document ; le champ classique contient une écriture ASCII lisible pour les clients qui ne lisent pas le champ étendu. Les caractères refusés par les systèmes de fichiers (barre oblique, barre oblique inverse, deux-points, astérisque, point d’interrogation, guillemets, inférieur à, supérieur à, barre verticale) ainsi que les caractères de contrôle sont supprimés, et la longueur du nom est limitée pour rester compatible avec tous les systèmes de fichiers.

Images

Une image du modèle peut être liée à un champ de données et recevoir sa source avec la requête. Deux formes sont acceptées : l’ID d’une ressource importée (ast_…, pour logos, tampons et signatures récurrents : un seul import, seul l’ID est transmis) et une image intégrée (data:image/png;base64,…, pour un usage ponctuel). Si le champ est absent ou vide, l’image du modèle est utilisée ; si sa valeur est inutilisable, la requête est refusée avec 422 et la réponse indique le champ.

Demande

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Limites : une image intégrée doit être PNG, JPEG ou WebP, avec au plus 2 MB par image et 6 MB pour toutes les images du document. Une ressource importée peut atteindre 10 MB. Pour les images temporaires, indiquez expiresInMinutes à l’importation (1 minute–7 jours) ; les ressources expirées sont supprimées automatiquement.

Ressources

Les logos, signatures et polices sont importés une seule fois et référencés par ID. Leur page décrit l’importation, les limites et les autorisations des polices.

Ressources →

Les problèmes les plus courants

Une valeur déjà formatée est imprimée telle quelle. "1.234,56" se lit correctement dans une langue et incorrectement dans une autre ; aucun formatage ne peut ensuite la corriger.
Une date doit respecter ISO 8601. Un format local arrive comme texte : il n’est ni formaté, ni trié, ni traduit.
La devise ne doit pas figurer dans le montant. Envoyez le nombre et laissez le format de colonne ajouter le code ISO.
Un ratio s’envoie sur cent : 18 pour 18%. Envoyer 0.18 imprime zéro virgule dix-huit pour cent.
Une condition lit un booléen JSON. La chaîne "false" est un texte non vide et compte comme présente.