Référence de l'API REST TemplateFox

Référence complète de l’API REST TemplateFox.

URL de base

https://api.templatefox.com

Authentification

Chaque requête doit porter une clé API dans l’en-tête x-api-key.

x-api-key: YOUR_API_KEY

Créez une clé API dans la section des clés API de votre tableau de bord. Les clés commencent par sk_.

Documentation interactive

• Documentation Swagger — explorateur interactif de l’API
• Collection Postman — forkez-la et testez tous les endpoints

---

Endpoints principaux

POST

/v1/pdf/create

Génération de PDF synchrone. Renvoie immédiatement une URL signée (ou les octets du fichier).

POST

/v1/pdf/create-async

Met une tâche en file d’attente ; le résultat arrive par interrogation ou par webhook. Adapté aux gros documents, aux lots et aux rendus longs.

---

Autres endpoints

GET /v1/templates

Liste tous les templates de votre équipe. Pratique pour les intégrations no-code (Zapier, Make, n8n).

Aucun crédit consommé.

curl https://api.templatefox.com/v1/templates \
  -H "x-api-key: YOUR_API_KEY"

Réponse

{
  "templates": [
    {
      "id": "HMQywVpZxqAM",
      "name": "Invoice Template",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:45:00Z"
    }
  ]
}

---

GET /v1/templates/{template_id}/fields

Renvoie les champs dynamiques (variables) déclarés dans un template. Pratique pour construire des formulaires dynamiques dans les intégrations.

Aucun crédit consommé.

curl https://api.templatefox.com/v1/templates/HMQywVpZxqAM/fields \
  -H "x-api-key: YOUR_API_KEY"

Réponse

[
  {
    "key": "customer_name",
    "label": "Customer Name",
    "type": "string",
    "required": false,
    "helpText": "Example: John Doe"
  },
  {
    "key": "items",
    "label": "Items",
    "type": "array",
    "required": false,
    "helpText": "Array of items with fields: name, price",
    "spec": [
      { "name": "name", "label": "Name", "type": "text" },
      { "name": "price", "label": "Price", "type": "number" }
    ]
  }
]

Champ	Type	Description
key	string	Identifiant du champ, à utiliser dans l’objet data
label	string	Libellé lisible, déduit de la clé (customer_name → Customer Name)
type	string	Type du champ : string, integer, number, boolean, array
required	boolean	Indique si le champ est obligatoire
helpText	string	Texte d’aide avec un exemple de valeur (absent quand aucun exemple n’est connu)
spec	array	Champs de type array uniquement : la structure de chaque élément (name, label, type)

---

GET /v1/account

Informations du compte, dont les crédits restants.

Aucun crédit consommé.

curl https://api.templatefox.com/v1/account \
  -H "x-api-key: YOUR_API_KEY"

Réponse

{
  "credits": 142,
  "email": "user@example.com"
}

---

GET /v1/account/transactions

Historique des transactions, paginé.

Aucun crédit consommé.

Paramètre	Type	Défaut	Description
limit	number	300	Nombre d’enregistrements renvoyés (1 à 1000)
offset	number	0	Nombre d’enregistrements à sauter

curl "https://api.templatefox.com/v1/account/transactions?limit=10&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

Réponse

{
  "transactions": [
    {
      "transaction_ref": "550e8400-e29b-41d4-a716-446655440000",
      "transaction_type": "PDFGEN",
      "template_id": "HMQywVpZxqAM",
      "exec_tm": 1250,
      "credits": 1,
      "created_at": "2026-01-20T14:30:00Z"
    }
  ],
  "total": 45,
  "limit": 10,
  "offset": 0
}

Type de transaction	Description
PDFGEN	Génération d’un PDF ou d’une image, ou appel d’un outil PDF (crédits consommés)
PURCHASE	Achat de crédits (crédits ajoutés)
REFUND	Remboursement d’un crédit après un échec de génération
BONUS	Crédits offerts

Un credits positif correspond à des crédits consommés, un credits négatif à des crédits ajoutés.

---

Outils PDF

Des endpoints pour manipuler directement des PDF, sans template. Chaque appel coûte 1 crédit et accepte le fichier d’entrée sous forme d’URL HTTPS (pdf_url) ou de chaîne base64 (pdf_base64).

Les trois renvoient la même réponse que POST /v1/pdf/create : URL, nom de fichier, crédits restants, expiration.

POST /v1/pdf-tools/merge

Assemble au moins 2 PDF, dans l’ordre fourni.

curl -X POST https://api.templatefox.com/v1/pdf-tools/merge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdfs": [
      { "pdf_url": "https://example.com/cover.pdf" },
      { "pdf_url": "https://example.com/report.pdf" },
      { "pdf_url": "https://example.com/appendix.pdf" }
    ],
    "filename": "merged-report"
  }'

Champ	Type	Obligatoire	Description
pdfs	array	Oui	Liste ordonnée (2 au minimum). Chaque entrée contient pdf_url ou pdf_base64.
filename	string	Non	Nom de fichier personnalisé, sans .pdf.
expiration	integer	Non	Durée de validité de l’URL signée, en secondes (60 à 604800, 86400 par défaut).
export_type	string	Non	url (par défaut) ou binary (renvoie les octets bruts).

---

POST /v1/pdf-tools/extract-pages

Renvoie un seul PDF qui ne contient que les pages choisies du fichier d’entrée, dans l’ordre indiqué. De quoi découper, réordonner ou sélectionner des pages.

curl -X POST https://api.templatefox.com/v1/pdf-tools/extract-pages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/report.pdf",
    "pages": "1-3, 5, 7-9"
  }'

Champ	Type	Obligatoire	Description
pdf_url ou pdf_base64	string	Oui	PDF source (un seul des deux).
pages	string	Oui	Pages à garder, numérotées à partir de 1. Plages et pages isolées acceptées, par exemple 1-3, 5, 7-9. L’ordre est respecté (5,1,3 renvoie ces 3 pages dans cet ordre).
filename, expiration, export_type	—	Non	Comme pour merge.

---

POST /v1/pdf-tools/rotate

Fait pivoter toutes les pages d’un même angle (rotation) ou applique un angle par page (page_rotations). Angles acceptés : 0, 90, 180, 270. La rotation s’ajoute à celle que la page a déjà.

# Rotate every page 90°
curl -X POST https://api.templatefox.com/v1/pdf-tools/rotate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/scan.pdf",
    "rotation": 90
  }'

# Rotate page 1 by 90° and page 3 by 180°
curl -X POST https://api.templatefox.com/v1/pdf-tools/rotate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_url": "https://example.com/scan.pdf",
    "page_rotations": { "1": 90, "3": 180 }
  }'

Champ	Type	Obligatoire	Description
pdf_url ou pdf_base64	string	Oui	PDF source (un seul des deux).
rotation ou page_rotations	int / object	Oui	Un seul des deux. rotation s’applique à tout le document ; page_rotations associe un angle à chaque page : { "<page>": <degrés> }.
filename, expiration, export_type	—	Non	Comme pour merge.

---

Tâches asynchrones

Les endpoints de suivi des tâches lancées par POST /v1/pdf/create-async.

GET /v1/pdf/jobs

Liste les tâches de génération de PDF asynchrones de votre équipe.

Aucun crédit consommé.

Paramètre	Type	Défaut	Description
limit	integer	20	Nombre maximum de résultats (100 au plus).
offset	integer	0	Nombre d’enregistrements à sauter.
status	string	—	Filtre par statut : pending, processing, completed, failed.

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

Réponse

{
  "jobs": [
    {
      "id": "8e1c8c5d-4a4f-4c1a-9b13-3d2c9c3f4e6a",
      "status": "completed",
      "template_id": "HMQywVpZxqAM",
      "filename": "invoice-001",
      "result_url": "https://cdn.templatefox.com/generated/abc/invoice-001.pdf",
      "created_at": "2026-04-25T12:00:00Z",
      "completed_at": "2026-04-25T12:00:04Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Pour suivre une seule tâche, voir GET /v1/pdf/jobs/{job_id} dans la page Créer un PDF (asynchrone).

---

Versions de template

GET /v1/templates/{template_id}/versions

Liste les versions publiées d’un template (le brouillon en cours n’y figure pas). Une version est un instantané figé : elle garantit des rendus reproductibles, par exemple des factures de fin de mois toujours rendues avec la version en ligne en début de mois.

Aucun crédit consommé.

curl https://api.templatefox.com/v1/templates/HMQywVpZxqAM/versions \
  -H "x-api-key: YOUR_API_KEY"

Réponse

{
  "versions": [
    { "version_number": 3, "tag": "2026-q2", "description": null, "created_at": "2026-04-01T09:00:00Z" },
    { "version_number": 2, "tag": "2026-q1", "description": null, "created_at": "2026-01-02T09:00:00Z" },
    { "version_number": 1, "tag": null,      "description": null, "created_at": "2025-11-10T09:00:00Z" }
  ]
}

Pour rendre une version précise, passez son tag (par exemple "2026-q2") ou son version_number sous forme de chaîne (par exemple "3") dans le champ version de POST /v1/pdf/create ou de POST /v1/pdf/create-async. Sans version, le rendu utilise le brouillon en cours.

---

Stockage S3

Configurez votre propre stockage compatible S3 : les PDF générés sont envoyés directement dans votre bucket.

GET /v1/integrations/s3

Renvoie la configuration S3 actuelle, clé secrète masquée. Sans configuration, l’API répond 404.

curl https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

Réponse (configuration présente)

{
  "configured": true,
  "endpoint_url": "https://s3.amazonaws.com",
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "secret_access_key_masked": "••••EKEY",
  "bucket_name": "my-pdf-bucket",
  "default_prefix": "invoices/"
}

---

POST /v1/integrations/s3

Enregistre ou met à jour la configuration S3.

Champ	Type	Obligatoire	Description
endpoint_url	string	Oui	URL de l’endpoint compatible S3 (doit commencer par https://)
access_key_id	string	Oui	Identifiant de la clé d’accès (16 à 128 caractères)
secret_access_key	string	Non	Clé d’accès secrète. Obligatoire à la première configuration ; omise lors d’une mise à jour, la clé existante est conservée
bucket_name	string	Oui	Nom du bucket (3 à 63 caractères, en minuscules)
default_prefix	string	Non	Préfixe de chemin par défaut des fichiers envoyés

curl -X POST https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_url": "https://s3.amazonaws.com",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "bucket_name": "my-pdf-bucket",
    "default_prefix": "invoices/"
  }'

---

DELETE /v1/integrations/s3

Supprime la configuration S3.

curl -X DELETE https://api.templatefox.com/v1/integrations/s3 \
  -H "x-api-key: YOUR_API_KEY"

---

POST /v1/integrations/s3/test

Teste la connexion au bucket avec les identifiants enregistrés.

curl -X POST https://api.templatefox.com/v1/integrations/s3/test \
  -H "x-api-key: YOUR_API_KEY"

Pour utiliser ce bucket depuis l’endpoint de génération, voir les paramètres S3 de Créer un PDF.

---

Codes d’erreur

Statut	Signification
400	Requête incohérente, par exemple un template image envoyé à /v1/pdf/create
401	Clé API absente ou invalide
402	Plus aucun crédit disponible
403	Template introuvable ou appartenant à une autre équipe
404	Ressource introuvable : version de template, tâche asynchrone, configuration S3…
422	Paramètres manquants ou invalides
429	Trop de requêtes (voir Limites de requêtes)
500	Erreur serveur

Format des réponses d’erreur

Une erreur renvoie un objet JSON avec un champ detail qui décrit le problème :

{
  "detail": "Access denied. You don't have permission to use this template."
}

Pour une erreur de validation (422), detail contient la liste des champs en cause.

---

Limites de requêtes

Les limites s’appliquent par équipe, sur une fenêtre glissante de 60 secondes :

Plan	Requêtes par minute
Gratuit	60
Payant	120

Les endpoints de génération et de modification comptent dans cette limite. Les endpoints de lecture des templates, du compte et des tâches PDF n’y sont pas soumis.

Les réponses portent ces en-têtes, sauf celles des endpoints asynchrones (create-async, jobs) :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704384000

Au-delà de la limite, l’API répond 429 avec un en-tête Retry-After : le nombre de secondes à attendre avant de réessayer.