SDK C# et exemples REST — TemplateFox

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

• SDK (TemplateFox.SDK) — client typé, généré automatiquement depuis notre spécification OpenAPI.
• REST — HttpClient. Pratique pour limiter les dépendances.

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

Dépôt GitHub

Installation

dotnet add package TemplateFox.SDK
# or Package Manager:
Install-Package TemplateFox.SDK

La variante REST utilise System.Net.Http, inclus dans .NET.

Configuration

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

SDK REST

Copier

using TemplateFox.SDK.Api;
using TemplateFox.SDK.Client;

var config = new Configuration
{
  ApiKey = new Dictionary<string, string>
  {
      { "x-api-key", Environment.GetEnvironmentVariable("TEMPLATEFOX_API_KEY")! }
  }
};

var api = new PDFApi(config);

using System.Net.Http;
using System.Net.Http.Json;

const string BASE_URL = "https://api.templatefox.com";

var client = new HttpClient { BaseAddress = new Uri(BASE_URL) };
client.DefaultRequestHeaders.Add(
  "x-api-key",
  Environment.GetEnvironmentVariable("TEMPLATEFOX_API_KEY")
);

Générer un PDF

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

SDK REST

Copier

using TemplateFox.SDK.Model;

var request = new CreatePdfRequest(
  templateId: "YOUR_TEMPLATE_ID",
  data: new Dictionary<string, object>
  {
      { "customer_name",  "John Doe" },
      { "invoice_number", "INV-001" },
      { "amount",         "$1,234.56" }
  }
);

var response = await api.CreatePdfAsync(request);

Console.WriteLine(response.Url);               // signed URL valid 24h
Console.WriteLine(response.CreditsRemaining);  // credits left on the team

var response = await client.PostAsJsonAsync("/v1/pdf/create", new
{
  template_id = "YOUR_TEMPLATE_ID",
  data = new
  {
      customer_name  = "John Doe",
      invoice_number = "INV-001",
      amount         = "$1,234.56"
  }
});

var result = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
Console.WriteLine(result!["url"]);

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

Enregistrer le PDF dans un fichier

SDK REST

Copier

using var httpClient = new HttpClient();

var response = await api.CreatePdfAsync(request);

var pdfBytes = await httpClient.GetByteArrayAsync(response.Url);
await File.WriteAllBytesAsync("invoice.pdf", pdfBytes);

var response = await client.PostAsJsonAsync("/v1/pdf/create", new
{
  template_id = "YOUR_TEMPLATE_ID",
  data = new { customer_name = "Jane Doe" },
  export_type = "binary"   // PDF bytes returned directly
});

await using var file = File.Create("invoice.pdf");
await response.Content.CopyToAsync(file);

Envoyer le PDF dans votre bucket S3

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

SDK REST

Copier

using TemplateFox.SDK.Model;

var request = new CreatePdfRequest(
  templateId: "YOUR_TEMPLATE_ID",
  data: new Dictionary<string, object> { { "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
);

var response = await api.CreatePdfAsync(request);
Console.WriteLine($"{response.S3Bucket}/{response.S3Key}");

var response = await client.PostAsJsonAsync("/v1/pdf/create", new
{
  template_id = "YOUR_TEMPLATE_ID",
  data        = new { 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
});

var result = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
Console.WriteLine($"{result!["s3_bucket"]}/{result["s3_key"]}");

Conformité PDF/A

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

SDK REST

Copier

using TemplateFox.SDK.Model;

var request = new CreatePdfRequest(
  templateId: "YOUR_TEMPLATE_ID",
  data:       new Dictionary<string, object> { { "customer_name", "John Doe" } },
  pdfVariant: "pdf/a-2b"   // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"
);

var response = await api.CreatePdfAsync(request);

var response = await client.PostAsJsonAsync("/v1/pdf/create", new
{
  template_id = "YOUR_TEMPLATE_ID",
  data        = new { 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 .NET expose CreatePdfAsyncAsync, GetPdfJobAsync et ListPdfJobsAsync dans la classe PDFAsyncApi ; le déroulé complet est décrit dans Créer un PDF (asynchrone).

SDK REST

Copier

using TemplateFox.SDK.Api;
using TemplateFox.SDK.Model;

var asyncApi = new PDFAsyncApi(config);

var request = new CreateAsyncPdfRequest(
  templateId:    "YOUR_TEMPLATE_ID",
  data:          new Dictionary<string, object> { { "invoice_number", "INV-001" } },
  webhookUrl:    "https://example.com/webhooks/pdf",
  webhookSecret: "whk_a1b2c3d4e5f6g7h8i9j0k1l2"   // HMAC-SHA256 signing
);

var response = await asyncApi.CreatePdfAsyncAsync(request);
Console.WriteLine(response.JobId);
// Poll await asyncApi.GetPdfJobAsync(jobId) or wait for the webhook.

var response = await client.PostAsJsonAsync("/v1/pdf/create-async", new
{
  template_id    = "YOUR_TEMPLATE_ID",
  data           = new { invoice_number = "INV-001" },
  webhook_url    = "https://example.com/webhooks/pdf",
  webhook_secret = "whk_a1b2c3d4e5f6g7h8i9j0k1l2"   // HMAC-SHA256 signing
});

var result = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
Console.WriteLine(result!["job_id"]);
// Poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

Gestion des erreurs

SDK REST

Copier

using TemplateFox.SDK.Client;

try
{
  var response = await api.CreatePdfAsync(request);
}
catch (ApiException e)
{
  Console.WriteLine($"status={e.ErrorCode} body={e.ErrorContent}");
}

var response = await client.PostAsJsonAsync("/v1/pdf/create", new
{
  template_id = "INVALID_ID",
  data = new { }
});

if (!response.IsSuccessStatusCode)
{
  var body = await response.Content.ReadAsStringAsync();
  Console.WriteLine($"status={(int)response.StatusCode} body={body}");
}

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

Principales méthodes du SDK

Classe	Méthode	Endpoint
PDFApi	CreatePdfAsync	POST /v1/pdf/create
PDFAsyncApi	CreatePdfAsyncAsync	POST /v1/pdf/create-async
PDFAsyncApi	GetPdfJobAsync	GET /v1/pdf/jobs/{id}
PDFAsyncApi	ListPdfJobsAsync	GET /v1/pdf/jobs
TemplatesApi	ListTemplatesAsync	GET /v1/templates
TemplatesApi	GetTemplateFieldsAsync	GET /v1/templates/{id}/fields
AccountApi	GetAccountAsync	GET /v1/account
AccountApi	ListTransactionsAsync	GET /v1/account/transactions
IntegrationsApi	SaveS3ConfigAsync	POST /v1/integrations/s3
IntegrationsApi	GetS3ConfigAsync	GET /v1/integrations/s3
IntegrationsApi	DeleteS3ConfigAsync	DELETE /v1/integrations/s3
IntegrationsApi	TestS3ConnectionAsync	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