Best Practices

Introduction

Cette section synthétise les principales règles à respecter pour l’implémentation de l’appel à l’API Sage Business Cloud Comptabilité dans vos applications standard ou spécifiques.

Authentification

Un tutoriel complet vous explique comment implémenter l’authentification pour l’API Sage Business Cloud Comptabilité, nous mettons également à votre disposition une application d’exemple d’utilisation de l’API en C# NET incluant la logique de connexion et déconnexion.

Relation entre le bureau, les sociétés et les utilisateurs

Pour accéder aux données d’une ressource, il est préalablement nécessaire de récupérer l’identifiant de la base société contenant les données.
La route companies permet de récupérer la liste des sociétés de l’utilisateur courant et, pour chaque société, son identifiant.
L’exemple C# NET démontre le choix d’une société si plusieurs sociétés sont disponibles pour l’utilisateur courant.

Pagination

La notion de pagination est fondamentale.
Vos développements doivent être en phase avec le nombre maximal d’enregistrements que l’API Sage Business Cloud renvoie à chaque appel.
L’exemple C# Net illustre la pagination à travers un exemple de consultation de clients.

Volume des données renvoyées

Par défaut chaque requête de lecture renvoie la totalité des propriétés d’une ressource.
Ceci offre l’avantage de ne pas être obligé de spécifier les propriétés nécessaires mais a l’inconvénient majeur de renvoyer des données qui peuvent être totalement inutiles dans le contexte d’utilisation.
Privilégiez toujours l’utilisation de $select.
Concepts clés / OData - Paramètres de requêtes et rôle

{url API}/{datasetId}/ecritures?$expand=journal($select=code),compte($select=numero,intitule),tiers($select=numero)&$select=date,piece,intitule,sens,montant

Propriétés de Navigation

Les propriétés de navigation permettent de définir les relations entre les différentes ressources.
C’est donc par le biais de ces propriétés qu’il sera possible d’associer une écriture à un journal, un compte général, etc. ou encore associer un compte principal et une devise à un client.
L’exemple C# .NET illustre l’utilisation des propriétés de navigation pour l’ajout d’un client ou l’impord d’écritures comptables.

Limites d’utilisation de l’API Sage Business Cloud Comptabilité

Pour garantir la disponibilité et l’intégrité de l’API Sage Business Cloud Comptabilité à tout moment, une limite de nombre d’appels a été définie.
La limite de débit est définie pour chaque application client unique avec les limitations suivantes:

1. Limite de débit de 1 296 000 requêtes par application et par jour.
2. Maximum de 150 demandes simultanées à tout moment (par application)

En cas de dépassement d’une des limites, l’API Sage Business Cloud Comptabilité renverra un code erreur HTTP 429 (Too many requests). Nous vous recommandons de tenir compte de cet éventuel code erreur dans le développement de votre application afin de prévenir l’atteinte d’une des limites précitées.

Mise en cache

Le dépassement des limites de l’API peut être problématique pour toute application ou expérience utilisateur.
Pour vous assurer que votre application est aussi efficace que possible, la prise en compte des types de données que vous obtenez et gérez devrait vous aider à mettre en évidence les types de données statiques ou rarement mises à jour.
Les données statiques sont constantes et peuvent être partagées pour tous les utilisateurs de la même langue sans nécessité de les relire systématiquement.

Accès concurrentiel

Pour aider et maintenir l’intégrité des données, une attention supplémentaire doit être accordée lorsque des requêtes POST parallèles sont effectuées.
Nous vous recommandons de ne pas utiliser de requêtes parallèles lors de la création de données susceptibles d’avoir des références uniques ou d’utiliser la numérotation séquentielle générée par le système.
Évitez notamment de faire des requêtes POST parallèles lors de l’ajout d’écritures.

Stockage des jetons d’Authentification

Le stockage des jetons d’autorisation et d’actualisation générés à partir du flux OAuth 2.0 est un sujet largement discuté sur le web.
Les solutions et les conseils varient en fonction du type d’application que vous avez créée, la documentation OAuth 2.0 est une bonne référence aux modèles que votre flux doit suivre et sont basés sur le type d’application.
Dans la mesure du possible, essayez de réduire le nombre de fois qu’un utilisateur doit se réauthentifier dans votre application.
Par exemple, une application Web native avec son propre stockage backend devrait être en mesure de stocker en toute sécurité des jetons et d’autoriser l’accès des utilisateurs sans avoir à s’authentifier à nouveau après chaque session.

Non-concordance de type

La non-concordance de type peut être frustrante pour l’utilisateur et peut également être un facteur de dépassement des limites de consommation de l’API.
L’usage abusif le plus courant des types concerne les règles de gestion non respectées.

Métadonnées

Vous pouvez récupérer les métadonnées de l’API Sage Business Cloud Comptabilité pour développer des applications avec appels dynamiques, par exemple pour prévoir un import/export paramétrable ou un générateur de formulaires.

• Un exemple ainsi que son code source, sont disponibles dans le manuel de référence de l’API Sage Business Cloud Comptabilité, il permet de naviguer dans l’ensemble des métadonnées.
• L’exemple C# .NET offre un outil de requêtage permettant de choisir les ressources. Il illustre aussi l’utilisation des métadonnées.

Localisation

• les codes d’erreur HTTP renvoyés par l’API sont en anglais et nécessitent l’intervention du développeur pour traduire et localiser en français.
• les erreurs métier renvoyées par l’application à travers l’API sont en français.

Longueurs des champs et énumérations.

Il appartient au développeur de respecter les longueurs des propriétés de type string ainsi que les valeurs des énumérations.
Le manuel de référence de l’API Sage Business Cloud Comptabilité décrit précisément les longueurs maximales, les valeurs des énumérations, les valeurs obligatoires, etc.
Vue d’ensemble ressources API

Bases de test

Nous recommandons de ne jamais tester vos développements sur des données de production.
Depuis le bureau vous pouvez créer pour vos tests trois types de base société, l’accès à Sage Business Cloud Comptabilité pour ces sociétés se fera directement depuis le bureau :

1. Base vierge que vous pourrez alimenter selon vos besoins de tests. Donner un nom quelconque à la société lors de sa demande de création.
2. Base de démonstration avec un jeu limité de données. Donner à la société le nom BIJOU, après création vous pourrez renommer la société.
3. Base anonymisée à forte volumétrie pour test de montée en charge et tests sur gros volumes de données. Donner à la société le nom BASE2GOSQL100CV7, après création vous pourrez renommer la société.

Erreurs du client HTTP 4xx

Ces erreurs sont générées en raison de données non valides dans la demande. Dans la plupart des cas, le message d’erreur devrait aider à résoudre le problème. Concepts clés / Codes de réponse HTTP

Les erreurs HTTP 403 forbidden seront renvoyées sur les points de terminaison de l’API Sage Business Cloud Comptabilité lorsque l’utilisateur ne dispose pas des autorisations suffisantes pour exécuter l’action demandée.
Cela se produit généralement lorsque l’utilisateur n’est pas autorisé à utiliser Sage Business Cloud Comptabilité.
Il est recommandé de gérer les erreurs 403: lorsque votre application reçoit une réponse 403 à chaque appel, il doit rejeter le jeton d’accès et d’actualisation et demander une nouvelle autorisation à l’utilisateur.