Service d'export comptable automatisé (via API)

Aperçu de la fonctionnalité

Vous pouvez générer automatiquement des exports comptables depuis Cleemy à partir de votre système d'information. Ceci vous permet de récupérer les fichiers d'écritures comptables de Cleemy en réponse à une requêtes internet, sans intervention humaine, de manière à intégrer ces écritures dans votre logiciel de comptabilité ou votre ERP.

En pratique, le service est équivalent à la création manuelle :

  • Le fichier d'écritures généré est identique à celui qui aurait été généré manuellement depuis le module d'export comptable de Cleemy.
  • Les export générés de cette manière apparaissent normalement dans l'historique du module d'export comptable de Cleemy.

Cette fiche d'aide est destinée à votre DSI afin de les aider à exploiter ce service. Hormis la création du jeton d'authentification et une assistance pour pour vous expliquer le fonctionnement du service, la mise en place de ce service optionnel est de votre ressort.

 

Principes généraux

Le service repose sur des requêtes sécurisées ; le corps de la réponse de Cleemy contient le fichier d'écritures comptables dont vous pourrez disposer à votre guise.

Notez bien qu'une fois qu'une écriture a été exportée, elle ne peut plus être exportée, ceci afin d'éviter tout doublon en comptabilité. Si vous rencontrez de votre côté une erreur dans le traitement du fichier d'écritures que vous avez récupéré via le service, il vous faudra aller dans l'historique des exports comptables de Cleemy et supprimer l'export ayant échoué avant de relancer la requête.

L'appel au service est réalisé au moyen d'une requête à votre site Cleemy, l'URL à appeler étant de la forme :

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

Nous vous expliquons la syntaxe exacte à utiliser plus loin dans cette fiche.

 

Authentification et appels au service

Lors de l'appel, votre requête HTTPS doit être de type POST et contenir une clé d'authentification qui vous sera communiquée par Lucca, directement dans l'en-tête de la réponse.

Les requêtes appellent le sous-domaine de ilucca.net correspondant à votre entreprise. Par exemple, si votre instance se nomme "votre-societe ", vous ferez un POST (suivi des paramètres idoines) sur : 

https://votre-societe.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport

L'authentification passe par une clé d'application, qui est rattachée à un accès technique, qui prend la forme d'une rôle spécifique et qui apparaît dans le module d'administration des rôles de votre instance Lucca (/admin/roles),

La clé est à ajouter dans l'en-tête (header Authorization) de la requête sous la forme :

Authorization: lucca application=[votre clé]

Si vous avez plusieurs instances de Cleemy sur votre site, il faut intégrer le tag de l'instance dans l'URL. Par exemple, si vous voulez appeler le Cleemy "untel", il vous faut ajuster l'URL ainsi :

https://votre-societe.ilucca.net/cleemy-untel/services/v3/CreateExpenseAccountingExport 

 

Réponses possibles du service

La réponse du service peut présenter les codes de réponse suivants :

  • 200 : l'export a réussi et le corps de la réponse contient le fichier d'écritures
  • 204 : la requête a réussi, mais il n'y avait aucune écriture à exporter répondant aux filtres. Le corps de la réponse ne contient donc aucun fichier.
  • 400, 401, 404 : votre requête est erronée. Vérifiez notamment que vous n'avez pas oublié le paramètre legalEntityId (cf. plus loin)
  • 500 : le problème est de notre côté, contactez Lucca

Voici un exemple d'implémentation en C# qui enregistre le fichier récupéré sur un disque local D:\. Le paramètre url suit la syntaxe exposée plus loin.

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);
    }
}

 

Syntaxe des requêtes

La forme basique de l'URL à appeler est :

https://votre-societe.ilucca.net/cleemy/services/v3/CreateExpenseAccountingExport

A la suite de l’URL, vous ajoutez des paramètres en indiquant ? à la fin de l’URL et en séparant les paramètres avec le symbole &.

 

Entité légale

Le seul paramètre obligatoire est l'identifiant de l'entité légale dont vous demandez l'export. Il se forme ainsi :

legalEntityId=X

Remplacez le X par le numéro de l'entité légale désirée. Vous pouvez consulter les identifiants des entités juridiques en appelant depuis votre navigateur l'API suivante (sous réserve que vous ayez les droits de consultation dans votre rôle utilisateur) :

https://votre-societe.ilucca.net/api/legalentities

 

Filtres sur les dates des écritures

Dans Cleemy, tous les objets métiers (principalement des notes de frais) sont matérialisés sous la forme d'écritures comptables. Ces objets métiers sont rattachés à plusieurs dates :

  • Date de création (déclaration d'une note de frais)
  • Date d'approbation (fin du circuit de validation)
  • Date de contrôle (action réalisée dans le module de contrôle des notes des frais)
  • Date comptable (pour une note de frais, il s'agit par défaut de la date de création de la note de frais)

Ces filtres sont optionnels. Si vous ne les utilisez pas, toutes les écritures validées et contrôlées (mais n'ayant pas encore été exportées) seront incluses dans l'export.

Dans tous ces filtres, les dates sont à indiquer au format ISO, à savoir AAAA-MM-JJ.

Trois dates de filtrage sont disponibles :

  • declaredOn porte sur la date de création des écritures, c’est-à-dire la date de création des notes de frais.
  • approvedOn porte sur la date de validation de la note de frais. Si le circuit d’approbation a plusieurs étapes, la date retenue est celle de la dernière étape de validation.
  • controlledOn porte sur la date à laquelle le contrôle de la note de frais a eu lieu

Vous pouvez ajouter un qualificatif temporel sur ces filtres :

  • since,2015-11-30 garde uniquement les écritures ultérieures au 30 novembre 2015 inclus
  • until,2015-11-30 garde les écritures antérieures au 30 novembre 2015 non inclus.
  • between,2015-11-01,2015-11-30 garde les écritures comprises entre le 1 et le 30 du mois de novembre inclus.

 

Remplacement des dates comptables par défaut

Chaque opération réalisée dans Cleemy a par défaut une date comptable identique à la date de l'opération. Ainsi, les notes de frais ont par défaut une date comptable égale à leur date de déclaration par le collaborateur.

Vous pouvez modifier la date comptable des écritures d'un export à l'occasion de la création de l'export, grâce au paramètre accountingDate.

Ainsi, accountingDate=2015-30-11 modifie la date comptable de toutes les écritures exportées pour qu’elle soit égale au 30 novembre. Naturellement, ce paramètre n’accepte pas les qualificatifs until, since ou between.

 

Exemples

Voici quelques exemples, pour l’entité légale 1 du site lucca.

  • Exporter toutes les écritures validées et contrôlées, mais dont la date de validation est antérieures au 20 novembre inclus, sans modifier les dates comptables par défaut des écritures :

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

  • Celles pour lesquelles les notes de frais ont été déclarées entre le 1 et le 15 inclus, mais en remplaçant leur date comptable par le 30 novembre :

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

  • Et maintenant, les notes de frais déclarées avant le 10, validées avant le 15 et contrôlées avant le 20 (inclus), sans modifier leur date comptable :

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

 

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 0 sur 0
Vous avez d’autres questions ? Envoyer une demande

Commentaires