View Categories

API REST – Gestion des fichiers

3 minutes

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 :

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 :

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 :

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 :

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 :

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