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.

L’article L’API REST est apparu en premier sur dev Kafinea.

L’article Les préférences utilisateur est apparu en premier sur dev Kafinea.

La création d’une étiquette

Il existe 2 façons de créer une étiquette dans Kafinea :

1. Depuis une fiche : vous pouvez créer une étiquette directement depuis l’en-tête d’une fiche en cliquant sur le bouton + Ajouter balise. Le formulaire qui s’affiche vous propose les étiquettes déjà existantes. La partie droite du formulaire vous permet de créer une nouvelle balise.
2. Depuis les préférences utilisateur : vous pouvez ajouter, modifier ou supprimer des balises depuis les paramètres de Kafinea > Mes préférences > Mes balises.

Vous pouvez créer plusieurs balises à la fois en tapant le nom de chaque nouvelle balise séparé par une virgule. Vous pouvez choisir de garder ces nouvelles balises privées ou de les rendre publiques pour tous les utilisateurs de l’instance. Pour ce faire, il suffit de cocher la case Balises publiques.

L’utilisation des étiquettes

Pour voir les fiches portant le même tag, cliquez sur le tag désiré dans la section Balises du volet gauche du module concerné. Le tableau des fiches se mettra à jour en filtrant uniquement les fiches portant le tag sélectionné. Qu’en est-il des documents ?

Chaque document importé dans Kafinea (devis, factures, bons de livraison, CV, etc) est considéré comme une fiche du module Documents. Par conséquent, les tags appliqués à ces différents types de documents sont transversaux. En cliquant sur un tag, vous verrez tous les documents portant ce tag, peu importe leur type.

L’article Les étiquettes (tags) est apparu en premier sur dev Kafinea.

L’article Les rapports est apparu en premier sur dev Kafinea.

L’article Les lieux de travail est apparu en premier sur dev Kafinea.

L’article Les services est apparu en premier sur dev Kafinea.

L’article Les affectations de service est apparu en premier sur dev Kafinea.

L’article Les activités est apparu en premier sur dev Kafinea.

L’article Les matrices de polyvalence est apparu en premier sur dev Kafinea.

L’article Les formations est apparu en premier sur dev Kafinea.