SDK Python et exemples REST — TemplateFox

Deux façons d’utiliser l’API TemplateFox depuis Python :

SDK (templatefox) — client typé, généré automatiquement depuis notre spécification OpenAPI.
REST — requests ou httpx. Pratique pour limiter les dépendances.

Les exemples de cette page montrent les deux côte à côte.

Installation

pip install templatefox
# or
poetry add templatefox
# or
uv add templatefox

Pour la variante REST, pip install requests suffit.

Configuration

Définissez votre clé API une fois, puis réutilisez le client.

import os
from templatefox import ApiClient, Configuration
from templatefox.api import PDFApi

config = Configuration()
config.api_key["ApiKeyAuth"] = os.environ["TEMPLATEFOX_API_KEY"]

client = ApiClient(config)
api = PDFApi(client)

import os
import requests

BASE_URL = "https://api.templatefox.com"
HEADERS = {"x-api-key": os.environ["TEMPLATEFOX_API_KEY"]}

Générer un PDF

Seuls template_id et data sont obligatoires ; tous les autres champs sont facultatifs.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
          "amount": "$1,234.56",
      },
  )
)

print(response.url)                # signed URL valid 24h
print(response.credits_remaining)  # credits left on the team

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
          "amount": "$1,234.56",
      },
  },
).json()

print(response["url"])

Tous les paramètres sont détaillés dans Créer un PDF.

Enregistrer le PDF dans un fichier

import urllib.request
from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"customer_name": "Jane Doe"},
  )
)

urllib.request.urlretrieve(response.url, "invoice.pdf")

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"customer_name": "Jane Doe"},
      "export_type": "binary",   # PDF bytes returned directly
  },
)

with open("invoice.pdf", "wb") as f:
  f.write(response.content)

Avec le SDK, vous téléchargez le fichier depuis l’URL signée. En REST, export_type="binary" renvoie directement les octets du PDF.

Envoyer le PDF dans votre bucket S3

Configurez l’intégration S3 une fois dans le tableau de bord, puis passez store_s3=True dans n’importe quel appel.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"invoice_number": "INV-001"},
      filename="invoice-001",           # no extension, .pdf appended
      store_s3=True,                     # upload to your configured bucket
      s3_filepath="invoices/2026/04/",  # key prefix (optional)
      # s3_bucket="custom-bucket",      # override bucket from integration
  )
)

print(response.s3_bucket, response.s3_key)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"invoice_number": "INV-001"},
      "filename": "invoice-001",           # no extension
      "store_s3": True,                     # upload to your configured bucket
      "s3_filepath": "invoices/2026/04/",  # key prefix (optional)
      # "s3_bucket": "custom-bucket",      # override bucket from integration
  },
).json()

print(response["s3_bucket"], response["s3_key"])

Conformité PDF/A

Pour l’archivage ou les usages juridiques, demandez une variante PDF/A.

from templatefox.models import CreatePdfRequest

response = api.create_pdf(
  CreatePdfRequest(
      template_id="YOUR_TEMPLATE_ID",
      data={"customer_name": "John Doe"},
      pdf_variant="pdf/a-2b",   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
  )
)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"customer_name": "John Doe"},
      "pdf_variant": "pdf/a-2b",   # "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
  },
)

Génération asynchrone avec webhooks

Pour les gros documents ou les traitements par lots, passez par l’endpoint asynchrone : un webhook vous prévient quand le PDF est prêt. Le déroulé complet est décrit dans Créer un PDF (asynchrone).

response = requests.post(
  f"{BASE_URL}/v1/pdf/create-async",
  headers=HEADERS,
  json={
      "template_id": "YOUR_TEMPLATE_ID",
      "data": {"invoice_number": "INV-001"},
      "webhook_url": "https://example.com/webhooks/pdf",
      "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",  # HMAC-SHA256 signing
  },
).json()

job_id = response["job_id"]
# Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

Le SDK couvre aussi ces endpoints, dans la classe PDFAsyncApi (create_pdf_async, get_pdf_job, list_pdf_jobs) ; l’exemple ci-dessus appelle l’API REST avec requests.

Gestion des erreurs

from templatefox.exceptions import ApiException
from templatefox.models import CreatePdfRequest

try:
  response = api.create_pdf(
      CreatePdfRequest(template_id="INVALID_ID", data={})
  )
except ApiException as e:
  print(e.status, e.body)

response = requests.post(
  f"{BASE_URL}/v1/pdf/create",
  headers=HEADERS,
  json={"template_id": "INVALID_ID", "data": {}},
)

if not response.ok:
  print(response.status_code, response.json().get("detail"))

La liste complète est dans Codes d’erreur.

Principales méthodes du SDK

Classe	Méthode	Endpoint
`PDFApi`	`create_pdf`	`POST /v1/pdf/create`
`PDFAsyncApi`	`create_pdf_async`	`POST /v1/pdf/create-async`
`PDFAsyncApi`	`get_pdf_job`	`GET /v1/pdf/jobs/{id}`
`PDFAsyncApi`	`list_pdf_jobs`	`GET /v1/pdf/jobs`
`ImageApi`	`create_image`	`POST /v1/image/create`
`TemplatesApi`	`list_templates`	`GET /v1/templates`
`TemplatesApi`	`get_template_fields`	`GET /v1/templates/{id}/fields`
`AccountApi`	`get_account`	`GET /v1/account`
`AccountApi`	`list_transactions`	`GET /v1/account/transactions`
`IntegrationsApi`	`save_s3_config`	`POST /v1/integrations/s3`
`IntegrationsApi`	`get_s3_config`	`GET /v1/integrations/s3`
`IntegrationsApi`	`delete_s3_config`	`DELETE /v1/integrations/s3`
`IntegrationsApi`	`test_s3_connection`	`POST /v1/integrations/s3/test`

Tous les endpoints REST sont documentés dans la référence API.

Pour aller plus loin

Créer un PDF — chaque paramètre en détail
Créer un PDF (asynchrone) — webhooks et suivi des tâches
Dépôt GitHub — code source, historique des versions, tickets
Collection Postman — testez les endpoints de façon interactive