Comment on a relié les paiements internationaux à la comptabilité – et à quoi ressemblait vraiment le processus.
Le problème : deux systèmes qui ne se parlent pas
Les PME suisses qui travaillent avec des fournisseurs et des clients à l’étranger connaissent bien ce problème : Amnis gère parfaitement les paiements multidevises, Xero tient les comptes avec précision, mais les deux systèmes ne communiquent pas entre eux.
Résultat ? Les équipes financières saisissent les transactions à la main, rapprochent les paiements manuellement, et passent des heures sur des tâches que le logiciel devrait gérer tout seul.
On a décidé de créer une vraie intégration Amnis-Xero – pas une solution bricolée, mais un connecteur solide et prêt pour la production, capable de gérer la complexité multidevises, de s’adapter à plusieurs clients et de se comporter correctement même quand quelque chose tourne mal.
Comprendre les API
Amnis et Xero proposent tous deux des API REST avec authentification OAuth 2.0, mais leur comportement est assez différent dans la pratique.
L’API Amnis est bien documentée et simple d’accès. Les points de terminaison clés dont on avait besoin :
- Point de terminaison transactions – récupère les paiements effectués, les virements entrants et les dépenses par carte
- Point de terminaison comptes – fournit les soldes multidevises et les détails IBAN
- Point de terminaison des taux de change – pour un suivi précis de l’historique des conversions
La gestion des jetons était indispensable dès le départ, car l’API utilise des jetons de rafraîchissement.
L’API de Xero est plus aboutie, mais aussi plus complexe. On s’est concentrés sur :
- Transactions bancaires – création de transactions de dépenses et de recettes
- Comptes bancaires – mappage des comptes Amnis vers les comptes bancaires Xero
- Contacts – mise en correspondance ou création d’enregistrements fournisseurs/clients
- Catégories de suivi – centres de coûts et affectation aux projets
Le piège principal : les jetons Xero expirent au bout de 30 minutes, ce qui rend la gestion des actualisations absolument critique – surtout pour les processus en arrière-plan.
Faire le pont entre deux modèles de données différents
C’est là que les choses sont devenues vraiment intéressantes. Amnis et Xero modélisent les données financières de manière très différente.
| Concept | Amnis | Xero |
|---|---|---|
| Gestion des devises | Comptes multidevises natifs | Devise de base unique avec conversion |
| Types de transactions | Structure plate avec champ de type | Points de terminaison distincts par type |
| Catégorisation | Minimale | Plan comptable riche |
| Contacts | Informations de base sur les contreparties | Fiches de contact complètes avec historique |
On avait besoin d’une couche de traduction capable de faire correspondre ces modèles tout en préservant l’intégrité des données et en gérant les cas limites – pas seulement le scénario idéal.
Approche de développement : mappage d’API assisté par IA
L’un des aspects les plus utiles de ce projet, c’est l’utilisation de l’automatisation IA pour accélérer le travail de mappage des API – une tâche qui prendrait normalement plusieurs jours à un développeur.
On a entré les spécifications des deux API dans Claude et on lui a demandé d’identifier les champs correspondants entre les deux systèmes, les transformations nécessaires (types de données, formats, énumérations), les cas limites et les points de perte de données potentiels, ainsi que les champs manquants qui nécessiteraient des valeurs par défaut ou une saisie de l’utilisateur.
Résultat : un premier mappage solide en quelques heures plutôt qu’en plusieurs jours.
Pour le travail répétitif d’écriture des fonctions de transformation, on a utilisé l’IA pour générer des implémentations initiales. La clé, c’était de traiter le résultat de l’IA comme un point de départ, pas comme un produit fini – chaque fonction générée a quand même été soumise à une revue de code, à des tests de cas limites et à une consolidation pour la production.
Architecture : workers en arrière-plan et pipeline cohérent
La synchronisation en temps réel n’était pas envisageable ici. Les transactions Amnis prennent du temps à être réglées, Xero a des limites de débit, et on avait besoin d’une gestion des échecs propre. Une architecture de workers en arrière-plan s’imposait.
Chaque cycle de synchronisation suit le même pipeline en six étapes :
- Récupération – extraire les nouvelles transactions d’Amnis depuis la dernière synchronisation
- Transformation – convertir au format Xero, résoudre les contacts, mapper les comptes
- Validation – vérifier l’exhaustivité des données, signaler les anomalies
- Push – créer les transactions dans Xero via l’API
- Confirmation – vérifier la création, enregistrer les identifiants de transaction Xero
- Journal – enregistrer les résultats de la synchronisation, le timing, les éventuels problèmes
L’idempotence était essentielle tout au long du processus. Exécuter deux fois la même synchronisation ne doit pas créer de doublons. On a géré ça grâce à :
- Empreinte des transactions – chaque transaction Amnis reçoit un hachage déterministe
- Suivi de l’état de synchronisation – on enregistre quelles transactions ont été poussées avec succès
- Correspondance des références Xero avant de créer quoi que ce soit de nouveau
Gestion des erreurs : concevoir pour la réalité
Les choses tournent mal. Les API expirent, les jetons expirent, les données sont mal formées, les limites de débit sont atteintes. On a classé les erreurs en quatre catégories qui déclenchent chacune une réponse différente :
| Catégorie | Exemples | Réponse |
|---|---|---|
| Transitoire | Timeout réseau, erreurs 503, limites de débit | Réessayer avec un backoff exponentiel |
| Auth | Jeton expiré, accès révoqué | Actualiser le jeton, alerter en cas d’échec |
| Données | Champ obligatoire manquant, format invalide | Ignorer la transaction, marquer pour révision |
| Système | Base de données en panne, plantage du worker | Alerter immédiatement, mettre le traitement en pause |
Pour les erreurs transitoires, on utilise un backoff exponentiel avec variation : 1 minute, puis 5, puis 30, puis 2 heures. Après quatre échecs, la transaction est marquée comme ayant échoué et signalée pour un examen manuel.
Les notifications passent par trois canaux – Slack pour les alertes critiques en temps réel et les résumés quotidiens, les digests par e-mail pour les rapports hebdomadaires non urgents, et les alertes du tableau de bord dans l’application pour les administrateurs de locataires.
Interface de gestion multi-locataires
Comme cette intégration d’outils devait servir plusieurs clients depuis une seule interface, on a développé une interface de gestion pour gérer la configuration et la surveillance de tous les locataires.
L’intégration des locataires comprend :
- Les flux de connexion OAuth pour Amnis et Xero
- Le mappage des comptes (quels comptes Amnis correspondent à quels comptes bancaires Xero)
- Les règles de catégorisation par défaut
- Les préférences de correspondance des contacts
Le tableau de bord de surveillance affiche :
- État de la synchronisation – dernière synchronisation réussie, transactions en attente, nombre d’erreurs
- Volume de transactions – nombre et valeur des transactions quotidiennes/hebdomadaires/mensuelles
- Indicateurs de santé – connectivité API, état des jetons et latence de traitement
Chaque locataire dispose aussi de paramètres configurables :
- Fréquence de synchronisation – à quelle fréquence récupérer les nouvelles transactions
- Règles de catégorisation basées sur la contrepartie ou des modèles de description
- Préférences de notification – qui est alerté et quand
- Seuils de vérification manuelle pour les transactions importantes ou inhabituelles
Chaque action est consignée – modifications de configuration, interventions manuelles, cycles de synchronisation, erreurs et résolutions. Cette piste d’audit s’est révélée indispensable, non seulement pour le débogage, mais aussi pour les clients qui doivent expliquer leurs processus comptables à des auditeurs.
Leçons apprises
La documentation des API ment parfois
Les deux API présentaient des cas où le comportement réel différait de la documentation. On a appris à se fier davantage aux tests d’intégration qu’à la doc, et à intégrer des contrôles défensifs pour les réponses inattendues.
La gestion des devises, c’est vraiment compliqué
Que se passe-t-il quand un paiement en EUR arrive sur un compte en CHF ? Quel taux de change utilises-tu – celui d’Amnis ou celui de Xero ? Et qu’en est-il des décalages entre la date de transaction et la date de valeur ? On a passé beaucoup de temps à régler ça, et les cas limites n’arrêtaient pas d’apparaître.
L’observabilité, ça vaut l’investissement
Quand un problème survient à 2h du matin, tu veux pouvoir le diagnostiquer depuis les logs sans avoir à reproduire l’incident. On enregistre chaque appel API, chaque décision de transformation, chaque erreur – avec suffisamment de contexte pour comprendre ce qui s’est passé. Ça nous a rendu service à maintes reprises.
Les utilisateurs ont des workflows existants
L’intégration n’existe pas en vase clos. Les équipes financières ont des processus d’approbation et des exigences de reporting qui sont antérieurs à ton connecteur. Comprendre ces workflows et s’y adapter – plutôt que de les perturber – est aussi important que la mise en œuvre technique.
Résultats
L’intégration traite désormais des milliers de transactions par mois pour plusieurs locataires. Voici les principaux résultats :
- Gain de temps – les équipes financières déclarent gagner 5 à 10 heures par semaine sur la saisie manuelle des données
- Réduction des erreurs – les écarts de rapprochement sont tombés à presque zéro, contre un taux d’erreur de 3 à 5 % avec la saisie manuelle
- Visibilité en temps réel – les comptes sont à jour dans les 15 minutes suivant la finalisation du paiement
- Évolutivité – l’ajout d’un nouveau client prend quelques minutes, pas plusieurs jours
Et la suite ?
On continue d’améliorer l’intégration avec une catégorisation plus intelligente (en s’appuyant sur les modèles de l’historique des transactions pour l’affectation automatique des comptes), des alertes prédictives pour les transactions inhabituelles, et un rapprochement étendu qui fait correspondre les transactions Amnis aux factures Xero pour une affectation automatique des paiements.
Si tu gères des outils métier déconnectés et que tu passes du temps à saisir des données manuellement entre les systèmes, c’est exactement ce genre de projet qu’on développe. Jette un œil à nos services d’intégration d’outils pour voir comment on aborde la connexion de plateformes comme Amnis et Xero – et ce que ça pourrait donner pour ta configuration.
