Introduction #
Profitez des API REST exposées sur HTTP(s) pour pousser ou tirer des données de Kafinea et les intégrer à des applications tierces. Vous êtes bien sûr libre de choisir la bibliothèque de votre choix pour travailler avec ces API.
L’API Kafinea étant une API REST, cela signifie que vous communiquez directement avec votre instance Kafinea et que chaque requête effectuée est unique et indépendante des autres. Rien n’est stocké en cache. La communication avec votre instance Kafinea se fait via le protocole HTTP en utilisant des requêtes GET et POST. La réponse est reçue au format JSON. Les deux exemples possibles de réponses positives ou négatives sont présentés ci-dessous.
Réponse positive :
{
"success" : true,
"result" : {
// ...
}
}
Réponse négative :
{
"success" : false,
"error" : {
"message" : "[STRING]", // message d'erreur
"code" : "[STRING]" // code d'erreur
}
}
Connexion et déconnexion #
Processus de connexion #
L’opération de connexion est un processus en deux étapes qui consiste à obtenir un jeton et à échanger les informations d’identification (nom d’utilisateur et clé d’accès). Vous pouvez trouver les informations relatives à votre clé d’accès sous « Mes préférences » dans l’interface web de Kafinea.
Fonctionnement du token #
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=getchallenge&username=YourUserName
Réponse :
{
"success" : true,
"result" : {
"token" : "[TOKENSTRING]", // Token à utiliser pour la connexion
"serverTime" : "[TIMESTAMP]", // Heure actuelle du serveur
"expireTime" : "[TIMESTAMP]", // Heure d'expiration du token
}
}
Opération de connexion #
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=login
username=VotreNomDeServeur
accessKey=md5(TOKENSTRING + ACCESSKEY) // Attention : accessKey= K est ici en majuscule.
Réponse :
{
"success" : true,
"result" : {
"sessionId" : "[STRING]", // Identifiant unique de la session
"userId" : "[STRING]", // Identifiant de l'utilisateur dans Kafinea
"version" : "[STRING]", // Version de l'API du webservice
"kafineaVersion" : "[STRING]", // Version de l'API du webservice
}
}
Opération de déconnexion #
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=logout
sessionName=sessionId // Obtenu par le processus de connexion
Extension du fonctionnement de la session #
Si vous devez prolonger la durée de votre session, vous pouvez utiliser cette opération.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=extendsession
Opération ListTypes #
Cette opération montre tous les modules que vous pouvez utiliser avec cette API.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=listtypes&sessionName=sessionId
Opération de description #
Cette opération permet de connaître les champs présents dans un module, ainsi que le type de champ, ou encore s’ils sont obligatoires. Elle permet également de savoir quelles actions peuvent être effectuées dans ce module.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=describe&sessionName=sessionId&elementType=ModuleName
Opération de récupération #
Cette opération vous permet de récupérer une entité spécifique. Elle nécessite l’ID du Webservice de l’entité (ex. 21×3456).
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=retrieve&sessionName=sessionId&id=WebserviceID
Opération de création #
Cette opération permet de créer une nouvelle entité pour un module. Il faut veiller à inclure tous les champs obligatoires, ainsi qu’à mettre les valeurs des champs dans le bon format. Toutes les valeurs de champ liées à d’autres modules doivent utiliser le format Webservice IDs (ex. 21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=create
sessionName=sessionId // Obtenu par le processus de connexion
element=JSONDATA // Tableau JSON de l’entité (fieldname=fieldvalue)
elementType=ModuleName //Nom du module de l’entité
Attention ! Pour les modules de type inventaire (factures, devis, commandes, etc), il est obligatoire d’inclure les champs suivants dans le corps de l’élément :
productid // ID du Webservice produit
hdnTaxType // Individual ou Group
LineItems // Tableau de différents produits ou services
Opération de mise à jour #
Cette opération permet de mettre à jour une entité déjà créée. Les mêmes paramètres doivent être pris en compte que lors de la création d’une nouvelle entité. Tous les champs doivent être inclus, et pas seulement ceux qui seront modifiés. De plus, le tableau de l’entité doit inclure l’ID Webservices de l’entité (ex. ‘id’=>21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=update
sessionName=sessionId // Obtenu par le processus de connexion
element=JSONDATA // Tableau JSON de l’entité (fieldname=fieldvalue)
elementType=ModuleName // Nom du module de l’entité
Opération de suppression #
Cette opération permet de supprimer une entité spécifique. Elle nécessite l’identifiant Webservice de l’entité (ex. 21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=delete
sessionName=sessionId // Obtenu par le processus de connexion
id=WebserviceID // Identifiant du webservice de l’entité
Opération d’interrogation #
Cette opération permet d’effectuer une requête SELECT directement dans la base de données. Mais la requête doit suivre un format spécifique et présente certaines limitations. Il n’est possible d’interroger qu’un seul type d’entité. Il n’est pas possible d’ajouter des JOINTS dans la requête. Le nombre maximum de résultats est également de 100, bien que vous puissiez utiliser l’opérateur LIMIT pour gérer un plus grand nombre de résultats en effectuant plusieurs requêtes. Les opérateurs WHERE, ORDER BY et LIMIT ne sont pas obligatoires. La requête doit être définie dans le paramètre URL encoded.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery
Format de la requête #
SELECT * | ColumnsList | count(*) // Les trois possibilités sont disponibles FROM ModuleName WHERE Conditions ORDER BY ColumnsList LIMIT Offset, Limit ; // Le point-virgule final est obligatoire
ColumnsList : Doit être une liste de noms de champs séparés par des virgules.
ModuleName : Nom du module de l’entité
Conditions : Il peut y avoir plusieurs conditionnelles qui seront séparées par les opérateurs AND ou OR et qui seront traitées de gauche à droite. Le regroupement de conditions n’est pas autorisé. Les trois types de conditionnelles que vous pouvez utiliser sont les suivants :
1) Conditionnelles avec opérateurs : , =, =, !=
2) Conditionnelles de type IN : IN(ValuesSeparatedByComma)
3) Conditionnelles de type LIKE : LIKE ‘sqlregex’
Offset : valeur entière pour spécifier l’offset. Le décalage est facultatif.
Limite : valeur entière pour spécifier la limite.
Opération liée à l’interrogation #
Cette opération permet d’obtenir les entités des listes connexes d’une entité spécifique. Elle nécessite l’ID du Webservice de l’entité (ex. 21×3456). Il est également possible de filtrer ces listes en utilisant les conditionnels de la requête. La requête doit avoir le format spécifié dans le paragraphe Format de la requête de ce document. La requête doit être encodée en URL. La requête ne doit pas comporter de point-virgule à la fin.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query_related&sessionName=sessionId&id=WebserviceID&relatedLabel=RelatedModuleName&query=UrlEncodedQuery
Exemple de requête :
SELECT * FROM Documents WHERE filesize > 10000
Ajouter une opération connexe #
Cette opération permet d’ajouter un élément aux listes connexes d’une entité spécifique. La liste apparentée doit être de type « get_related_list » et non « get_dependents_list », car ces derniers sont ajoutés automatiquement lors de l’ajout de l’entité apparentée.
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=add_related
sessionName=sessionId // Obtenu par le processus de connexion
sourceRecordId=WebserviceID // ID Webservices de l’entité
relatedLabel=RelatedModuleName // Nom du module lié
relatedRecordId=WebserviceID // Identifiant Webservices de l’entité liée
Téléchargement de fichiers #
Le téléchargement d’un fichier ne se fait pas en une seule opération, mais vous devrez effectuer une série d’opérations l’une après l’autre, dont certaines ont déjà été mentionnées plus haut. En résumé, il s’agit de créer un document, de télécharger le fichier et de les mettre en relation.
Obtenir l’ID des Webservices du dossier #
Pour créer un document, vous avez besoin de l’identifiant Webservice du dossier dans lequel le fichier sera placé. Pour l’obtenir, vous pouvez effectuer une opération de requête comme la suivante :
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery
Exemple de requête :
SELECT id FROM DocumentFolders WHERE foldername LIKE 'FolderName' LIMIT 1 ;
Créer une entité de document #
Vous devez créer une entité de type Document pour pouvoir y ajouter notre fichier ultérieurement. Pour ce faire, vous pouvez utiliser une opération de création.
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=create
sessionName=sessionId // Obtenu par le processus de connexion
element=JSONDATA // Tableau JSON de l’entité (nom du champ=valeur du champ)
elementType=Documents
Champs du document pour construire le JSONDATA :
notes_title = TitleDocument // Nom de l’entité document
folderid = WebserviceID // Obtenu lors de l’opération précédente
filename = FileName // Nom du fichier à télécharger
filetype = FileMimeType // Type MIME du fichier à télécharger (ex. ‘application/pdf’)
filesize = FileSize // Taille du fichier en octets
filestatus = 1 // Indique un statut actif
filelocationtype = I // Indique un stockage interne
assigned_user_id = WebserviceID // Assigned user in format Webservice
Opération FileUpload #
Cette opération vous permet de télécharger le fichier sur le serveur et de lier le document à votre fichier. Il est également possible d’utiliser cette opération seule pour ajouter des images aux produits. Dans ce cas, vous devez remplacer attachmentType par « Image » et parentId par l’ID du Webservice du produit.
POST https://apps.kafinea.com/YourKafinea/webservice.php
Champs POST :
operation=FileUpload
sessionName=sessionId // Obtenu par le processus de connexion
parentId=WebserviceID // Document WebserviceID obtenu lors de la dernière étape
attachmentType=Attachment // Pièce jointe ou image
fileName=FileName // Nom du fichier à télécharger
fileContents=Base64FileContents // Le fichier devrait être encodé en base64
Opération de récupération des fichiers #
Vous pouvez utiliser l’opération files_retrieve pour récupérer les fichiers précédemment ajoutés à Kafinea. Pour cela, vous n’avez besoin que du WebserviceID du fichier (à ne pas confondre avec le WebserviceID de l’entité Document). Vous pouvez extraire ces données en utilisant une opération de requête comme nous l’avons vu avec le dossier lors du téléchargement d’un document.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=files_retrieve&sessionName=sessionId&id=WebserviceID
Nous espérons que ce guide vous aidera à utiliser notre API ! Vous pouvez nous contacter si vous avez besoin de plus d’informations.