---
title: API REST – Gestion des fichiers
description: "Pour ajouter un fichier à un document, créez le document puis envoyez son fichier. Pour récupérer un fichier déjà présent, utilisez directement l'opération `files_retrieve` décrite plus bas. Elle permet aussi de récupérer les images insérées dans les descriptions et les…"
url: "https://www.kafinea.com/fr/documentation/api/api-rest-fichiers/"
updated: "2026-11-15"
category: Intégrations / API
---

# API REST – Gestion des fichiers

Pour ajouter un fichier à un document, créez le document puis envoyez son fichier. Pour récupérer un fichier déjà présent, utilisez directement l'opération `files_retrieve` décrite plus bas. Elle permet aussi de récupérer les images insérées dans les descriptions et les commentaires.

---

## Étape 1 : Obtenir l'ID Webservice du dossier

Pour créer un document, vous avez besoin de l'identifiant Webservice du dossier cible. Utilisez une opération `query` :

**Exemple curl :**

```bash
curl "https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=YOUR_SESSION_ID&query=SELECT%20id%20FROM%20DocumentFolders%20WHERE%20foldername%20LIKE%20'Default'%20LIMIT%201%20;"
```

**Requête :**

```sql
SELECT id FROM DocumentFolders WHERE foldername LIKE 'Default' LIMIT 1 ;
```

---

## Étape 2 : Créer une entité Document

Créez une entité de type `Documents` via l'opération `create`.

> **POST** `https://apps.kafinea.com/{instance}/webservice.php`

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `create` |
| `sessionName` | string | oui | Identifiant de session |
| `element` | JSON | oui | Objet JSON du document (voir champs ci-dessous) |
| `elementType` | string | oui | Doit être `Documents` |

**Champs de l'objet `element` :**

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `notes_title` | string | oui | Nom de l'entité document |
| `folderid` | string | oui | ID Webservice du dossier (étape 1) |
| `filename` | string | oui | Nom du fichier |
| `filetype` | string | oui | Type MIME (ex : `application/pdf`) |
| `filesize` | int | oui | Taille du fichier en octets |
| `filestatus` | int | oui | `1` pour actif |
| `filelocationtype` | string | oui | `I` pour stockage interne |
| `assigned_user_id` | string | oui | ID Webservice de l'utilisateur assigné |

**Exemple curl :**

```bash
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php 
  -d "operation=create" 
  -d "sessionName=YOUR_SESSION_ID" 
  -d 'element={"notes_title":"Mon document","folderid":"65x1","filename":"rapport.pdf","filetype":"application/pdf","filesize":12345,"filestatus":1,"filelocationtype":"I","assigned_user_id":"19x1"}' 
  -d "elementType=Documents"
```

---

## Étape 3 : Uploader le fichier (FileUpload)

Cette opération uploade le fichier et le lie au document créé. Elle peut aussi être utilisée seule pour ajouter des images aux produits (remplacez `attachmentType` par `Image` et `parentId` par l'ID Webservice du produit).

> **POST** `https://apps.kafinea.com/{instance}/webservice.php`

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `FileUpload` |
| `sessionName` | string | oui | Identifiant de session |
| `parentId` | string | oui | ID Webservice du document (étape 2) |
| `attachmentType` | string | oui | `Attachment` pour un fichier, `Image` pour une image |
| `fileName` | string | oui | Nom du fichier |
| `fileContents` | string | oui | Contenu du fichier encodé en base64 |

**Exemple curl :**

```bash
curl -X POST https://apps.kafinea.com/YourKafinea/webservice.php 
  -d "operation=FileUpload" 
  -d "sessionName=YOUR_SESSION_ID" 
  -d "parentId=15x7890" 
  -d "attachmentType=Attachment" 
  -d "fileName=rapport.pdf" 
  -d "fileContents=$(base64 -w0 rapport.pdf)"
```

---

## Récupérer un fichier (files_retrieve)

Récupère un fichier précédemment ajouté à Kafinea, y compris une image insérée dans la description d'un ticket ou dans un commentaire. L'utilisateur API doit avoir accès au module et pouvoir consulter la fiche à laquelle le fichier est rattaché.

Le paramètre `id` est composé de **deux éléments séparés par `x`** : le préfixe Webservice du module de la fiche à laquelle le fichier est rattaché, puis l'identifiant numérique du fichier joint. Utilisez le préfixe retourné par `describe` dans `idPrefix` pour ce module : il peut varier selon l'instance.

> **Exemple :** Pour une image rattachée à un ticket, utilisez le préfixe du module des tickets suivi de l'identifiant de l'image. Pour une image rattachée à un commentaire, utilisez celui du module des commentaires. L'identifiant placé après `x` désigne le fichier joint, pas le ticket ni le commentaire.

Une image insérée dans un texte Markdown possède une adresse contenant `fid` : sa valeur correspond à l'identifiant numérique du fichier joint.

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

| Paramètre | Type | Requis | Description |
| --- | --- | --- | --- |
| `operation` | string | oui | Doit être `files_retrieve` |
| `sessionName` | string | oui | Identifiant de session |
| `id` | string | oui | Préfixe du module de rattachement + `x` + identifiant du fichier joint |

**Exemple curl :**

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

**Réponse :**

`result` contient une liste de fichiers. Pour chaque entrée, décodez `filecontents` depuis le base64 pour obtenir les octets du fichier.

| Propriété d'une entrée de `result` | Contenu |
| --- | --- |
| `fileid` | Identifiant numérique du fichier joint. |
| `filename` | Nom du fichier. |
| `filetype` | Type MIME, par exemple `image/png`. |
| `filesize` | Taille du fichier en octets. |
| `filecontents` | Contenu du fichier encodé en base64, à décoder pour obtenir le fichier. |

> **Note :** La session API suffit pour cette opération. L'ouverture de l'adresse d'une image interne dans un navigateur nécessite une connexion à Kafinea dans ce navigateur. Utilisez `files_retrieve` pour récupérer cette image depuis votre intégration ou votre assistant IA.

---

## Références associées 🔗

- [Référence complète de l'API](https://www.kafinea.com/fr/documentation/api/api-rest-reference-complete/)
- [Opérations liées](https://www.kafinea.com/fr/documentation/api/api-rest-operations-liees/)
- [Texte enrichi et images dans les enregistrements](https://www.kafinea.com/fr/documentation/interface-kafinea/les-enregistrements/#les-champs-de-texte-enrichi-markdown)
