Bonnes pratiques d'intégration
Une intégration avec Acomba fonctionne bien quand elle respecte une contrainte d'Acomba : une seule opération à la fois. Cette page rassemble les règles qui en découlent, de la mise en place jusqu'à l'exploitation.
Avant de commencer#
Rythme des requêtes#
| Règle | Pourquoi |
|---|
| 1 ou 2 requêtes simultanées au maximum | Acomba traite une opération à la fois. Les requêtes en trop attendent leur tour : elles ne vont pas plus vite en parallèle et allongent l'attente des autres utilisateurs |
| Délai d'attente de 300 secondes côté client | Un calcul long (tableau de bord sur une année) ou une file chargée peut dépasser une minute |
| Traitements lourds hors des heures de bureau | Les utilisateurs d'Acomba partagent la même file que votre intégration |
Reprises avec délai croissant sur 500, 502, 503, 504 | Ce sont des indisponibilités temporaires. Respectez retry_after_seconds quand il est fourni. Voir Codes d'erreur |
Lire efficacement#
Listez en résumé (brief=true, par défaut) avec page_size=100, puis lisez la fiche complète seulement pour les fiches qui vous intéressent. La fiche complète est relue dans Acomba à chaque appel.
Filtrez côté API (code_prefix, name_prefix, is_active, from_datetime…) plutôt que de tout télécharger pour filtrer chez vous : le total et les pages tiennent compte des filtres.
Utilisez les tableaux de bord (âge des comptes, à recevoir, à payer, trésorerie, ventes, paie) au lieu de recalculer ces chiffres vous-même : ils sont calculés dans Acomba et gardés en cache. N'ajoutez force_refresh=true que si vous avez besoin d'un chiffre à la minute près.
Fraîcheur des données#
| Source | Fraîcheur |
|---|
Fiche lue par code ou par ID, fiche complète (brief=false) | Lue dans Acomba au moment de l'appel |
| Factures, transactions et paiements (clients et fournisseurs) | Lus dans Acomba au moment de l'appel |
Listes en résumé des fiches de référence, /helpers/updates | Copie locale, mise à jour en arrière-plan environ toutes les 15 minutes |
| Tableaux de bord | Cache, en général 4 heures pour une période en cours et 24 heures pour une période passée (1 heure pour les soldes bancaires et le stock). Le bloc cache de la réponse indique l'âge des chiffres et leur expiration |
Garder le lien avec Acomba#
Conservez l'id et le metadata.unique_id de chaque fiche liée. Acomba réutilise l'id d'une fiche supprimée ; seul unique_id est stable. Voir Concepts clés. Les codes métier peuvent être modifiés par un utilisateur d'Acomba : ne vous en servez pas comme clé.
Écrire en sécurité#
Vérifiez vos champs. Un champ inconnu est ignoré sans erreur. Validez vos corps de requête contre le schéma de l'endpoint (la référence de l'API donne le nom exact de chaque champ).
Une écriture à la fois, et attendez la réponse avant la suivante.
Après un délai dépassé sur un POST ou un DELETE, relisez avant de réessayer : l'opération a peut-être réussi. Seuls les lots de feuilles de temps (POST /api/payroll/time-sheets/write-batches) acceptent une clé d'idempotence qui empêche les doublons.
Un 409 signale souvent une fiche ouverte par un utilisateur dans Acomba ou un code déjà utilisé : réessayez plus tard ou changez de code.
La forme de la réponse varie selon le domaine (created_id pour les fiches, id pour les documents) : lisez la section « Responses » de l'endpoint.
Synchroniser avec votre système#
| Données | Méthode recommandée |
|---|
| Fiches de référence (clients, fournisseurs, produits, taxes, projets…) | GET /api/helpers/updates depuis la dernière synchronisation, puis lecture des fiches modifiées |
| Documents (factures, paiements, transactions) | Leurs listes filtrées par date, par exemple GET /api/customers/invoice-ar?from_datetime=… |
| Suppressions | /helpers/updates ne fournit pas la liste des fiches supprimées : faites une réconciliation complète périodique (liste en résumé comparée à vos fiches), par exemple chaque semaine |
Surveiller#
GET /system/health : état du service, d'Acomba et de la copie locale.
Journalisez, pour chaque erreur, l'heure, la route, le code HTTP et le corps de la réponse. Jamais la clé API.
Passez en revue les clés actives et leur dernière utilisation dans ExoConnect, et révoquez celles qui ne servent plus.
Modified at 2026-10-09 21:31:01
