SDK TypeScript et exemples REST — TemplateFox

Deux façons d’utiliser l’API TemplateFox depuis Node.js :

• SDK (@templatefox/sdk) — client typé, généré automatiquement depuis notre spécification OpenAPI.
• REST — fetch ou n’importe quel client HTTP. Pratique sur les runtimes edge ou pour limiter les dépendances.

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

Dépôt GitHub

Installation

npm install @templatefox/sdk
# or
yarn add @templatefox/sdk
# or
pnpm add @templatefox/sdk

La variante REST ne demande aucune dépendance : fetch est intégré à Node 18+ et à tous les runtimes récents.

Configuration

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

SDK REST

Copier

import { Configuration, PDFApi } from "@templatefox/sdk";

const api = new PDFApi(
new Configuration({
  apiKey: process.env.TEMPLATEFOX_API_KEY!,
}),
);

const BASE_URL = "https://api.templatefox.com";
const headers = {
"x-api-key": process.env.TEMPLATEFOX_API_KEY!,
"Content-Type": "application/json",
};

Générer un PDF

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

SDK REST

Copier

const response = await api.createPdf({
templateId: "YOUR_TEMPLATE_ID",
data: {
  customer_name: "John Doe",
  invoice_number: "INV-001",
  amount: "$1,234.56",
},
});

console.log(response.url);              // signed URL valid 24h
console.log(response.creditsRemaining); // credits left on the team

const res = await fetch(`${BASE_URL}/v1/pdf/create`, {
method: "POST",
headers,
body: JSON.stringify({
  template_id: "YOUR_TEMPLATE_ID",
  data: {
    customer_name: "John Doe",
    invoice_number: "INV-001",
    amount: "$1,234.56",
  },
}),
});

const { url, credits_remaining } = await res.json();

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

Enregistrer le PDF dans un fichier

SDK REST

Copier

import fs from "node:fs";

const { url } = await api.createPdf({
templateId: "YOUR_TEMPLATE_ID",
data: { customer_name: "Jane Doe" },
});

const pdf = await fetch(url).then((r) => r.arrayBuffer());
fs.writeFileSync("invoice.pdf", Buffer.from(pdf));

import fs from "node:fs";

const res = await fetch(`${BASE_URL}/v1/pdf/create`, {
method: "POST",
headers,
body: JSON.stringify({
  template_id: "YOUR_TEMPLATE_ID",
  data: { customer_name: "Jane Doe" },
  export_type: "binary",   // PDF bytes returned directly
}),
});

const buffer = Buffer.from(await res.arrayBuffer());
fs.writeFileSync("invoice.pdf", buffer);

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 : un aller-retour de moins.

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.

SDK REST

Copier

const response = await api.createPdf({
templateId: "YOUR_TEMPLATE_ID",
data: { invoice_number: "INV-001" },
filename: "invoice-001",           // no extension, .pdf appended
storeS3: true,                      // upload to your configured bucket
s3Filepath: "invoices/2026/04/",   // key prefix (optional)
// s3Bucket: "custom-bucket",      // override bucket from integration
});

console.log(response.s3Bucket, response.s3Key);

const res = await fetch(`${BASE_URL}/v1/pdf/create`, {
method: "POST",
headers,
body: JSON.stringify({
  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
}),
});

const { s3_bucket, s3_key } = await res.json();

Conformité PDF/A

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

SDK REST

Copier

const response = await api.createPdf({
templateId: "YOUR_TEMPLATE_ID",
data: { customer_name: "John Doe" },
pdfVariant: "pdf/a-2b",   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
});

const res = await fetch(`${BASE_URL}/v1/pdf/create`, {
method: "POST",
headers,
body: JSON.stringify({
  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).

REST

Copier

const res = await fetch(`${BASE_URL}/v1/pdf/create-async`, {
method: "POST",
headers,
body: JSON.stringify({
  template_id: "YOUR_TEMPLATE_ID",
  data: { invoice_number: "INV-001" },
  webhook_url: "https://example.com/webhooks/pdf",
  webhook_secret: "whk_a1b2c3d4e5f6g7h8i9j0k1l2",  // HMAC-SHA256 signing
}),
});

const { job_id } = await res.json();
// Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

Le SDK couvre aussi ces endpoints, dans la classe PDFAsyncApi (createPdfAsync, getPdfJob, listPdfJobs) ; l’exemple ci-dessus appelle l’API REST avec fetch.

Gestion des erreurs

SDK REST

Copier

import { ResponseError } from "@templatefox/sdk";

try {
const response = await api.createPdf({
  templateId: "INVALID_ID",
  data: {},
});
} catch (error) {
if (error instanceof ResponseError) {
  const body = await error.response.json();
  console.error(error.response.status, body.detail);
}
}

const res = await fetch(`${BASE_URL}/v1/pdf/create`, {
method: "POST",
headers,
body: JSON.stringify({ template_id: "INVALID_ID", data: {} }),
});

if (!res.ok) {
const { detail } = await res.json();
console.error(res.status, detail);
}

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

Principales méthodes du SDK

Classe	Méthode	Endpoint
PDFApi	createPdf	POST /v1/pdf/create
PDFAsyncApi	createPdfAsync	POST /v1/pdf/create-async
PDFAsyncApi	getPdfJob	GET /v1/pdf/jobs/{id}
PDFAsyncApi	listPdfJobs	GET /v1/pdf/jobs
ImageApi	createImage	POST /v1/image/create
TemplatesApi	listTemplates	GET /v1/templates
TemplatesApi	getTemplateFields	GET /v1/templates/{id}/fields
AccountApi	getAccount	GET /v1/account
AccountApi	listTransactions	GET /v1/account/transactions
IntegrationsApi	saveS3Config	POST /v1/integrations/s3
IntegrationsApi	getS3Config	GET /v1/integrations/s3
IntegrationsApi	deleteS3Config	DELETE /v1/integrations/s3
IntegrationsApi	testS3Connection	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