SDK PHP et exemples REST — TemplateFox

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

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

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

Installation

composer require templatefox/sdk

La variante REST ne demande aucune dépendance : elle utilise l’extension cURL de PHP.

Configuration

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

<?php

require_once __DIR__ . '/vendor/autoload.php';

use TemplateFox\Api\PDFApi;
use TemplateFox\Configuration;

$config = Configuration::getDefaultConfiguration()
  ->setApiKey('x-api-key', getenv('TEMPLATEFOX_API_KEY'));

$api = new PDFApi(null, $config);

<?php

const BASE_URL = 'https://api.templatefox.com';

function tf_request(string $method, string $path, array $body = null): array {
  $ch = curl_init(BASE_URL . $path);
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => $method,
      CURLOPT_HTTPHEADER => [
          'x-api-key: ' . getenv('TEMPLATEFOX_API_KEY'),
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
  ]);
  return json_decode(curl_exec($ch), true);
}

Générer un PDF

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

<?php

use TemplateFox\Model\CreatePdfRequest;

$request = new CreatePdfRequest([
  'template_id' => 'YOUR_TEMPLATE_ID',
  'data' => [
      'customer_name'  => 'John Doe',
      'invoice_number' => 'INV-001',
      'amount'         => '$1,234.56',
  ],
]);

$response = $api->createPdf($request);

echo $response->getUrl() . "\n";              // signed URL valid 24h
echo $response->getCreditsRemaining() . "\n"; // credits left on the team

<?php

$response = tf_request('POST', '/v1/pdf/create', [
  'template_id' => 'YOUR_TEMPLATE_ID',
  'data' => [
      'customer_name'  => 'John Doe',
      'invoice_number' => 'INV-001',
      'amount'         => '$1,234.56',
  ],
]);

echo $response['url'] . "\n";
echo $response['credits_remaining'] . "\n";

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

Enregistrer le PDF dans un fichier

<?php

$response = $api->createPdf($request);
file_put_contents('invoice.pdf', file_get_contents($response->getUrl()));

<?php

$ch = curl_init(BASE_URL . '/v1/pdf/create');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
      'x-api-key: ' . getenv('TEMPLATEFOX_API_KEY'),
      'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'template_id' => 'YOUR_TEMPLATE_ID',
      'data' => ['customer_name' => 'Jane Doe'],
      'export_type' => 'binary',   // PDF bytes returned directly
  ]),
]);

file_put_contents('invoice.pdf', curl_exec($ch));

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.

<?php

use TemplateFox\Model\CreatePdfRequest;

$request = new 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
]);

$response = $api->createPdf($request);
echo $response->getS3Bucket() . '/' . $response->getS3Key();

<?php

$response = tf_request('POST', '/v1/pdf/create', [
  '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
]);

echo $response['s3_bucket'] . '/' . $response['s3_key'];

Conformité PDF/A

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

<?php

use TemplateFox\Model\CreatePdfRequest;

$request = new 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 = $api->createPdf($request);

<?php

$response = tf_request('POST', '/v1/pdf/create', [
  '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. Le SDK PHP expose createPdfAsync, getPdfJob et listPdfJobs dans la classe PDFAsyncApi ; le déroulé complet est décrit dans Créer un PDF (asynchrone).

<?php

use TemplateFox\Api\PDFAsyncApi;
use TemplateFox\Model\CreateAsyncPdfRequest;

$asyncApi = new PDFAsyncApi(null, $config);

$request = new CreateAsyncPdfRequest([
  'template_id'    => 'YOUR_TEMPLATE_ID',
  'data'           => ['invoice_number' => 'INV-001'],
  'webhook_url'    => 'https://example.com/webhooks/pdf',
  'webhook_secret' => 'whk_a1b2c3d4e5f6g7h8i9j0k1l2',  // HMAC-SHA256 signing
]);

$response = $asyncApi->createPdfAsync($request);
echo $response->getJobId();
// Poll $asyncApi->getPdfJob($jobId) or wait for the webhook.

<?php

$response = tf_request('POST', '/v1/pdf/create-async', [
  'template_id'    => 'YOUR_TEMPLATE_ID',
  'data'           => ['invoice_number' => 'INV-001'],
  'webhook_url'    => 'https://example.com/webhooks/pdf',
  'webhook_secret' => 'whk_a1b2c3d4e5f6g7h8i9j0k1l2',  // HMAC-SHA256 signing
]);

echo $response['job_id'];
// Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

Gestion des erreurs

<?php

use TemplateFox\ApiException;

try {
  $response = $api->createPdf($request);
} catch (ApiException $e) {
  echo 'status=' . $e->getCode() . "\n";
  echo 'body=' . $e->getResponseBody() . "\n";
}

<?php

$ch = curl_init(BASE_URL . '/v1/pdf/create');
// ... setopt ...
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($status >= 400) {
  echo "status=$status body=$body";
}

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