Introduction #
Take advantage of 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.
As the Kafinea API is a REST API, this means that you communicate directly with your Kafinea instance, and that each request you make is unique and independent of the others. Nothing is cached. Communication with your Kafinea instance takes place via the HTTP protocol, using GET and POST requests. The response is received in JSON format. The two possible examples of positive and negative responses are shown below.
Positive response:
{
"success" : true,
"result" : {
// ...
}
}
Negative answer :
{
"success" : false,
"error" : {
"message" : "[STRING]", // message d'erreur
"code" : "[STRING]" // code d'erreur
}
}
Login and logout #
Connection process #
The login operation is a two-step process that involves obtaining a token and exchanging identification information (username and access key). You can find your access key information under "My preferences" in the Kafinea web interface.
How the # token works
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=getchallenge&username=YourUserName
Answer:
{
"success" : true,
"result" : {
"token" : "[TOKENSTRING]", // Token à utiliser pour la connexion
"serverTime" : "[TIMESTAMP]", // Heure actuelle du serveur
"expireTime" : "[TIMESTAMP]", // Heure d'expiration du token
}
}
Connection operation #
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=login
username=YourServerName
accessKey=md5(TOKENSTRING + ACCESSKEY) // Please note: accessKey= K is capitalized here.
Answer:
{
"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
}
}
Disconnection operation
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=logout
sessionName=sessionId // Obtained by the login process
Session operation extension #
If you need to extend the duration of your session, you can use this operation.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=extendsession
Operation ListTypes #
This operation shows all the modules you can use with this API.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=listtypes&sessionName=sessionId
Description operation #
This operation lets you know which fields are present in a module, as well as the type of field, or whether they are mandatory. It also shows which actions can be performed in the module.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=describe&sessionName=sessionId&elementType=ModuleName
Recovery operation #
This operation allows you to retrieve a specific entity. It requires the entity's Webservice ID (e.g. 21×3456).
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=retrieve&sessionName=sessionId&id=WebserviceID
Creative operation #
This operation creates a new entity for a module. Care must be taken to include all mandatory fields, and to set field values in the correct format. All field values linked to other modules must use the Webservice IDs format (e.g. 21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=create
sessionName=sessionId // Obtained by the connection process
element=JSONDATA // JSON array of the entity (fieldname=fieldvalue)
elementType=ModuleName //Name of the entity's module
Please note! For inventory-type modules (invoices, quotes, orders, etc.), it is mandatory to include the following fields in the element body:
productid // Webservice product ID
hdnTaxType // Individual or Group
LineItems // Table of different products or services
Update operation #
This operation updates a previously created entity. 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 table must include the entity's Webservices ID (e.g. 'id'=>21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=update
sessionName=sessionId // Obtained by the connection process
element=JSONDATA // JSON array of the entity (fieldname=fieldvalue)
elementType=ModuleName // Name of the entity's module
Delete operation #
This operation deletes a specific entity. It requires the entity's Webservice identifier (e.g. 21×3456).
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=delete
sessionName=sessionId // Obtained by the connection process
id=WebserviceID // Identifier of the entity's webservice
Query operation #
This operation allows you to perform a SELECT query directly in the database. But the query must follow a specific format and has certain limitations. Only one type of entity can be queried. JOINTS cannot be added to the query. The maximum number of results is also 100, although you can use the LIMIT operator to manage a larger number of results by running multiple queries. The WHERE, ORDER BY and LIMIT operators are not mandatory. The query must be defined in the URL encoded parameter.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery
Query format #
SELECT * | ColumnsList | count(*) // All three possibilities are available FROM ModuleName WHERE Conditions ORDER BY ColumnsList LIMIT Offset, Limit ; // The final semicolon is mandatory
ColumnsList: Must be a comma-separated list of field names.
ModuleName: Name of the entity's module
Conditions: There may be several conditionals, separated by AND or OR operators and processed from left to right. Grouping conditions is not allowed. The three types of conditional you can use are:
1) Conditionals with operators : , =, =, !=
2) IN conditionals: IN(ValuesSeparatedByComma)
3) LIKE conditionals: LIKE 'sqlregex'
Offset: integer value to specify offset. Offset is optional.
Limit: integer value to specify limit.
Operation linked to query #
This operation is used to obtain the entities in the related lists of a specific entity. It requires the entity's Webservice ID (e.g. 21×3456). It is also possible to filter these lists using query conditionals. The query must have the format specified in the Query format paragraph of this document. The query must be URL-encoded. The query must not contain a semicolon at the end.
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query_related&sessionName=sessionId&id=WebserviceID&relatedLabel=RelatedModuleName&query=UrlEncodedQuery
Example query:
SELECT * FROM Documents WHERE filesize > 10000
Add a related operation #
This operation adds an element to the related lists of a specific entity. The related list must be of type "get_related_list" and not "get_dependents_list", as 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 connection process
sourceRecordId=WebserviceID // Webservices ID of the entity
relatedLabel=RelatedModuleName // Name of the related module
relatedRecordId=WebserviceID // Webservices ID of the related entity
File download #
Uploading a file is not a single operation, but you'll need to perform a series of operations one after the other, some of which have already been mentioned above. In short, it's a matter of creating a document, uploading the file and linking them.
Get Webservice IDs for folder #
To create a document, you need the Webservice ID of the folder in which the file will be placed. To obtain it, you can perform a query operation such as the following:
GET https://apps.kafinea.com/YourKafinea/webservice.php?operation=query&sessionName=sessionId&query=UrlEncodedQuery
Example query:
SELECT id FROM DocumentFolders WHERE foldername LIKE 'FolderName' LIMIT 1 ;
Create a document entity #
You need to create a Document entity so that you can add our file to it at a later date. To do this, you can use a create operation.
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=create
sessionName=sessionId // Obtained by the connection process
element=JSONDATA // JSON array of the entity (field name=field value)
elementType=Documents
Document fields to build the JSONDATA :
notes_title = TitleDocument // Name of the document entity
folderid = WebserviceID // Obtained during the previous operation
filename = FileName // Name of the file to be uploaded
filetype = FileMimeType // MIME type of the file to be uploaded (eg. application/pdf')
filesize = FileSize // File size in bytes
filestatus = 1 // Indicates active status
filelocationtype = I // Indicates internal storage
assigned_user_id = WebserviceID // Assigned user in Webservice format
FileUpload # operation
This operation allows you 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 products. In this case, replace attachmentType with "Image" and parentId with the product's Webservice ID.
POST https://apps.kafinea.com/YourKafinea/webservice.php
POST fields :
operation=FileUpload
sessionName=sessionId // Obtained by the login process
parentId=WebserviceID // WebserviceID document obtained in the last step
attachmentType=Attachment // Attachment or image
fileName=FileName // Name of the file to be uploaded
fileContents=Base64FileContents // The file should be base64 encoded
File recovery operation #
You can use the files_retrieve operation to retrieve files previously added to Kafinea. All you need is the file's WebserviceID (not to be confused with the WebserviceID of the Document entity). You 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 use our API! Please contact us if you need any further information.