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

Un dossier Acomba de test pour développer et essayer les écritures.

Un utilisateur Acomba dédié à ExoConnect, limité aux modules dont l'intégration a besoin. L'API n'ira jamais au-delà de ses droits.

Une clé API par application, en lecture seule si l'application ne fait que lire, avec une date d'expiration. Voir Authentification.

Une fenêtre d'arrêt dans ExoConnect pendant la sauvegarde d'Acomba : l'API répond alors 503 avec le délai d'attente, et vos traitements reprennent ensuite.

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.

Avant de commencer#

Rythme des requêtes#

Lire efficacement#

Fraîcheur des données#

Garder le lien avec Acomba#

Écrire en sécurité#

Synchroniser avec votre système#

Surveiller#