Aller au contenu

Créer un PDF : génération synchrone par API

Générez un PDF à partir d’un template en un seul appel synchrone. La requête attend la fin du rendu, puis renvoie une URL signée ou directement les octets du PDF.

POST https://api.templatefox.com/v1/pdf/create

Authentification : clé API dans l’en-tête x-api-key. Crédits : 1 crédit par génération réussie (remboursé automatiquement si le rendu échoue).

Pour les gros documents, les traitements par lots ou les flux pilotés par webhook, l’endpoint create-pdf-async prend le relais.

Seuls deux champs du corps de la requête sont obligatoires :

Champ Type Description
template_id string L’identifiant de 12 caractères de votre template (à copier depuis la liste des templates du tableau de bord).
data object Les paires clé-valeur à injecter dans le template. Les clés doivent correspondre aux variables {{variable}} de votre design.
curl -X POST https://api.templatefox.com/v1/pdf/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": {
    "customer_name": "John Doe",
    "invoice_number": "INV-001",
    "amount": "$1,234.56"
  }
}'

Ou passez par l’un de nos SDK officiels : TypeScript, Python, Go, PHP, Ruby, Java, C#.

Champ Type Obligatoire Défaut Description
template_id string ✅ — Identifiant court du template, 12 caractères.
data object ✅ — Les données clé-valeur injectées dans le template. Voir Liaison de données.
export_type string — "url" "url" dépose le PDF sur notre CDN et renvoie une URL signée. "binary" renvoie directement les octets du PDF, en application/pdf.
expiration integer — 86400 Durée de validité de l’URL, en secondes. Minimum 60, maximum 604800 (7 jours). S’applique uniquement avec export_type="url".
filename string — "document" Nom de fichier personnalisé (sans l’extension .pdf). Lettres, chiffres, _, - et . uniquement. 100 caractères maximum.
store_s3 boolean — false Envoie le fichier dans votre bucket S3 configuré plutôt que sur notre CDN. Nécessite une intégration S3.
s3_filepath string — — Préfixe de chemin dans votre bucket S3. Remplace default_prefix. 500 caractères maximum.
s3_bucket string — — Remplace le nom de bucket de votre intégration S3 (3 à 63 caractères, en minuscules).
pdf_variant string — — Génère un PDF conforme à une norme. Valeurs : "pdf/a-1b", "pdf/a-2b", "pdf/a-3b". Voir Normes PDF.
version string — — Tag de version du template (par exemple "prod") ou numéro de version (par exemple "3"). Sans version, le brouillon en cours est utilisé. 50 caractères maximum.

Renvoie un objet JSON avec une URL signée vers le PDF généré.

{
"url": "https://cdn.templatefox.com/generated/abc123/invoice.pdf",
"filename": "invoice-001.pdf",
"credits_remaining": 99,
"expires_in": 86400
}
Champ Type Description
url string URL signée pour télécharger le PDF (expire au bout de expires_in secondes).
filename string Nom de fichier final du PDF généré.
credits_remaining number Crédits restants sur le solde de votre équipe après cet appel.
expires_in number Nombre de secondes avant l’expiration de l’URL signée.

Renvoie le fichier PDF brut, en application/pdf. Pratique pour transmettre le fichier directement à un utilisateur ou le stocker vous-même. expiration, filename et les options S3 sont ignorés.

En-têtes de la réponse :

Content-Type: application/pdf
Content-Disposition: attachment; filename="HMQywVpZxqAM.pdf"
X-Credits-Remaining: 99

Quand l’envoi vers S3 est demandé, la réponse indique où le fichier a été déposé dans votre bucket, au lieu de renvoyer une URL :

{
"s3_bucket": "my-pdf-bucket",
"s3_key": "invoices/2026/01/invoice-001.pdf",
"filename": "invoice-001.pdf",
"credits_remaining": 99
}

Exemple :

curl -X POST https://api.templatefox.com/v1/pdf/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": { "customer_name": "John Doe" },
  "store_s3": true,
  "filename": "invoice-001",
  "s3_filepath": "2026/01/"
}'

Renseignez pdf_variant pour produire un PDF qui passe les contrôles de conformité PDF/A : facturation électronique (Factur-X, ZUGFeRD), archivage, secteurs réglementés.

curl -X POST https://api.templatefox.com/v1/pdf/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": { "customer_name": "John Doe" },
  "pdf_variant": "pdf/a-3b"
}'

Avec export_type à "binary", vous recevez directement les octets du PDF : pratique pour les transmettre à l’utilisateur ou les enregistrer sur disque, sans passer par le CDN.

curl -X POST https://api.templatefox.com/v1/pdf/create \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--output invoice.pdf \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": { "customer_name": "John Doe" },
  "export_type": "binary"
}'
Statut Quand
400 Le template est un template image : utilisez create-image.
401 Clé API absente ou invalide.
402 Le solde de crédits de votre équipe est à 0.
403 Le template n’existe pas ou n’appartient pas à votre équipe.
404 La version demandée n’existe pas.
422 Un paramètre est manquant ou invalide.
429 Limite de requêtes atteinte (voir les en-têtes de la réponse).
500 Erreur serveur. Si le rendu lui-même échoue, le crédit est remboursé automatiquement.

La liste complète est dans la vue d’ensemble de la référence API.