Documentation de l’API HTML et JSON vers PDF

Un template HTML, des données JSON, un document PDF. Les exemples ci-dessous utilisent la même API que le playground.

https://api.templatr.app

Authentification

Créez une clé dans Paramètres → Clés API, puis transmettez-la dans l’en-tête Authorization: Bearer. Les URL avec api_key restent compatibles, mais l’en-tête évite de placer la clé dans les historiques et journaux d’URL.

Enregistrer un template

Enregistrez cet exemple dans template.html, puis envoyez-le en multipart. La réponse contient template_id : remplacez TEMPLATE_ID dans les exemples suivants. Le champ name définit le nom ; le champ json peut enregistrer un objet JSON d’exemple.

html

<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Invoice</title>
<style>body { font: 16px sans-serif; margin: 32px; } table { width: 100%; } td { padding: 8px; }</style>
</head><body>
<h1>Invoice for {{customer.name}}</h1>
<table>{{ items loop }}<tr><td>{{item.description}}</td><td>{{item.price}}</td></tr>{{ end loop }}</table>
<p>Total: {{total}}</p>
</body></html>

bash

curl -X POST "https://api.templatr.app/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" -F "name=Invoice"

Générer un PDF

Envoyez directement votre objet de données JSON. Avec format=pdf, la réponse est un fichier application/pdf. Sans ce paramètre, vous recevez un objet { pdf_url, expires_in } : le lien signé expire après une heure. Vos documents restent accessibles dans l’historique avec votre compte.

bash

curl -X POST "https://api.templatr.app/pdf/TEMPLATE_ID?format=pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"customer":{"name":"Ada"},"items":[{"description":"Design","price":120}],"total":120}' \
  --output invoice.pdf

javascript

const response = await fetch('https://api.templatr.app/pdf/TEMPLATE_ID?format=pdf', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
  "customer": {
    "name": "Ada"
  },
  "items": [
    {
      "description": "Design",
      "price": 120
    }
  ],
  "total": 120
})
});
if (!response.ok) throw new Error(await response.text());
const pdf = await response.blob();

python

import requests

response = requests.post(
    "https://api.templatr.app/pdf/TEMPLATE_ID?format=pdf",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"customer":{"name":"Ada"},"items":[{"description":"Design","price":120}],"total":120},
    timeout=60,
)
response.raise_for_status()
with open("invoice.pdf", "wb") as output:
    output.write(response.content)

Variables et boucles

Les valeurs sont échappées en HTML. Utilisez {{customer.name}} pour une propriété imbriquée et {{ items loop }}…{{ end loop }} pour un tableau. Dans cet exemple, item désigne chaque élément de items. Les boucles imbriquées sont prises en charge. Les variables absentes deviennent vides. Les conditions if/else et la syntaxe Handlebars #each ne sont pas prises en charge : calculez vos totaux et textes dans le JSON.

json

{
  "customer": {
    "name": "Ada"
  },
  "items": [
    {
      "description": "Design",
      "price": 120
    }
  ],
  "total": 120
}

Gérer les templates

Toutes ces routes sont limitées au propriétaire du template. Une modification accepte un fichier HTML, un nom et des données JSON d’exemple.

GET	/upload/:id	HTML, name, json, created_at, updated_at
PUT	/upload/:id	multipart: file, name, json
DELETE	/upload/:id	Delete template
POST	/pdf/:id?format=pdf	JSON → application/pdf
GET	/documents/:id	Authorization: Bearer YOUR_API_KEY

Quotas et limites

Toutes les clés d’un compte partagent le même quota. Créer ou renouveler une clé ne fournit pas de crédits supplémentaires. La consommation est remise à zéro au renouvellement payé de l’abonnement ; le plan gratuit suit les mois UTC. Une génération PDF échouée est remboursée. Taille maximale : 5 Mo de HTML et 1 Mo de JSON. Le rendu utilise A4 par défaut et respecte la règle CSS @page. JavaScript n’est pas exécuté.

Les limites de débit sont partagées par adresse IP : 30 générations PDF/minute, 5 demandes IA/minute et 20 tentatives d’authentification/15 minutes. La démo publique autorise 2 tentatives PDF et 2 demandes IA par jour UTC.

Erreurs

400	Invalid HTML, JSON or request
401	Missing, expired or invalid credentials
403	Admin access required
404	Resource not found
413	Request body too large
429	Quota or rate limit exceeded; check Retry-After
502	PDF rendering failed; retry later

Exemples de factures complets

Retrouvez des templates HTML, des données JSON et des requêtes API pour la facturation SaaS et les commandes ecommerce.

Voir les guides de factures PDF →

Intégrations guidées

Téléchargez les scripts Node.js et Python, puis testez la pagination CSS avec un rapport complet.

Voir les tutoriels

Notifications HTTP

Configurez une URL HTTPS publique dans Paramètres → Webhooks. Les événements sont placés dans une file persistante, livrés en tâche de fond et retentés jusqu’à 5 fois. Vérifiez X-Templatr-Signature avec HMAC-SHA256 sur le corps brut et votre secret. Dédupliquez les livraisons avec X-Templatr-Delivery.

pdf.generated, template.created, template.updated, template.deleted, quota.warning.75, quota.warning.90, quota.warning.100, subscription.changed