API (Webservices)

Table of Contents

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,
              code: String
      }
}

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.

Réponse:

{
      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 set in the parameter 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.

What are your Feelings