Créer un PDF en asynchrone, avec webhooks

Mettez un PDF en file d’attente et récupérez le résultat plus tard : en interrogeant l’endpoint de la tâche, ou par une notification webhook. Adapté aux gros documents, aux lots, et à tout flux qui ne doit pas garder une connexion HTTP ouverte jusqu’à la fin du rendu.

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

Authentification : clé API dans l’en-tête x-api-key. Crédits : 1 crédit débité à la mise en file de la tâche (remboursé si la tâche échoue définitivement).

Pour une génération immédiate, utilisez create-pdf.

Fonctionnement

1. Vous appelez POST /v1/pdf/create-async avec votre template_id et vos data : vous recevez aussitôt un job_id.
2. La tâche passe par pending → processing → completed ou failed.
3. Le résultat vous parvient de deux façons (ou des deux) :
   • Interrogation — appelez GET /v1/pdf/jobs/{job_id} jusqu’à ce que status vaille completed ou failed.
   • Webhook — passez une webhook_url dans la requête : nous y envoyons un POST quand la tâche se termine.

Les deux modes fonctionnent en même temps. Le webhook est facultatif.

Lancer une tâche

Champs obligatoires

Champ	Type	Description
template_id	string	L’identifiant du template, 12 caractères.
data	object	Les paires clé-valeur correspondant aux variables du template.

curl TypeScript Python Go PHP Ruby Java C#

Copier

curl -X POST https://api.templatefox.com/v1/pdf/create-async \
-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"
  },
  "webhook_url": "https://example.com/webhooks/pdf"
}'

const response = await fetch("https://api.templatefox.com/v1/pdf/create-async", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  data: {
    customer_name: "John Doe",
    invoice_number: "INV-001",
  },
  webhook_url: "https://example.com/webhooks/pdf",
}),
});

const { job_id } = await response.json();

import requests

response = requests.post(
  "https://api.templatefox.com/v1/pdf/create-async",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "data": {
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
      },
      "webhook_url": "https://example.com/webhooks/pdf",
  },
)

print(response.json()["job_id"])

payload, _ := json.Marshal(map[string]any{
  "template_id": "HMQywVpZxqAM",
  "data": map[string]string{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
  },
  "webhook_url": "https://example.com/webhooks/pdf",
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/pdf/create-async", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

<?php
$ch = curl_init('https://api.templatefox.com/v1/pdf/create-async');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
      'x-api-key: YOUR_API_KEY',
      'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'template_id' => 'HMQywVpZxqAM',
      'data' => [
          'customer_name'  => 'John Doe',
          'invoice_number' => 'INV-001',
      ],
      'webhook_url' => 'https://example.com/webhooks/pdf',
  ]),
]);

$response = json_decode(curl_exec($ch), true);
echo $response['job_id'];

require 'net/http'
require 'json'

uri = URI('https://api.templatefox.com/v1/pdf/create-async')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, {
'x-api-key'    => 'YOUR_API_KEY',
'Content-Type' => 'application/json'
})
request.body = {
template_id: 'HMQywVpZxqAM',
data: {
  customer_name: 'John Doe',
  invoice_number: 'INV-001'
},
webhook_url: 'https://example.com/webhooks/pdf'
}.to_json

response = JSON.parse(http.request(request).body)
puts response['job_id']

var body = """
{
"template_id": "HMQywVpZxqAM",
"data": {
  "customer_name": "John Doe",
  "invoice_number": "INV-001"
},
"webhook_url": "https://example.com/webhooks/pdf"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/create-async"))
  .header("x-api-key", "YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
  "https://api.templatefox.com/v1/pdf/create-async",
  new {
      template_id = "HMQywVpZxqAM",
      data = new {
          customer_name = "John Doe",
          invoice_number = "INV-001"
      },
      webhook_url = "https://example.com/webhooks/pdf"
  }
);

Console.WriteLine(await response.Content.ReadAsStringAsync());

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

Tous les paramètres

Champ	Type	Obligatoire	Défaut	Description
template_id	string	✅	—	Identifiant du template, 12 caractères.
data	object	✅	—	Les données clé-valeur injectées dans le template.
export_type	string	—	"url"	En asynchrone, seule la valeur "url" est prise en charge pour l’instant. Pour une réponse binaire, utilisez create-pdf.
expiration	integer	—	86400	Durée de validité de l’URL signée, en secondes (60 à 604800).
filename	string	—	"document"	Nom de fichier personnalisé (sans extension).
store_s3	boolean	—	false	Envoie le fichier dans votre bucket S3 configuré plutôt que sur notre CDN.
s3_filepath	string	—	—	Préfixe de chemin dans votre bucket S3.
s3_bucket	string	—	—	Remplace le nom de bucket de votre intégration S3.
webhook_url	string	—	—	URL publique notifiée à la fin de la tâche, en cas de succès comme d’échec. Les adresses privées ou locales sont refusées.
webhook_secret	string	—	—	Secret (16 à 256 caractères) qui sert à signer le contenu des webhooks en HMAC-SHA256.
pdf_variant	string	—	—	"pdf/a-1b", "pdf/a-2b" ou "pdf/a-3b", pour un PDF conforme aux normes d’archivage.
version	string	—	—	Tag ou numéro de version du template.

Exemple : webhook signé et envoi vers S3

Une requête asynchrone complète : webhook signé en HMAC, envoi vers S3, nom de fichier personnalisé, conformité PDF/A.

curl TypeScript Python Go

Copier

curl -X POST https://api.templatefox.com/v1/pdf/create-async \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": { "invoice_number": "INV-001" },
  "filename": "invoice-001",
  "store_s3": true,
  "s3_filepath": "invoices/2026/04/",
  "pdf_variant": "pdf/a-2b",
  "webhook_url": "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2"
}'

await fetch("https://api.templatefox.com/v1/pdf/create-async", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  data: { invoice_number: "INV-001" },
  filename: "invoice-001",             // no extension, .pdf appended
  store_s3: true,                      // upload to your S3 bucket
  s3_filepath: "invoices/2026/04/",    // key prefix
  pdf_variant: "pdf/a-2b",             // archival compliance
  webhook_url: "https://example.com/webhooks/pdf",
  webhook_secret: "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
}),
});

import requests

requests.post(
  "https://api.templatefox.com/v1/pdf/create-async",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "data": {"invoice_number": "INV-001"},
      "filename": "invoice-001",             # no extension
      "store_s3": True,                      # upload to your S3 bucket
      "s3_filepath": "invoices/2026/04/",    # key prefix
      "pdf_variant": "pdf/a-2b",             # archival compliance
      "webhook_url": "https://example.com/webhooks/pdf",
      "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
  },
)

payload, _ := json.Marshal(map[string]any{
  "template_id":    "HMQywVpZxqAM",
  "data":           map[string]string{"invoice_number": "INV-001"},
  "filename":       "invoice-001",
  "store_s3":       true,
  "s3_filepath":    "invoices/2026/04/",
  "pdf_variant":    "pdf/a-2b",
  "webhook_url":    "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/pdf/create-async", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

Quand la tâche se termine, le contenu du webhook porte result.s3_bucket et result.s3_key à la place de result.url, et chaque requête porte un en-tête X-TemplateFox-Signature : voir Vérifier la signature.

Réponse

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "credits_remaining": 99
}

Champ	Type	Description
job_id	string	UUID à interroger, ou à rapprocher des notifications webhook.
status	string	Toujours "pending" à la création.
credits_remaining	number	Crédits restants après le débit.

Suivre l’état d’une tâche

GET /v1/pdf/jobs/{job_id}

Renvoie l’état actuel d’une tâche.

curl TypeScript Python Go PHP Ruby Java C#

Copier

curl https://api.templatefox.com/v1/pdf/jobs/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: YOUR_API_KEY"

const jobId = "550e8400-e29b-41d4-a716-446655440000";

let job;
while (true) {
const r = await fetch(`https://api.templatefox.com/v1/pdf/jobs/${jobId}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
job = await r.json();
if (job.status === "completed" || job.status === "failed") break;
await new Promise((res) => setTimeout(res, 2000));
}

console.log(job.result_url);

import time
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"

while True:
  r = requests.get(
      f"https://api.templatefox.com/v1/pdf/jobs/{job_id}",
      headers={"x-api-key": "YOUR_API_KEY"},
  ).json()
  if r["status"] in ("completed", "failed"):
      break
  time.sleep(2)

print(r.get("result_url"))

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
  "time"
)

func main() {
  jobID := "550e8400-e29b-41d4-a716-446655440000"
  url := "https://api.templatefox.com/v1/pdf/jobs/" + jobID

  var job map[string]any
  for {
      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("x-api-key", "YOUR_API_KEY")
      resp, _ := http.DefaultClient.Do(req)
      json.NewDecoder(resp.Body).Decode(&job)
      resp.Body.Close()

      status := job["status"].(string)
      if status == "completed" || status == "failed" {
          break
      }
      time.Sleep(2 * time.Second)
  }

  fmt.Println(job["result_url"])
}

<?php
$jobId = '550e8400-e29b-41d4-a716-446655440000';
$url = "https://api.templatefox.com/v1/pdf/jobs/{$jobId}";

while (true) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
  ]);
  $job = json_decode(curl_exec($ch), true);
  curl_close($ch);

  if (in_array($job['status'], ['completed', 'failed'])) break;
  sleep(2);
}

echo $job['result_url'] ?? '';

require 'net/http'
require 'json'

job_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.templatefox.com/v1/pdf/jobs/#{job_id}")

job = nil
loop do
req = Net::HTTP::Get.new(uri, { 'x-api-key' => 'YOUR_API_KEY' })
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
job = JSON.parse(http.request(req).body)
break if %w[completed failed].include?(job['status'])
sleep 2
end

puts job['result_url']

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var jobId = "550e8400-e29b-41d4-a716-446655440000";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/jobs/" + jobId))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

String body;
while (true) {
  body = client.send(request, HttpResponse.BodyHandlers.ofString()).body();
  if (body.contains("\"completed\"") || body.contains("\"failed\"")) break;
  Thread.sleep(2000);
}

System.out.println(body);

using System.Net.Http;
using System.Text.Json;

var jobId = "550e8400-e29b-41d4-a716-446655440000";
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

JsonElement job;
while (true)
{
  var body = await client.GetStringAsync(
      $"https://api.templatefox.com/v1/pdf/jobs/{jobId}"
  );
  job = JsonDocument.Parse(body).RootElement;
  var status = job.GetProperty("status").GetString();
  if (status == "completed" || status == "failed") break;
  await Task.Delay(2000);
}

Console.WriteLine(job.GetProperty("result_url").GetString());

Valeurs de statut

Statut	Description
pending	En file d’attente, pas encore pris en charge.
processing	Le PDF est en cours de rendu.
completed	Le PDF est prêt : voir result_url, ou result_s3_bucket / result_s3_key.
failed	La tâche a échoué : voir error_message et error_code. Le crédit est remboursé.

Réponse

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "template_id": "HMQywVpZxqAM",
  "export_type": "url",
  "filename": "invoice-001",
  "store_s3": false,
  "created_at": "2026-04-24T12:00:00Z",
  "updated_at": "2026-04-24T12:00:05Z",
  "completed_at": "2026-04-24T12:00:05Z",
  "result_url": "https://cdn.templatefox.com/generated/abc123/invoice-001.pdf",
  "result_filename": "invoice-001.pdf",
  "result_expires_at": "2026-04-25T12:00:05Z",
  "result_s3_bucket": null,
  "result_s3_key": null,
  "error_message": null,
  "error_code": null
}

Rythme d’interrogation

• Toutes les 1 à 2 secondes pour les petits documents.
• Toutes les 5 à 10 secondes pour les gros documents ou les lots.
• Avec des délais croissants (attente exponentielle) quand beaucoup de tâches tournent en même temps.
• Un webhook évite ces appels répétés.

Webhooks

Si vous fournissez une webhook_url, nous y envoyons un POST dès que la tâche se termine : plus besoin d’interroger l’API.

En-têtes

En-tête	Valeur
Content-Type	application/json
User-Agent	TemplateFox-Webhook/1.0
X-TemplateFox-Event	pdf.completed ou pdf.failed
X-TemplateFox-Timestamp	Horodatage Unix, en secondes
X-TemplateFox-Signature	sha256=<hex>, uniquement si webhook_secret est défini

Contenu en cas de succès

{
  "event": "pdf.completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "url": "https://cdn.templatefox.com/generated/abc123/invoice-001.pdf",
    "filename": "invoice-001.pdf"
  }
}

Pour un envoi vers S3, l’objet result contient s3_bucket et s3_key à la place de url.

Contenu en cas d’échec

{
  "event": "pdf.failed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": {
    "message": "Template rendering failed",
    "code": "GENERATION_ERROR"
  }
}

error.code vaut GENERATION_ERROR (échec du rendu), UPLOAD_ERROR (échec de l’envoi du fichier) ou UNKNOWN_ERROR ; error.message décrit l’erreur. Les mêmes valeurs se retrouvent dans error_code et error_message quand vous interrogez la tâche.

Vérifier la signature

Quand un webhook_secret est défini, chaque webhook est signé en HMAC-SHA256 :

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)

Comparez le résultat à la valeur de X-TemplateFox-Signature, après le préfixe sha256=. Calculez la signature sur le corps brut de la requête, avant tout parsing JSON : la moindre resérialisation la rend invalide.

Python TypeScript

Copier

import hmac
import hashlib

def verify_signature(secret: str, timestamp: str, raw_body: bytes, signature_header: str) -> bool:
  if not signature_header.startswith("sha256="):
      return False
  received = signature_header.removeprefix("sha256=")
  expected = hmac.new(
      secret.encode("utf-8"),
      f"{timestamp}.{raw_body.decode('utf-8')}".encode("utf-8"),
      hashlib.sha256,
  ).hexdigest()
  return hmac.compare_digest(received, expected)

import crypto from "node:crypto";

export function verifySignature(
secret: string,
timestamp: string,
rawBody: string,
signatureHeader: string,
): boolean {
if (!signatureHeader.startsWith("sha256=")) return false;
const received = signatureHeader.slice("sha256=".length);
const expected = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const a = Buffer.from(received, "hex");
const b = Buffer.from(expected, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Nouvelles tentatives

Une livraison de webhook est tentée 3 fois au plus, avec 1 seconde puis 5 secondes d’attente entre les tentatives :

• Nouvelle tentative si le délai expire, si la connexion échoue ou si votre endpoint répond en 5xx.
• Pas de nouvelle tentative sur une réponse 4xx (votre endpoint a refusé la requête).

Répondez avec un code 2xx pour accuser réception. Sans réponse au bout de 30 secondes, la tentative compte comme un échec.

Lister les tâches

GET /v1/pdf/jobs

Liste les tâches de votre équipe, avec pagination et filtre par statut.

Paramètre de requête	Type	Défaut	Description
limit	integer	20	Taille de la page (100 au maximum).
offset	integer	0	Nombre de résultats à sauter.
status	string	—	Filtre par statut : pending, processing, completed ou failed.

curl TypeScript Python Go PHP Ruby Java C#

Copier

curl "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50" \
-H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({ status: "failed", limit: "50" });
const res = await fetch(
`https://api.templatefox.com/v1/pdf/jobs?${params}`,
{ headers: { "x-api-key": "YOUR_API_KEY" } },
);
const { jobs, total } = await res.json();

import requests

res = requests.get(
  "https://api.templatefox.com/v1/pdf/jobs",
  headers={"x-api-key": "YOUR_API_KEY"},
  params={"status": "failed", "limit": 50},
).json()

print(res["total"], len(res["jobs"]))

req, _ := http.NewRequest("GET",
  "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct {
  Jobs  []map[string]any `json:"jobs"`
  Total int              `json:"total"`
}
json.NewDecoder(resp.Body).Decode(&result)

<?php
$ch = curl_init('https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
]);

$result = json_decode(curl_exec($ch), true);
echo "Total: {$result['total']}";

require 'net/http'
require 'json'

uri = URI('https://api.templatefox.com/v1/pdf/jobs')
uri.query = URI.encode_www_form(status: 'failed', limit: 50)

req = Net::HTTP::Get.new(uri, { 'x-api-key' => 'YOUR_API_KEY' })
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

result = JSON.parse(http.request(req).body)
puts result['total']

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50"))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var body = await client.GetStringAsync(
  "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50"
);
Console.WriteLine(body);

Réponse

{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed",
      "template_id": "HMQywVpZxqAM",
      "export_type": "url",
      "created_at": "2026-04-24T12:00:00Z",
      "error_message": "Template rendering failed",
      "error_code": "GENERATION_ERROR"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Synchrone ou asynchrone

create-pdf (synchrone)	create-pdf-async
Documents courts, données simples	Gros documents ou rendus lourds
Échange requête-réponse interactif	Lots ou traitements en arrière-plan
Octets du PDF reçus directement	Notification par webhook
Faible volume, un PDF par requête	Gros volume, générations en parallèle