Follow

Automated accounting export service

Overview of features

You can automatically generate accounting exports using Cleemy from your information system. This allows you to retrieve accounting entry files from Cleemy with a single internet request without human intervention by integrating entries in your accounting software or your ERP.

In practice, this service is equivalent to manually generating accounting exports:

  • The generated entry file is identical to a manually generated one from the Cleemy accounting export module.
  • The exports generated in this way appear the same in Cleemy’s accounting export module’s history.

This support page is intended for your IT management in order to help them use this service. Apart from the creation of a security token and an aid to explain to you the service’s features, the implementation of this optional service is up to you.

 

General principles

The service relies on secured requests; the body of Cleemy’s response contains the accounting entry file which you will have at your disposal.

Please note that once an entry has been exported, it can no longer be exported. This prevents duplicates in accounting. If you come across an error in the processing of an entry file that you retrieved via the service, you must go into Cleemy’s accounting export’s history and delete the unsuccessful export before resending the request.

The service call is performed through a request to your Cleemy site, the URL to be called takes the following form:

https://your-company.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport?legalEntityId=1&declaredOn=until,2015-11-30

We will explain the exact syntax to use later in this page.

 

Authentication and service calls

During the call, your HTTPS request must be a POST and contain an authentication key that will be provided to you by Lucca in the header of the response.

The requests call the ilucca.net subdomaine that corresponds with your company. For example, if your product is named “your-company,” you will make a POST (following the appropriate parameters) at:

https://your-company.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport

The authentication is performed via an application key which is linked to a technical access which takes the form of a specific role and appears in the administration roles module in your Lucca product.

The key is added in the header (Authorization header) of the request and takes the following:

Authorization: lucca application=[your key]

If you have several Cleemy products on your site, you must add the product’s tag in the URL. For example, if you want to call Cleemy “xxxx”, you must adjust the URL like this:

https://your-company.ilucca.net/cleemy-xxxx/services/v3/CreateExpenseAccountingExport

 

Possible responses from the service

The response from the service can provide the following response codes:

  • 200: The export was successful, and the body of the response will include the entry file.
  • 204: the request was successful, but there was no entry to export matching the filters. The body of the response will therefore not contain a file.
  • 400, 401, 404: your request contains errors. Please verify that you have not forgotten the legalEntityld parameter (cf. see below).
  • 500: the problem exists in Lucca, please contact us.

Here is an example of an implementation in C# that has stored the retrieved file on the D:\ local drive. The URL parameter follows the syntax shown later.

static void GenerateExport(string url, string token)

{

   using (var wc = new WebClient())

   {

       wc.Headers["Authorization"] = "Lucca application=" + token;

       var exportBody = wc.UploadString(url, "POST", "");

       File.WriteAllText(@"D:\export.csv", exportBody);

   }

}

 

Request syntax

The basic form of the URL to be called is:

https://your-company.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport

Following the URL, you must add the parameters by including a “?” at the end of the URL and by separating the parameters with the “&” symbol.

Legal entity

The only mandatory parameter is the legal entity’s ID from which you request the export. It appears like this:

legalEntityId=X

Repace the “X” with the number of the desired legal entities. You can consult the identifiers of legal entities by calling the following API from your web browser (on the condition that you have consultation rights in your user role):

https://your-company.ilucca.net/api/legalentities

 

Entry date filters

In Cleemy, all business objects (mainly expense reports) are materialized as accounting entries. These business objects are linked to several dates:

  • Creation date (declaration of an expense report)
  • Approval date (end of the approval process)
  • Control date (action performed in the control module of expense reports)
  • Posting date (for an expense report, it is by default the creation date of the expense report)

These filters are optional. If you do not use them, every approved and controlled entry (but not yet exported) will be included in the export.

With all of these filters, the dates will follow the ISO format (YYYY-MM-DD).

Three date filters are available:

  • declaredOn concerns the creation date of entries. In other words the creation date of expense reports.
  • approvedOn concerns the approval date of the expense report. If the approval process has several steps, the date used is the one when the last step of the approval process took place.
  • controlledOn concerns the date when the expense report’s control took place.

You can add a temporary qualifier to these filters:

  • since,2015-11-30 only includes entries made after November 30, 2015 (the 30th included).
  • until,2015-11-30 only includes entries made before November 30,2015 (the 30th not included).
  • between,2015-11-01,2015-11-30 includes entries between the 1st and 30th of November (both the 1st and 30th are included).

 

Replacing default posting dates

Each operation performed in Cleemy has a default posting date which is the same as the date of the operation. Therefore, expense reports have by default a posting date that is the same as the date they were declared by an employee.

You can modify the posting date of an export’s entries when creating the export thanks to the accountingDate parameter.

 

Therefore, AccountingDate=2015-30-11 will modify the posting date of all exported entries to November 30. Of course this parameter does not accept the until, since or between qualifiers.

 

Examples

Here are a few examples for the legal entity 1 from the Lucca site.

  • Export all approved and controlled entries which were approved before November 20 (the 20th included) without modifying the default posting dates of the entries:

https://lucca.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport?legalEntityId=1&approvedOn=until,2015-11-20

  • To export those for which the expense reports were declared between the 1st and 15th (both included) and to replace their posting date with November 30:

https://lucca.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport?legalEntityId=1&declaredOn=between,2015-11-01,2015-11-15&accountingDate=2015-11-30

  • And now, the expense reports declared before the 10th, approved before the 15th, and controlled before the 20th (included) without modifying their posting dates:


https://lucca.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport?legalEntityId=1&declaredOn=until,2015-11-10&approvedOn=until,2015-11-15&controlledOn=2015-11-20

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk