Générer un PDF en PHP avec une API : guide pratique

Produire un PDF en PHP est un besoin permanent pour qui développe une application de gestion : factures, devis, contrats, attestations, bons de commande. Pourtant, la plupart des développeurs PHP butent rapidement sur le même obstacle. Les bibliothèques de mise en page comme TCPDF ou Dompdf demandent un temps considérable, alourdissent le projet et imposent de coder la maquette ligne par ligne. Une API de génération de PDF renverse complètement cette logique : vous décrivez le document une seule fois sous forme de modèle Word, vous envoyez vos données, et l'API vous renvoie le fichier fini.

Ce guide montre comment générer un PDF par API en PHP avec DocX, l'API documentaire de Layerone, avec deux exemples complets : un avec cURL natif, l'autre avec Guzzle, le client HTTP le plus utilisé dans l'écosystème PHP.

Le problème : générer des PDF en PHP sans librairie lourde

Quand on veut créer un PDF en PHP, l'approche classique consiste à installer une librairie de rendu : TCPDF, FPDF, Dompdf, mPDF. On positionne alors le texte, on gère les sauts de page, les polices, les marges, les tableaux. Le moindre changement de maquette devient un chantier de développement. Pire encore : ces librairies grossissent vos dépendances Composer, ralentissent vos déploiements, et leur rendu HTML-vers-PDF reste capricieux dès que la mise en page se complique.

Le contenu d'un document change en permanence — le client, les montants, les dates — mais sa mise en forme, elle, reste stable. Coder cette présentation à la main est donc fastidieux et fragile, sans compter les coûts cachés : maintenir la librairie à jour et gérer les polices manquantes sur le serveur de production. Autant de code qui n'apporte aucune valeur métier. L'idéal serait de séparer la maquette du code PHP : que le développeur n'écrive plus que la logique de données.

La solution : un modèle Word + des données → un PDF

L'approche par modèle inverse la charge. Un gérant ou un graphiste prépare la maquette dans Microsoft Word, un outil qu'il maîtrise déjà, et y place des balises comme {{ client_nom }} ou {{ total_ttc }}. Le développeur PHP se contente d'injecter les données. Il n'y a aucune librairie de rendu à installer ni à maintenir dans votre projet.

Avec DocX, le principe tient en trois étapes :

  1. Vous déposez un modèle Word (.docx) avec vos balises, et vous récupérez son identifiant (template_id).
  2. Vous appelez l'API depuis PHP en envoyant le template_id et vos données.
  3. L'API renvoie le document fini (PDF ou Word) directement dans la réponse, sous forme binaire.

Les modèles sont stockés côté serveur : vous pouvez les modifier sans toucher au code de votre application PHP. La transformation template Word vers PDF est entièrement pilotée par l'API.

Authentification et format d'envoi en PHP

Toutes les requêtes vers DocX s'authentifient avec un en-tête HTTP X-API-Key. Vous obtenez votre clé sur l'espace développeur après inscription. Cette clé est secrète : conservez-la côté serveur, jamais dans du code accessible au navigateur.

Point important pour PHP : l'endpoint POST https://docx.layerone.fr/render-document attend un corps au format formulaire (application/x-www-form-urlencoded), pas du JSON. Vous envoyez donc trois champs : template_id, json_data (vos données sérialisées en JSON via json_encode) et output_filename (le nom du fichier voulu). En PHP, cela se traduit naturellement avec http_build_query() pour cURL, ou un tableau form_params avec Guzzle.

Générer un PDF en PHP avec cURL natif

cURL est disponible dans toute installation PHP standard, sans dépendance supplémentaire. On construit le corps du formulaire avec http_build_query(), on ajoute l'en-tête X-API-Key, et comme la réponse est un fichier binaire, on l'écrit directement sur le disque : 

<?php

$apiKey = "VOTRE_CLE_API";
$url = "https://docx.layerone.fr/render-document";

$donnees = [
    "client_nom" => "Boulangerie Martin",
    "numero"     => "F-2026-0042",
    "date"       => "20/06/2026",
    "total_ttc"  => "1 250,00 €",
];

$champs = [
    "template_id"     => "facture-standard",
    "json_data"       => json_encode($donnees),
    "output_filename" => "facture.pdf",
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: " . $apiKey],
    CURLOPT_POSTFIELDS     => http_build_query($champs),
    CURLOPT_TIMEOUT        => 120,
]);

$pdf = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 200) {
    file_put_contents("facture.pdf", $pdf);
    echo "PDF généré : facture.pdf";
} else {
    echo "Erreur HTTP $code : $pdf";
}

Points clés : json_data doit être une chaîne JSON (d'où json_encode), CURLOPT_POSTFIELDS reçoit une chaîne form-encoded via http_build_query() — c'est ce qui déclenche le bon Content-Type. La réponse, récupérée grâce à CURLOPT_RETURNTRANSFER, est le PDF binaire que l'on écrit avec file_put_contents. Un CURLOPT_TIMEOUT évite de bloquer votre application si le service tarde.

Générer un PDF en PHP avec Guzzle

Sur un projet moderne (Laravel, Symfony, ou tout code basé sur Composer), Guzzle rend l'appel encore plus lisible. La clé : utiliser form_params, qui envoie automatiquement le corps en application/x-www-form-urlencoded. On installe d'abord la dépendance avec composer require guzzlehttp/guzzle, puis : 

<?php

require "vendor/autoload.php";

use GuzzleHttp\Client;

$apiKey = "VOTRE_CLE_API";

$donnees = [
    "client_nom" => "Boulangerie Martin",
    "numero"     => "F-2026-0042",
    "date"       => "20/06/2026",
    "total_ttc"  => "1 250,00 €",
];

$client = new Client();

$reponse = $client->post("https://docx.layerone.fr/render-document", [
    "headers" => ["X-API-Key" => $apiKey],
    "form_params" => [
        "template_id"     => "facture-standard",
        "json_data"       => json_encode($donnees),
        "output_filename" => "facture.pdf",
    ],
    "timeout" => 120,
]);

if ($reponse->getStatusCode() === 200) {
    // Le corps de la réponse EST le PDF binaire
    file_put_contents("facture.pdf", $reponse->getBody()->getContents());
    echo "PDF généré : facture.pdf";
}

Avec Guzzle, l'option form_params sérialise et encode le corps pour vous : vous passez un simple tableau associatif, et la requête part bien en form-urlencoded. Le corps de la réponse (getBody()) contient le PDF binaire, prêt à être écrit sur le disque ou renvoyé au navigateur.

Récupérer le PDF binaire et gérer les erreurs

Avec cURL comme avec Guzzle, le principe est identique : la réponse n'est pas du texte JSON mais le fichier lui-même, renvoyé en flux binaire. On l'écrit sur le disque, on le renvoie à l'utilisateur, ou on l'archive. Pour renvoyer directement le PDF au navigateur depuis un contrôleur, il suffit d'émettre les bons en-têtes : 

header("Content-Type: application/pdf");
header('Content-Disposition: inline; filename="facture.pdf"');
echo $pdf;

Pensez à traiter les cas d'erreur avant d'écrire le fichier :

  • 401 / 403 : clé API absente, invalide ou expirée. Vérifiez l'en-tête X-API-Key.
  • 404 : le template_id n'existe pas ou a été supprimé.
  • 429 : quota mensuel atteint sur le plan gratuit. Le corps de la réponse précise la cause.
  • 5xx : erreur côté service. Prévoyez un nouvel essai avec temporisation (retry).

Toujours vérifier le code HTTP avant d'écrire le fichier : un corps d'erreur écrit en .pdf donnerait un fichier illisible. Avec Guzzle, pensez à entourer l'appel d'un try/catch sur RequestException pour intercepter proprement les réponses non-2xx.

Factures électroniques : l'endpoint Factur-X

Pour les factures, DocX expose un second endpoint, POST /render-facturx, qui produit directement une facture Factur-X (un PDF/A-3 contenant les données structurées), conforme à la réforme française de la facture électronique. Le principe d'appel est le même qu'avec /render-document : en-tête X-API-Key, corps formulaire avec template_id, json_data et output_filename. Votre code PHP est donc quasiment identique — seule l'URL de l'endpoint change. Vous générez ainsi des factures à la fois lisibles par un humain et exploitables par un logiciel comptable, sans aucune bibliothèque supplémentaire.

Cas d'usage concrets côté PHP

  • Factures : génération automatique à chaque vente, en PDF classique ou en Factur-X pour la conformité 2026.
  • Devis Laravel ou Symfony : depuis un contrôleur, un modèle et des données suffisent à produire un devis prêt à envoyer.
  • Plugin WordPress / WooCommerce : générez les documents de commande sans alourdir le site avec une librairie de rendu PDF.
  • Rapports et contrats : remplissez les clauses ou les lignes variables depuis votre base de données, en masse.

Gratuit pour démarrer

Le plan gratuit offre 20 documents par mois, sans carte bancaire : largement de quoi valider votre intégration PHP en conditions réelles avant de passer à l'échelle. Vous obtenez votre clé API en quelques minutes sur l'espace développeur, et les deux exemples ci-dessus fonctionnent tels quels une fois votre template_id renseigné.

Obtenir une clé API gratuite Découvrir l'API

Questions fréquentes

Faut-il installer une librairie PHP comme TCPDF ou Dompdf ?

Non. C'est tout l'intérêt de l'approche par API : aucune librairie de rendu PDF n'est nécessaire dans votre projet. Vous utilisez uniquement cURL (intégré à PHP) ou Guzzle pour appeler l'API DocX, qui se charge de produire le document à partir de votre modèle Word.

Le corps de la requête est-il du JSON ou un formulaire ?

C'est un formulaire (application/x-www-form-urlencoded), pas du JSON. Vous envoyez trois champs — template_id, json_data et output_filename — où json_data est votre objet sérialisé avec json_encode. En PHP, utilisez http_build_query() avec cURL ou form_params avec Guzzle.

Comment récupérer le PDF renvoyé par l'API ?

La réponse n'est pas du texte mais le fichier PDF en flux binaire. Avec cURL, activez CURLOPT_RETURNTRANSFER puis écrivez le résultat avec file_put_contents. Avec Guzzle, lisez getBody()->getContents(). Pensez à vérifier le code HTTP avant d'écrire le fichier.

Puis-je générer des factures Factur-X en PHP ?

Oui. Il suffit d'appeler l'endpoint POST /render-facturx au lieu de /render-document, avec exactement les mêmes champs et la même authentification. Vous obtenez un PDF/A-3 conforme à la facture électronique française, directement utilisable.

Articles connexes

API de génération de PDF et documents Word Générer un PDF en Python ou Node.js Remplir un modèle Word par API Présentation de l'API Layerone Espace développeur et clés API