Intégration API Twinfield : comment se connecter, configurer et suivre les bonnes pratiques

Twinfield, le logiciel comptable cloud de Wolters Kluwer, est largement utilisé par les PME et les cabinets comptables en Europe, notamment aux Pays-Bas, en Belgique et au Royaume-Uni. Intégrer Twinfield dans votre produit vous permet de :

• Récupérer des données financières : écritures comptables, factures, codes TVA et dimensions de compte
• Pousser des transactions et des écritures directement dans l'environnement Twinfield de vos clients
• Automatiser la réconciliation, les flux de pré-comptabilité et le rapprochement des factures
• Gérer les environnements multi-sociétés et multi-bureaux via l'architecture multi-cluster de Twinfield

Ce guide explique comment fonctionne l'API Twinfield, comment configurer votre intégration, les bonnes pratiques à suivre, et comment l'API Comptable Unifiée de Chift vous permet de vous concentrer sur ce qui compte vraiment.

Qu'est-ce que l'API Twinfield ?

L'API Twinfield est basée sur les Web Services SOAP, un protocole XML. Tous les endpoints sont hébergés sur une URL de cluster spécifique (https://api.<cluster>.twinfield.com) et exposent des définitions WSDL standard.

L'authentification se fait via OAuth2. Les clients fournissent un Client ID et un Client Secret pour obtenir des jetons d'accès. Point important : Twinfield est une plateforme multi-cluster, et l'URL du cluster doit être extraite du jeton JWT décodé (champ twf.clusterUrl) et utilisée pour toutes les requêtes SOAP suivantes.

Les principaux web services disponibles sont :

• ProcessXml (/webservices/processxml.asmx), le service central pour créer, mettre à jour et lire pratiquement toutes les entités via des messages XML. C'est le service principalement utilisé par Chift.
• Finder (/webservices/finder.asmx) — recherche de dimensions, bureaux et autres entités
• Matching (/webservices/matching.asmx), gestion du rapprochement des transactions
• Bank books / Cash books, services dédiés à la gestion des livres de trésorerie
• Declarations, traitement des déclarations TVA et fiscales
• Documents (/webservices/documentservice.svc), gestion des pièces jointes
• Deleted transactions (/webservices/deletedtransactionsservice.svc), récupération des transactions supprimées
• Pay and Collect, Budgets, Hierarchies, XBRL, services spécialisés

ProcessXml accepte des éléments XML racine tels que transaction, dimension, vat, salesinvoice, match, list, read et browse, entre autres.

🔗 Pour la documentation technique complète, rendez-vous sur le portail développeurs Twinfield.

{{CTA-1}}

Exemples de cas d'usage de l'API Twinfield

Gestion et prévision de trésorerie

Les plateformes de gestion de trésorerie peuvent récupérer les factures clients et fournisseurs en cours, les écritures comptables et les soldes de comptes directement depuis Twinfield pour alimenter des projections en temps réel. L'intégration bidirectionnelle permet aussi la pré-comptabilité : pousser des données de transaction enrichies vers Twinfield pour générer des écritures automatiquement.

Connecter un SaaS vertical à la comptabilité

Les plateformes SaaS verticales, comme les ERP construction, peuvent pousser des factures fournisseurs, factures clients et notes de frais vers Twinfield, générant des écritures comptables en quelques clics. Cela élimine la double saisie et réduit les erreurs pour les chefs d'entreprise et leurs comptables.

Automatisation des processus de recouvrement

Les plateformes de recouvrement peuvent extraire les créances ouvertes de Twinfield pour déclencher des relances automatiques et des workflows de recouvrement. Une fois le paiement reçu, le statut peut être renvoyé vers Twinfield pour mettre à jour les enregistrements comptables, sans aucune réconciliation manuelle.

Pour plus d'exemples d'intégrations comptables réussies, découvrez nos études de cas Chift.

Comment configurer votre intégration API Twinfield

Voici les étapes pour démarrer avec l'API Twinfield :

1. Enregistrez une application OAuth2 dans le portail développeurs Twinfield pour obtenir un Client ID et un Client Secret
2. Demandez la certification de votre ClientId, les intégrations non certifiées sont limitées à 5 % du quota de crédits standard, ce qui bloque tout usage en production
3. Effectuez le flux OAuth2 pour obtenir un jeton d'accès, puis décodez le JWT pour extraire twf.clusterUrl, c'est l'URL de base pour toutes les requêtes SOAP
4. Construisez votre couche de requêtes SOAP via le service ProcessXml. Chaque requête contient une payload XML dont l'élément racine correspond au type d'entité à manipuler (<transaction>, <salesinvoice>, <read>, etc.)
5. Gérez les environnements multi-cluster et multi-bureau : les clients Twinfield peuvent avoir plusieurs bureaux ou filiales, chacun nécessitant des requêtes séparées

La connexion initiale est accessible à la plupart des équipes de développement. Mais une intégration prête pour la production demande davantage : mappage de données cohérent entre bureaux, gestion du renouvellement de jeton, traitement des limites de débit, pagination des grands datasets, et maintenance continue au fil des évolutions de l'API Twinfield.

Bonnes pratiques pour l'intégration API Twinfield

• Extrayez toujours l'URL du cluster depuis le JWT. Twinfield est multi-cluster. Envoyer des requêtes SOAP au mauvais cluster entraîne des échecs d'authentification. Lisez twf.clusterUrl depuis le jeton décodé avant tout appel API.
• Faites certifier votre ClientId. Les intégrations non certifiées reçoivent seulement 5 % du quota standard — 50 crédits/min au lieu de 1 000. Ce n'est pas une limite contournable : c'est un plafond dur qui bloque tout workload de production. La certification est un prérequis, pas une option.
• Privilégiez les opérations de lecture. Les requêtes de type Query (<read>, <list>, <columns>, appels Finder) coûtent 1 crédit. Les opérations d'écriture coûtent 3 crédits. Un connecteur orienté lecture étend considérablement votre budget de crédits par minute.
• Batchez correctement, respectez les limites. Twinfield recommande un maximum de 25 éléments enfants par parent et 500 lignes par transaction ou facture. Dépassez ces seuils et vous risquez des échecs de traitement. Découpez les opérations d'écriture volumineuses en conséquence.
• Implémentez un backoff exponentiel sur les erreurs 429. Quand les limites de débit ou de concurrence sont atteintes, l'API renvoie un 429 Too Many Requests avec un en-tête Retry-After. Utilisez cette valeur comme base pour votre backoff exponentiel.
• Respectez les limites de concurrence. Au-delà des quotas de crédits par minute, Twinfield impose un maximum de 20 requêtes concurrentes par ClientId et 10 par combinaison ClientId+OrganisationId. Les traitements batch intensifs doivent être régulés en conséquence.

Connectez-vous à Twinfield, Exact Online, Sage, et bien d'autres avec une seule intégration

Construire une intégration directe avec Twinfield implique de gérer des requêtes SOAP, le routage de jeton multi-cluster, la logique de rafraîchissement OAuth2, la gestion des limites de crédit, la normalisation des données entre bureaux Twinfield, et la maintenance continue au fil des évolutions de l'API. Et il faut ensuite recommencer tout cela pour chaque outil comptable sur votre roadmap.

Avec l'API Comptable Unifiée de Chift, vous intégrez une seule fois et accédez à Twinfield, Exact Online, Pennylane, Sage, Xero, Odoo, MyUnisoft, et bien d'autres, via le même modèle de données normalisé.

‍

Ce que cela offre concrètement à votre équipe :

• Votre équipe engineering construit une seule intégration, puis reste concentrée sur votre produit principal
• Les nouveaux connecteurs s'activent en un clic, sans développement supplémentaire
• L'authentification, la gestion SOAP, le routage multi-cluster et le mappage de données sont entièrement gérés par Chift
• Monitoring, logging et maintenance à long terme inclus
• Support expert d'une équipe qui comprend à la fois les aspects techniques et métiers des intégrations financières

Votre équipe dev gagne du temps. Votre équipe sales peut dire oui à plus de demandes d'intégration. Et votre produit devient le choix évident pour les clients qui ont besoin que leurs données comptables circulent librement.

L'API Comptable Unifiée de Chift : une seule intégration, tous les connecteurs comptables essentiels.Twinfield n'est qu'une des nombreuses plateformes comptables accessibles via l'API Unifiée de Chift. Avec une seule intégration, votre application accède à des données cohérentes et normalisées depuis : Twinfield, Exact Online, Sage, Xero, Pennylane, MyUnisoft, Odoo, et bien d'autres.

Vous n'avez pas besoin de construire ou maintenir un connecteur unique pour chaque plateforme, Chift s'en charge. Adopter les APIs Unifiées de Chift simplifie votre développement, élimine la maintenance des intégrations et vous permet de scaler rapidement sur de nouveaux marchés.

Prêt à intégrer Twinfield et bien plus encore ? Réservez une démo et découvrez comment Chift peut accélérer vos intégrations comptables.

FAQ sur l'API Twinfield

Quels endpoints sont inclus dans l'API Twinfield ?

Le connecteur Twinfield de Chift expose un large ensemble d'endpoints standardisés via le service ProcessXml, notamment :

• Clients /clients
• Fournisseurs /suppliers
• Codes TVA /vat-codes
• Écritures comptables /journal-entries
• Plan comptable /accounts
• Transactions /transactions
• Factures de vente /invoices
• Dimensions (centres de coûts, projets) /dimensions

Consultez notre documentation API Twinfield pour la liste complète des routes disponibles.

Quelles sont les limites de débit de l'API Twinfield ?

Twinfield utilise un système de crédits (en place depuis décembre 2024). Les opérations de requête coûtent 1 crédit ; toutes les autres opérations coûtent 3 crédits. Voici les quotas par minute pour les intégrations certifiées :

PortéeCertifiéNon certifié (5 %)Par adresse IP1 000 crédits/min50 crédits/minPar ClientId1 000 crédits/min50 crédits/minPar OrganisationId1 000 crédits/min50 crédits/minPar ClientId + OrganisationId500 crédits/min25 crédits/min

Des limites de concurrence s'appliquent séparément : max 20 requêtes simultanées par ClientId, max 10 par combinaison ClientId+OrganisationId. Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Credited et Retry-After sont inclus dans les réponses quand les limites sont atteintes.

Twinfield supporte-t-il REST ou uniquement SOAP ?

L'API principale de Twinfield est exclusivement SOAP. Il n'existe pas d'API REST native pour les données comptables et les transactions. Toutes les opérations sur les entités passent par le service SOAP ProcessXml via des payloads XML. Cela ajoute une complexité d'implémentation par rapport aux API REST modernes : votre intégration doit gérer la découverte WSDL, la sérialisation XML et le formatage des enveloppes SOAP.

Qu'est-ce que le multi-cluster dans Twinfield, et pourquoi est-ce important ?

Twinfield héberge les données clients sur plusieurs clusters de serveurs. Chaque environnement client réside sur un cluster spécifique, et l'URL de base de l'API varie selon le cluster. Si vous envoyez des requêtes au mauvais cluster, l'authentification échoue, même avec un jeton valide. Vous devez lire le claim twf.clusterUrl depuis le JWT décodé et l'utiliser comme URL de base pour tous les appels SOAP. C'est l'une des erreurs d'intégration les plus fréquentes.

Pourquoi la certification du ClientId est-elle importante ?

Les ClientIds non certifiés sont limités à 5 % du quota de crédits standard de Twinfield, soit 50 crédits par minute au lieu de 1 000. À 3 crédits par opération d'écriture, cela représente environ 16 requêtes d'écriture par minute avant d'atteindre la limite. Pour tout connecteur de production gérant des volumes de données clients réels, ce plafond rend l'intégration non viable sans certification. Il est fortement recommandé de demander la certification à Twinfield dès le début de votre développement.