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.