SDK Java et exemples REST — TemplateFox

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

SDK (io.github.templatefoxpdf:sdk) — client typé, généré automatiquement depuis notre spécification OpenAPI.
REST — le client java.net.http du JDK 11+. Pratique pour limiter les dépendances.

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

Installation

Maven

<dependency>
    <groupId>io.github.templatefoxpdf</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'io.github.templatefoxpdf:sdk:1.0.0'

La variante REST n’a besoin que du JDK 11+ (aucune dépendance).

Configuration

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

import com.templatefox.sdk.ApiClient;
import com.templatefox.sdk.api.PDFApi;

var client = new ApiClient();
client.setApiKey(System.getenv("TEMPLATEFOX_API_KEY"));

var api = new PDFApi(client);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

static final String BASE_URL = "https://api.templatefox.com";
static final String API_KEY  = System.getenv("TEMPLATEFOX_API_KEY");
static final HttpClient CLIENT = HttpClient.newHttpClient();

Générer un PDF

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

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("customer_name",  "John Doe")
  .putDataItem("invoice_number", "INV-001")
  .putDataItem("amount",         "$1,234.56");

var response = api.createPdf(request);

System.out.println(response.getUrl());              // signed URL valid 24h
System.out.println(response.getCreditsRemaining()); // credits left on the team

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": {
  "customer_name":  "John Doe",
  "invoice_number": "INV-001",
  "amount":         "$1,234.56"
}
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

Enregistrer le PDF dans un fichier

import java.io.*;
import java.net.URL;

var response = api.createPdf(request);

try (var in  = new URL(response.getUrl()).openStream();
   var out = new FileOutputStream("invoice.pdf")) {
  in.transferTo(out);
}

import java.nio.file.*;

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "customer_name": "Jane Doe" },
"export_type": "binary"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofFile(Paths.get("invoice.pdf")));

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.

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("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 = api.createPdf(request);
System.out.println(response.getS3Bucket() + "/" + response.getS3Key());

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "invoice_number": "INV-001" },
"filename":    "invoice-001",
"store_s3":    true,
"s3_filepath": "invoices/2026/04/"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

Conformité PDF/A

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

import com.templatefox.sdk.model.CreatePdfRequest;

var request = new CreatePdfRequest()
  .templateId("YOUR_TEMPLATE_ID")
  .putDataItem("customer_name", "John Doe")
  .pdfVariant("pdf/a-2b");  // "pdf/a-1b" | "pdf/a-2b" | "pdf/a-3b"

var response = api.createPdf(request);

var body = """
{
"template_id": "YOUR_TEMPLATE_ID",
"data": { "customer_name": "John Doe" },
"pdf_variant": "pdf/a-2b"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

Génération asynchrone avec webhooks

Pour les gros documents ou les traitements par lots, passez par l’endpoint asynchrone. Le déroulé complet est décrit dans Créer un PDF (asynchrone).

var body = """
{
"template_id":    "YOUR_TEMPLATE_ID",
"data":           { "invoice_number": "INV-001" },
"webhook_url":    "https://example.com/webhooks/pdf",
"webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create(BASE_URL + "/v1/pdf/create-async"))
  .header("x-api-key", API_KEY)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
// Parse job_id, then poll GET /v1/pdf/jobs/{job_id} or wait for the webhook.

L’exemple ci-dessus appelle l’API REST directement, avec java.net.http.

Gestion des erreurs

import com.templatefox.sdk.ApiException;

try {
  var response = api.createPdf(request);
} catch (ApiException e) {
  System.err.println("status=" + e.getCode() + " body=" + e.getResponseBody());
}

var response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() >= 400) {
  System.err.println("status=" + response.statusCode() + " body=" + response.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`
`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