Connecter une application à un logiciel de comptabilité : CSV, API, MCP

Il existe quatre façons de faire passer les données de votre application dans un logiciel de comptabilité : exporter un CSV et l'importer, utiliser une intégration native construite par l'éditeur, appeler une API publique depuis votre propre code, ou laisser un assistant IA travailler à travers un serveur MCP. Pour tout ce qui tourne chaque jour, l'API est le choix honnête, et une bonne connexion API se résume à cinq décisions : quoi synchroniser, dans quel sens, comment rendre les nouvelles tentatives sûres (idempotence), comment être informé des changements (webhooks) et où vit la clé.

Les quatre options, et quand chacune suffit

Le CSV suffit pour une remise trimestrielle à l'expert-comptable. Une intégration native suffit lorsque les deux produits que vous utilisez sont justement les deux produits que l'éditeur a connectés. Une API est ce dont vous avez besoin lorsque les données naissent dans votre propre système et doivent arriver complètes, chaque jour, sans intervention humaine. Le MCP est une cinquième couche par-dessus l'API, pour les personnes qui posent des questions à un assistant plutôt que d'écrire du code.

Les options ne s'excluent pas. Une configuration courante est l'API pour le flux quotidien, le MCP pour le fondateur qui demande « qui n'a pas payé ? », et un export CSV en fin d'exercice pour le logiciel de l'expert-comptable.

Quoi synchroniser : clients, factures, paiements — dans cet ordre

Synchronisez les objets dont le grand livre a besoin pour produire une facture correcte et lettrer un paiement, et rien de plus. En pratique, il s'agit de trois objets avec une dépendance entre eux : un client doit exister avant qu'une facture puisse y faire référence, et une facture doit exister avant qu'un paiement puisse la solder.

Clients

Nom, adresse, pays, numéro de TVA, statut professionnel ou consommateur, et votre propre identifiant externe. Le pays et le statut TVA sont ce qui décide du traitement fiscal ; renseignez-les correctement à la création, pas sur la facture.

Factures

Des lignes avec description, quantité, prix unitaire et nature de l'opération ; la devise ; la date d'échéance ; une référence à votre commande ou abonnement. N'envoyez pas de taux de TVA — envoyez les faits et laissez le grand livre décider, sinon vous réimplémenterez le droit de la TVA dans votre application.

Paiements

Montant, date, devise, et la ou les factures qu'il solde. Si un prestataire de paiement intervient, l'identifiant de transaction du prestataire est la clé qui permettra plus tard de rapprocher le versement.

Le sens compte. Les clients et les factures circulent généralement de votre application vers le grand livre. Le statut de paiement revient souvent dans l'autre sens — le grand livre voit le flux bancaire, votre application veut savoir que la facture est payée. Les rapports (créances en cours, compte de résultat) ne circulent que dans le sens retour. Décidez, objet par objet, quel système est la source de vérité et n'écrivez jamais le même champ depuis les deux côtés.

Ce qu'il ne faut pas synchroniser : les événements internes de votre produit (connexions, utilisation des fonctionnalités), les commandes en brouillon qui ne seront peut-être jamais facturées, et tout ce sur quoi le grand livre ne peut pas agir. Chaque objet que vous poussez est un objet que vous devrez maintenir cohérent.

Idempotence : la réponse qui n'arrive jamais

Une connexion tombe après que le grand livre a créé le client mais avant que votre application ait reçu la réponse. Sans protection, vous perdez l'enregistrement ou vous le créez deux fois, et un client en double refait surface des semaines plus tard lorsqu'une facture atteint la mauvaise copie. Le remède est une clé d'idempotence : une valeur que vous choisissez pour chaque écriture voulue, envoyée dans un en-tête, qui permet au serveur de reconnaître une répétition.

L'Internet-Draft de l'IETF sur cet en-tête énonce son objet sans détour : « The HTTP Idempotency-Key request header field can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant. » Le draft a expiré sans devenir une RFC, mais le motif est la convention du secteur et le nom de l'en-tête est celui qu'utilisent la plupart des API. Les règles qui le font fonctionner côté serveur :

1. La première requête sous une clé effectue le travail et stocke le résultat.
2. Une répétition avec la même clé et le même corps renvoie le résultat stocké — le même enregistrement, pas un nouveau.
3. Une répétition avec la même clé et un corps différent est refusée, parce qu'une clé représente une seule intention.
4. Les clés expirent après un délai, au-delà duquel la valeur compte comme un nouveau travail.

Côté client : générez la clé au moment où l'intention se forme (un UUID stocké avec votre propre ligne de commande), pas au moment où la requête est envoyée, de sorte qu'une nouvelle tentative après un plantage la réutilise. Réessayez avec un délai croissant sur les erreurs réseau et sur les 5xx ; ne réessayez pas sur les 4xx autres que 429.

Webhooks : être informé des changements sans interroger en boucle

Un webhook est une requête HTTP que le logiciel de comptabilité envoie à votre URL lorsqu'un événement se produit — une facture a été émise, un paiement a été enregistré. Il remplace l'interrogation périodique (polling), mais il s'accompagne de trois obligations : vérifier la signature, s'attendre à des doublons et répondre vite.

Les recommandations de Stripe sont la référence que la plupart des développeurs connaissent et elles s'appliquent à tout fournisseur : « Always verify that webhook events originate from Stripe before acting on them » ; « webhook endpoints might occasionally receive the same event more than once », ce contre quoi vous vous protégez « by logging the event IDs you've processed » ; et votre endpoint « must quickly return a successful status code (2xx) before any complex logic that could cause a timeout ». Stripe note aussi qu'il « doesn't guarantee the delivery of events in the order that they're generated » — traitez donc chaque événement comme un pointeur et récupérez l'état actuel si l'ordre importe.

La vérification de signature suit généralement un même schéma : un en-tête avec un horodatage et un HMAC calculé sur timestamp.raw_body ; rejet si l'horodatage sort d'une fenêtre de tolérance (protection contre le rejeu), recalcul du HMAC avec le secret de l'endpoint sur les octets bruts, et comparaison en temps constant. Les frameworks qui analysent et resérialisent le JSON avant que vous puissiez lire le corps cassent ce mécanisme ; lisez le corps brut.

Protéger la clé

Une clé d'API comptable peut lire chaque client et chaque facture de l'entreprise et créer des brouillons. Traitez-la comme un mot de passe de base de données : stockez-la dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le dépôt de code ni dans une application mobile, et n'accordez-lui que les portées que l'intégration utilise.

• Portée minimale. Un tableau de bord qui ne fait que lire les créances a besoin d'une portée de lecture, pas d'écriture. Lecture et écriture sont des autorisations distinctes.
• Une clé par intégration. Pour pouvoir en révoquer une sans casser les autres, et pour que la piste d'audit dise quel système a fait quoi.
• Clés de test en test, clés de production en production. Le préfixe de la clé doit rendre l'environnement évident dans une ligne de journal.
• Rotation. Un fournisseur qui ne stocke qu'un hachage de la clé ne peut pas vous la réafficher — ce qui est la conception correcte. Prévoyez la rotation dès le départ : émettre la nouvelle clé, basculer, révoquer l'ancienne.
• Les secrets de webhook sont aussi des clés. Même stockage, même rotation.

La spécification MCP ajoute un point sur les assistants : « Hosts must obtain explicit user consent before invoking any tool », et les outils « represent arbitrary code execution and must be treated with appropriate caution ». Un serveur MCP placé devant un grand livre comptable doit donc exposer des lectures et de la préparation, pas des actions irréversibles, et la personne au clavier reste responsable.

Comment KRONENWERK gère cela

KRONENWERK propose les quatre voies ; l'API, les webhooks, le serveur MCP et l'annuaire des intégrations font partie du plan Enterprise (voir les plans). Pris en charge avec des limitations

• API. https://kronenwerk.org/api/extern/v1, clé API Bearer avec préfixe greif_live_ ou greif_test_, portées telles que customers:write, invoices:write, transactions:write et reports:read. Endpoints pour les clients (GET/POST /customers), les factures (GET /invoices, POST /invoices/drafts), les transactions (GET/POST /transactions) et GET /reports/outstanding. Une entreprise par clé ; GET /me la nomme. KRONENWERK ne stocke qu'un hachage de la clé ; les clés sont révoquées ou renouvelées sur l'écran développeur.
• Idempotence. Idempotency-Key est obligatoire sur chaque POST. Même clé et même corps : le même enregistrement revient ; même clé et corps différent : refusé ; les clés vivent 24 heures. Détails sur l'idempotence.
• Webhooks. Événements invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. Chaque livraison porte KRONENWERK-Signature (t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal sur t.raw_body>, tolérance de 5 minutes), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt et une Idempotency-Key pour la déduplication. HTTPS uniquement, nouvelles tentatives jusqu'à acceptation, redirections non suivies. Voir les webhooks.
• MCP. Un serveur à /api/extern/mcp (Streamable HTTP, même clé) avec des outils de lecture tels que list_receivables et get_profit_and_loss, et des outils de brouillon create_invoice_draft, create_transaction, add_transaction_note. Aucun outil n'émet de facture, n'envoie de courrier, ne déplace d'argent ni ne modifie de paramètre.
• Limite de débit. Un budget de 240 requêtes par clé, se rechargeant en continu (environ deux par seconde) ; 429 avec Retry-After en cas de dépassement.

POST /api/extern/v1/customers HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_test_…
Idempotency-Key: 6f1c2a8e-4b3d-4a21-9d77-0c5e1f9b2a44
Content-Type: application/json

{"name": "Example SRL", "country": "BE", "vatId": "BE0123456789", "email": "ap@example.be"}

Un exemple détaillé des trois flux se trouve sur connecter un SaaS à la comptabilité ; la surface complète est décrite sur la page API comptable et dans la référence.