API REST – Récupérer le PDF d’un document

Cette page décrit comment récupérer, depuis une application tierce, le PDF d’un document commercial (facture, avoir, devis, commande, bon de livraison, bulletin de paie…) exactement tel qu’il est généré par Kafinea, avec le modèle d’impression de votre choix.

Par défaut, lorsque le document est une facture ou un avoir et que les conditions sont réunies, le PDF renvoyé contient automatiquement le fichier Factur-X : aucun paramètre supplémentaire n’est nécessaire (voir la section « Facture électronique » plus bas).

Une seule opération est nécessaire :

Elle nécessite une session valide (voir Authentification).

---

mds_document_pdf – Récupérer le PDF #

Génère le PDF d’un enregistrement et le renvoie, soit encodé en base64 dans la réponse JSON, soit directement sous forme de fichier PDF.

GET https://apps.kafinea.com/{instance}/webservice.php

Convention des identifiants : comme pour toutes les opérations de l’API, id et templateId attendent l’identifiant Webservice complet (6x54325), celui que renvoient query, retrieve ou describe. Un identifiant brut (54325) est refusé avec le code INVALID_ID_ATTRIBUTE.

Réponse JSON (par défaut) #

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=mds_document_pdf&sessionName=YOUR_SESSION_ID&id=6x54325&templateId=57x1088"

{
  "success": true,
  "result": {
    "id": "6x54325",
    "module": "Invoice",
    "templateId": "57x1088",
    "filename": "Facture - 0053 - 2026-06-29.pdf",
    "mime": "application/pdf",
    "size": 970618,
    "base64": "JVBERi0xLjQKJeLjz9MK..."
  }
}

Le champ base64 contient les octets du PDF. Décodez-le pour reconstituer le fichier :

$pdfBytes = base64_decode($response['result']['base64']);
file_put_contents($response['result']['filename'], $pdfBytes);

Téléchargement direct du fichier #

Avec download=1, la réponse n’est plus du JSON : le fichier PDF est renvoyé tel quel, avec les en-têtes Content-Type: application/pdf et Content-Disposition: attachment.

curl -o facture.pdf "https://apps.kafinea.com/YourKafinea/webservice.php?operation=mds_document_pdf&sessionName=YOUR_SESSION_ID&id=6x54325&download=1"

Astuce : Le mode download=1 évite le surcoût de l’encodage base64 (environ +33 % de volume) : privilégiez-le lorsque vous archivez ou réexpédiez le fichier tel quel.

---

Trouver l’identifiant d’un modèle d’impression #

Le paramètre templateId est facultatif : sans lui, Kafinea utilise le modèle par défaut du module. Si vous souhaitez imposer un modèle précis, récupérez son identifiant.

Rappel : Les modèles d’impression sont un module Kafinea à part entière, donc accessibles via les opérations génériques de l’API (describe, query, retrieve…). Aucune opération dédiée n’est nécessaire.

curl --get "https://apps.kafinea.com/YourKafinea/webservice.php" \
  --data-urlencode "operation=query" \
  --data-urlencode "sessionName=YOUR_SESSION_ID" \
  --data-urlencode "query=SELECT id, templatename, basemodule, active FROM MdsPrintTemplate WHERE basemodule = 'Invoice';"

{
  "success": true,
  "result": [
    { "id": "57x1088", "templatename": "Facture client", "basemodule": "Invoice", "active": "1" },
    { "id": "57x1093", "templatename": "Facture d'avancement client", "basemodule": "Invoice", "active": "1" }
  ]
}

Le champ basemodule indique le module auquel le modèle s’applique. L’identifiant renvoyé (57x1088) s’utilise tel quel dans le paramètre templateId.

Un résultat vide signifie que le module ne dispose d’aucun modèle d’impression : l’export PDF n’est alors pas possible pour ce module.

---

Modules concernés #

L’opération fonctionne pour tout module disposant d’au moins un modèle d’impression, notamment :

• les documents de gestion commerciale : devis, commandes client, factures, avoirs, commandes fournisseur ;
• les documents logistiques : bons de livraison, bons de réception ;
• les bulletins de paie ;
• tout module pour lequel vous avez créé vos propres modèles d’impression.

Pour savoir si un module est éligible, interrogez les modèles d’impression associés à ce module (voir ci-dessus) : s’il en existe au moins un, l’export PDF est disponible.

---

Facture électronique (Factur-X) #

Le PDF renvoyé est identique à celui produit depuis l’interface : il contient donc automatiquement, et sans aucun paramètre à ajouter à votre appel, le fichier factur-x.xml lorsque toutes les conditions ci-dessous sont réunies.

Le fichier obtenu est alors un PDF/A-3 : lisible comme un PDF ordinaire, il embarque en pièce jointe le fichier XML normalisé exploitable par la comptabilité du destinataire.

Note : Un document non verrouillé est considéré comme un brouillon : son PDF porte un filigrane et ne contient pas de fichier Factur-X. C’est le comportement attendu – une facture non définitive n’a pas de valeur légale.

Vérifier la présence du fichier Factur-X :

curl -o facture.pdf "https://apps.kafinea.com/YourKafinea/webservice.php?operation=mds_document_pdf&sessionName=YOUR_SESSION_ID&id=6x54325&download=1"
strings facture.pdf | grep factur-x.xml

---

Droits d’accès #

L’opération applique les droits de l’utilisateur du compte d’intégration : si cet utilisateur n’a pas le droit de consulter le document, l’appel est refusé. Créez un utilisateur dédié à l’intégration et attribuez-lui un profil donnant accès aux seuls modules nécessaires.

---

Codes d’erreur #

Exemple de réponse en erreur :

{
  "success": false,
  "error": {
    "message": "Print template 57x1093 does not belong to module \"Invoice\".",
    "code": "INVALID_TEMPLATE"
  }
}

---

Questions fréquentes #

Comment obtenir l’identifiant d’une facture à partir de son numéro ?

Utilisez l’opération query (voir Requêtes et interrogation) :

SELECT id FROM Invoice WHERE invoice_no = 'FA-2026-0053';

L’identifiant renvoyé (6x54325) est directement utilisable comme paramètre id.

Note : Le préfixe de l’identifiant Webservice (le nombre avant le x) est propre à chaque instance : ne le codez jamais en dur, récupérez-le toujours via query ou describe.

Puis-je récupérer plusieurs PDF en une seule requête ?

Non : un appel renvoie un document. Enchaînez les appels avec la même session – la génération d’un PDF étant coûteuse, prévoyez un traitement séquentiel plutôt que massivement parallèle.

Le PDF renvoyé porte un filigrane « Brouillon ». Pourquoi ?

Le document n’est pas verrouillé définitivement. Verrouillez-le dans Kafinea, puis relancez l’appel.

Puis-je récupérer uniquement le fichier XML de la facture électronique ?

Oui, l’opération mds_invoice_facturx renvoie le XML seul pour une facture verrouillée :

curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=mds_invoice_facturx&sessionName=YOUR_SESSION_ID&id=6x54325"

---

Références associées 🔗 #

• Introduction
• Authentification
• Requêtes et interrogation
• Gestion des fichiers