---
title: API REST – Récupérer le PDF d’un document
description: "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,…"
url: "https://www.kafinea.com/fr/documentation/api/api-rest-documents-pdf/"
updated: "2026-10-28"
category: Intégrations / API
---

# 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 :

| Opération | Méthode | Description |
| --- | --- | --- |
| `document_pdf` | GET | Récupérer le PDF d'un document |

Elle nécessite une session valide (voir [Authentification](https://www.kafinea.com/fr/documentation/api/api-rest-authentification/)).

> **Changement de nom :** cette opération s'appelait `mds_document_pdf`. Les deux noms fonctionnent
>  jusqu'au **30 novembre 2026**, avec exactement les mêmes paramètres et la même réponse : il suffit
>  de remplacer la valeur de `operation` dans vos appels.

---

## 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`

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `document_pdf` |
| `sessionName` | string | oui | Identifiant de session |
| `id` | string | oui | Identifiant Webservice de l'enregistrement (`6x54325`), tel que renvoyé par `query` ou `retrieve` |
| `templateId` | string | non | Identifiant Webservice du modèle d'impression (`57x1088`). Si absent, le modèle par défaut du module est utilisé |
| `download` | string | non | `1` pour recevoir directement le fichier PDF au lieu de la réponse JSON |

> **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)

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

```json
{
  "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 :

```php
$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`.

```bash
curl -o facture.pdf "https://apps.kafinea.com/YourKafinea/webservice.php?operation=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.

```bash
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';"
```

```json
{
  "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.

| Condition | Détail |
| --- | --- |
| Type de document | Facture client ou avoir client |
| Verrouillage | Le document doit être verrouillé définitivement (document définitif) |
| Paramétrage de l'instance | Le format de facturation électronique doit être configuré sur Factur-X |

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 :**

```bash
curl -o facture.pdf "https://apps.kafinea.com/YourKafinea/webservice.php?operation=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

| Code | Signification |
| --- | --- |
| `INVALID_ID_ATTRIBUTE` | Paramètre `id` ou `templateId` manquant, mal formé, ou ne correspondant pas au bon module |
| `ACCESS_DENIED` | L'utilisateur connecté n'a pas le droit de consulter ce document (ou le document n'existe pas) |
| `RECORD_NOT_FOUND` | Le document n'existe pas (ou a été supprimé) |
| `PDF_NOT_SUPPORTED` | Le module ne dispose d'aucun modèle d'impression |
| `INVALID_TEMPLATE` | Le modèle demandé n'appartient pas au module du document |
| `PDF_GENERATION_FAILED` | La génération du PDF a échoué (le message précise la cause) |

**Exemple de réponse en erreur :**

```json
{
  "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](https://www.kafinea.com/fr/documentation/api/api-rest-requetes-et-interrogation/)) :

```sql
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 `invoice_facturx` renvoie le XML seul pour une facture verrouillée :

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

Cette opération s'appelait `mds_invoice_facturx` : les deux noms fonctionnent jusqu'au
 30 novembre 2026, à paramètres et réponse identiques.

---

## Références associées 🔗

- [Introduction](https://www.kafinea.com/fr/documentation/api/api-rest-introduction/)
- [Authentification](https://www.kafinea.com/fr/documentation/api/api-rest-authentification/)
- [Requêtes et interrogation](https://www.kafinea.com/fr/documentation/api/api-rest-requetes-et-interrogation/)
- [Gestion des fichiers](https://www.kafinea.com/fr/documentation/api/api-rest-fichiers/)