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.

Introduction #

Take advantage of the REST APIs exposed over HTTP(s) to push or pull data from Kafinea and integrate it with third party applications. You are of course free to choose the library of your choice to work with these APIs.

The Kafinea API being a REST API, it means that you communicate directly with your Kafinea and that each request made is unique and independent from the others, nothing is stored in cache. The communication with your Kafinea is done via HTTP protocol using GET and POST requests. The response is received in JSON format. The two possible examples of successful and unsuccessful responses are shown below.

Successful response:

{
     "success" : true,
     "result" : {
                // …
     }
}

Unsuccessful response:

{
      "success" : false,
      "error" : {
              "message" : "[STRING]",        // error message
              "code" : "[STRING]"        // error code
      }
}

Login and Logout #

Login process #

The login operation is a two-step process that consists of obtaining a token and then exchanging the identification information (username and access key).
You can find your access key information under « My preferences » in the Kafinea web interface.

Token operation #

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=getchallenge&username=YourUserName

Response:

{
       "success" : true,
       "result" : {
             "token" : "[TOKENSTRING]",        // Token to use for the connection
             "serverTime" : "[TIMESTAMP]",        // Current server time
             "expireTime" : "[TIMESTAMP]"        // Token expiration time
       }
}

Login operation #

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=login
username=YourUserName
accessKey=md5(TOKENSTRING + ACCESSKEY) // Caution : accessKey= K here is capitalized.

Response:

{
      "success" : true,
      "result" : {
            "sessionId" : "[STRING]",        // Unique session identifier
            "userId" : "[STRING]",        // User ID in Kafinea
            "version" : "[STRING]",        // Version of the webservice API
            "kafineaVersion" : "[STRING]"        // Internal version of Kafinea
      }
}

Logout operation #

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=logout
sessionName=sessionId // Obtained by the login process

Extend Session Operation #

If we need to extend the duration of our session, we can use this operation.

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=extendsession

ListTypes Operation #

This operation shows all the modules you can use with this API.

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=listtypes&sessionName=sessionId

Describe Operation #

This operation allows you to know which fields are in a module, as well as the type of field, or if they are mandatory. It also allows to know which actions can be performed in this module.

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=describe&sessionName=sessionId&elementType=ModuleName

Retrieve Operation #

This operation allows you to retrieve a specific entity. It requires the Webservice ID of the entity (ex. 21×3456).

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=retrieve&sessionName=sessionId&id=WebserviceID

Create Operation #

This operation allows the creation of a new entity for a module. Care must be taken to include all mandatory fields, as well as to put the field values in the correct format. All field values related to other modules must use the Webservice IDs format (ex. 21×3456).

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=create
sessionName=sessionId // Obtained by the login process
element=JSONDATA // Array JSON of entity (fieldname=fieldvalue)
elementType=ModuleName //Entity Module Name

Attention! For inventory type modules (Invoices, Quotes, Orders, etc), it is mandatory to include the following fields in the main body of the element:
productid //Product Webservice ID
hdnTaxType //individual or group
LineItems //Array of different products or services

Update Operation #

This operation allows to update an entity already created. The same parameters must be taken into account as when creating a new entity. All fields must be included, not just those that will be modified. In addition, the entity array must include the Webservices ID of the entity (ex. ‘id’=>21×3456).

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=update
sessionName=sessionId // Obtained by the login process
element=JSONDATA // Array JSON of entity (fieldname=fieldvalue)
elementType=ModuleName //Entity Module Name

Delete Operation #

This operation allows the deletion of a specific entity. It requires the Webservice ID of the entity (ex. 21×3456).

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=delete
sessionName=sessionId // Obtained by the login process
id=WebserviceID //Webservices ID of the entity

Query Operation #

This operation allows a direct SELECT query to the database. But the query has to follow a specific format and has some limitations. It is only possible to query on a single type of entity. It is not possible to add JOINS in the query. Also the maximum number of results is 100, although you can use the LIMIT operator to manage a larger number of results by making several queries. The operators WHERE, ORDER BY, and LIMIT aren’t mandatory. The query must be URL encoded.

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery

Query Format #

SELECT * | ColumnsList | count(*)        //The three posibilities are available
FROM ModuleName
WHERE Conditionals
ORDER BY ColumnsList
LIMIT Offset, Limit;        //The final semicolon is mandatory

ColumnsList: Should be a comma separated list of fieldnames.
ModuleName: Entity module Name
Conditionals: There can be several conditionals that will be separated by the operators AND or OR and they are going to be processed from left to right. Conditionals grouping are not allowed. The three types of conditionals that you can use are the next ones :
1) Conditionals with operators : <, >, <=, >=, =, !=
2) Conditionals of type IN : IN(ValuesSeparatedByComma)
3) Conditionals of type LIKE : LIKE ‘sqlregex’
Offset: integer value to specify the offset. Offset is optional.
Limit: integer value to specify the limit

Query Related Operation #

This operation allows us to obtain the entities of the relatedlists of a specific entity. It requires the Webservice ID of the entity (ex. 21×3456). It is also possible to filter those lists using the conditionals in the query. The query should have the format specified in Query Format paragraph of this doc. The query must be set in the parameter URL encoded. The query must not have the semicolon at the end.

GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query_related&sessionName=sessionId&id=WebserviceID&relatedLabel=RelatedModuleName&query=UrlEncodedQuery

Query example:

SELECT * FROM Documents WHERE filesize > 10000

Add Related Operation #

This operation allows you to add an item to the relatedlists of a specific entity. The relatedlist must be of type ‘get_related_list’ and not ‘get_dependents_list’ because the latter are added automatically when the related entity is added.

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=add_related
sessionName=sessionId // Obtained by the login process
sourceRecordId=WebserviceID // Webservices ID of the entity
relatedLabel=RelatedModuleName //Related Module Name
relatedRecordId=WebserviceID //Webservices ID of the related entity

File Upload #

To upload a file is not done with a single operation but we will have to do a series of operations one after the other, some of them already mentioned above. These would be, in short, to create a document, upload the file and relate them.

Get Folder Webservices ID #

In order to create a document we will need the Webservice ID of the folder where the file will go. To obtain it we can do a query operation like the following.

GET  https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery

Query example:

SELECT id FROM DocumentFolders WHERE foldername LIKE 'FolderName' LIMIT 1;

Create Document Entity #

We have to create an entity of type Document to be able to add our file to it later. And for this we will use a creation operation.

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=create
sessionName=sessionId // Obtained by the login process
element=JSONDATA // Array JSON of entity (fieldname=fieldvalue)
elementType=Documents

Document fields to construct JSONDATA :

notes_title = TitleDocument //Name of the document entity
folderid = WebserviceID //Obtained in the precedent operation
filename = FileName //Name of the file to upload
filetype = FileMimeType //MIME type of the file to upload (ex. ‘application/pdf’)
filesize = FileSize //File size in bytes
filestatus = 1 //Indicates an active status
filelocationtype = I //Indicates internal storage
assigned_user_id = WebserviceID //Assigned user in format Webservice

FileUpload Operation #

This operation allows us to upload the file to the server and link the document to your file. It is also possible to use this operation alone to add images to the products, in this case you would have to change the attachmentType to ‘Image’ and the parentId to the Webservice ID of the product.

POST https://apps.kafinea.com/YourKafinea/webservice.php

POST fields:

operation=FileUpload
sessionName=sessionId // Obtained by the login process
parentId=WebserviceID // Document WebserviceID obtained in last step
attachmentType=Attachment //Attachment or Image
fileName=FileName //Name of the file to upload
fileContents=Base64FileContents //File should be base64 encoded

Files Retrieve Operation #

We can use the files_retrieve operation to retrieve previously added files from Kafinea. For this we only need the WebserviceID of the file. Not to be confused with the WebserviceID of the Document entity. We can extract this data using a query operation as we saw with the folder when uploading a document.

GET  https://apps.kafinea.com/YourKafinea/webservice.php?operation=files_retrieve&sessionName=sessionId&id=WebserviceID

We hope this guide will help you to use our API. You can contact us if you need more information.