L'API REST et l'API XML de Sage Intacct : comment Velixo prend en charge les deux

Sage Intacct gère l'ensemble de vos opérations financières et propose deux méthodes pour importer et exporter des données. L'API XML existe depuis des années et prend en charge la plupart des intégrations dont dépendent déjà les équipes financières. L’API REST de Sage Intacct est plus récente, et Sage y intègre désormais tous ses nouveaux objets et fonctionnalités. Si vous créez des rapports à partir d’Intacct, la différence entre ces deux interfaces détermine les données auxquelles vous pouvez accéder et la fluidité avec laquelle vous pouvez les exploiter. Velixo lit les deux à partir du même classeur ; vous n’avez donc plus à choisir entre elles dès le départ.

Deux API sur la même plateforme

Les deux API lisent et écrivent les données de la même entreprise. Elles diffèrent par leur architecture. L'API XML utilise des documents XML structurés et s'authentifie à l'aide d'identifiants de services Web. L’API REST utilise les verbes HTTP standard, le format JSON et le protocole OAuth. De nouveaux objets et fonctionnalités sont régulièrement ajoutés à l’API REST. Chaque version trimestrielle les intègre, et Sage publie une correspondance entre les objets XML et REST afin de faciliter les intégrations. L’API XML reste en place. Ses fonctions spécifiques aux objets sont qualifiées d’« héritées » et ne seront plus améliorées ; quelques tâches continuent toutefois d’être exécutées via cette API, car c’est la seule option disponible.

Ce que l'API REST de Sage Intacct modifie en matière de mises à jour

C'est au niveau du modèle de mise à jour que les deux API se distinguent le plus dans le travail quotidien. Dans l’API XML, une mise à jour générique d’une transaction traite l’ensemble des lignes comme un remplacement complet. Modifiez un champ sur une ligne d’écriture comptable et vous renvoyez toutes les lignes de cette écriture. Omettez une ligne dans la charge utile et Intacct la supprime. Les écritures comptables accentuent encore cette différence, puisqu’elles ne disposent d’aucune fonction de mise à jour partielle : ainsi, l’écriture entière est renvoyée à chaque fois que vous la modifiez.

L'API REST attribue à chaque ligne sa propre clé et son propre point de terminaison. Vous pouvez utiliser la méthode PATCH sur une seule ligne de facture, modifier un champ et laisser tout le reste inchangé. Si vous omettez une ligne, celle-ci est conservée. La suppression d'une ligne nécessite une instruction de suppression explicite. Pour les entrées comportant de nombreuses affectations et un nombre élevé de lignes, cela fait la différence entre une modification ciblée et la reconstruction de l'intégralité de l'enregistrement.

Là où l'API XML continue d'assumer la charge

REST couvre désormais la quasi-totalité des objets d'application standard. La cartographie des objets de Sage présente les équivalents dans les modules Grand Livre, Comptabilité fournisseurs, Comptabilité clients, Saisie des commandes, Gestion des stocks et Projets. Deux facteurs expliquent que l’API XML reste largement utilisée. Sage précise que les fonctions héritées spécifiques aux objets ne seront pas améliorées et que, dans certains cas, elles constituent les seules fonctions disponibles pour accomplir une tâche. De plus, la carte des objets couvre les modules financiers et opérationnels sans répertorier les constructions de Platform Services ; par conséquent, la définition d’objets personnalisés et la création de Smart Rules et de Smart Events s’effectuent toujours via la couche XML et Platform Services. Une équipe qui développe sa propre intégration conserve une voie XML parallèlement à la voie REST afin de tout couvrir.

Objets exposés exclusivement par l'API REST de Sage Intacct

Comme les nouveaux développements s'effectuent via REST, plusieurs objets n'existent que là-bas et nulle part ailleurs. La gestion des immobilisations s'effectue entièrement via REST. Les prévisions relatives aux travaux en cours de construction, y compris les périodes et les projets concernés, sont hébergées dans REST. Les écritures fiscales relatives aux factures, aux notes de facturation et aux écritures comptables sont accessibles en tant qu'enregistrements distincts dans REST, où l'API XML les conserve au sein de la transaction parente. Si vos rapports s'appuient sur l'un de ces éléments, REST est le moyen d'accéder aux données.

Comment Velixo exploite l'API REST de Sage Intacct

Velixo lit les deux API depuis Excel, et le nom de la fonction vous indique laquelle vous utilisez. La famille SI.QUERY communique avec l’API XML. La famille SI.XQUERY communique avec l’API REST. Le « X » désigne le chemin REST, et c’est ainsi que vous accédez aux objets que Sage n’expose que par ce biais. Vous ne vous engagez pas sur une API dès le début d’un projet pour vous en contenter ensuite. Vous choisissez la fonction qui correspond à l’objet, formule par formule.

SI.XQUERY extrait un objet REST vers une plage de données ou un tableau Excel. Il suffit de le pointer vers un objet tel que « construction-forecasting/wip-period », d’ajouter un filtre et de sélectionner vos colonnes. SI.XOBJECTDEFINITION renvoie les champs, les types de données, les indicateurs obligatoires et les valeurs valides pour cet objet, ce qui vous permet de travailler à partir des noms de champs réels plutôt que de deviner. SI.XEXPANDOBJECTRANGE répertorie les objets que vous pouvez interroger. SI.XQUERYLOOKUP renvoie un seul champ pour un enregistrement lorsque c’est tout ce dont vous avez besoin. SI.XQUERYFILTER construit l’expression de filtrage. Depuis la version 2025.7, SI.XQUERY prend également en charge les fonctions SUM, COUNT, MIN, MAX et AVERAGE, ce qui vous permet de regrouper et de calculer des totaux directement dans la requête.

Voici un aperçu des périodes de travaux en cours (WIP) publiées, se terminant au premier trimestre 2025 :

=SI.XQUERY(
  "Sage",
  "construction-forecasting/wip-period",
  "periodEndDate >= '2025-01-01' and periodEndDate <= '2025-03-31' and state = 'posted'",
  "key, periodName, state, periodEndDate"
)

Le résultat est mis à jour en même temps que le classeur, ce qui permet aux chiffres de rester à jour au fur et à mesure que la période avance.

Un seul classeur, les deux API, pas de recompilation

Sage publie ses nouveaux objets via REST. Une équipe qui développe sa propre intégration autour d’une API doit effectuer un travail supplémentaire lorsqu’elle a besoin d’un objet que seule l’autre API expose. Dans Velixo, les deux API s’appuient sur des formules Excel. Les rapports existants continuent de fonctionner grâce aux fonctions SI.QUERY. Les objets disponibles uniquement via REST deviennent accessibles via SI.XQUERY dès leur intégration dans l’API REST, sans projet de migration ni code à maintenir. Il suffit d’écrire une formule pour rester en phase avec la feuille de route de Sage.

C'est là que réside l'aspect stratégique. La coexistence de deux API impose aux équipes d'intégration un surcroît de travail en temps réel et de maintenance. Pour une équipe financière travaillant sous Excel, cela se résume à une colonne que l'on ajoute au besoin.

Mettez-le à profit dans votre prochain rapport

Comparez ces résultats avec vos propres données. Pointez SI.XQUERY vers un objet exclusivement REST, tel que la gestion des immobilisations ou les prévisions des travaux en cours, et intégrez-les dans un rapport qui s'actualise en même temps que le classeur, tandis que vos rapports SI.QUERY existants continuent de s'exécuter. Demandez une démonstration pour découvrir cette fonctionnalité avec un expert Velixo, ou commencez par consulter les exemples de rapports Sage Intacct et le guide de référence des fonctions disponibles dans le centre d'aide Velixo.