Jugez une API comptable sur huit points que vous pouvez vérifier dans sa documentation en un après-midi : comment un appelant s'authentifie et auprès de quel tenant, si les permissions sont limitées par scopes, si les écritures sont idempotentes, si elle vous informe des changements (webhooks), quelle est la limite de débit et comment elle échoue, s'il existe un bac à sable, à quoi ressemble une erreur, et si un assistant IA peut l'utiliser sans pouvoir causer de dommages. Un éditeur qui répond aux huit avec des détails précis a réfléchi aux intégrations ; un éditeur qui répond par « oui » ne l'a pas fait. Cette page donne les questions, puis les réponses de KRONENWERK avec les vrais chiffres et les vraies limitations.
Pourquoi l'API décide plus que la liste des fonctionnalités
Un système comptable dans lequel votre produit écrit devient une partie de votre produit. Son API façonne la manière dont vous modélisez les clients et les factures, la manière dont vous vous remettez d'une requête échouée à 3 heures du matin, et ce qu'un auditeur voit lorsqu'il demande quel système a créé une écriture. Choisir sur la liste des fonctionnalités et découvrir l'API ensuite, c'est ainsi que les intégrations finissent avec un traitement CSV nocturne et une personne qui « vérifie ».
Les huit critères ci-dessous sont classés selon le coût de leur contournement. L'absence d'idempotence, par exemple, ne peut pas être corrigée côté client ; une limite de débit grossière peut l'être.
Le tableau d'évaluation
Utilisez la colonne du milieu comme question à poser à tout éditeur ; utilisez la colonne de droite pour juger la réponse.
| Critère | Que demander | À quoi ressemble une bonne réponse |
|---|---|---|
| Authentification et tenant | Comment une requête s'identifie-t-elle, et comment le serveur sait-il à quelle société elle s'applique ? | Un secret Bearer lié à exactement une société lors de sa création ; le tenant ne provient jamais d'un en-tête ou d'un chemin que l'appelant contrôle ; un appel qui vous indique à quelle société une clé appartient. |
| Scopes | Une clé peut-elle être limitée à la lecture, ou à un seul type d'objet ? | Des scopes nommés par objet et par direction (lecture / écriture), vérifiés côté serveur, la lecture n'impliquant pas l'écriture. |
| Idempotence | Que se passe-t-il lorsque je réessaie un POST dont je n'ai jamais reçu la réponse ? | Un en-tête Idempotency-Key ; même clé et même corps renvoient le résultat original ; même clé avec un corps différent est refusée ; une durée de vie de clé documentée. |
| Webhooks | Comment apprendre qu'une facture a été payée sans interrogation répétée ? | Des livraisons signées (HMAC sur l'horodatage et le corps brut), un identifiant d'événement pour la déduplication, des nouvelles tentatives en nombre documenté, HTTPS uniquement, aucune redirection suivie. |
| Limites de débit | Combien d'appels, mesurés comment, et que revient-il quand je dépasse ? | Un budget et un taux de recharge indiqués par clé ; 429 avec Retry-After ; le chiffre, et non « usage raisonnable ». |
| Bac à sable | Où tester sans toucher aux vrais livres ? | Des identifiants de test qui exercent la même API avec la même validation ; une séparation claire des données de production. |
| Erreurs et versionnage | À quoi ressemble un échec, et que promet une version ? | Du JSON avec un code lisible par machine plus une phrase humaine ; une version dans le chemin ; une règle énoncée sur ce qui peut changer au sein d'une version. |
| MCP pour les assistants | Un assistant IA peut-il lire les livres, et que ne peut-il pas faire ? | Un serveur MCP avec la même clé et les mêmes scopes ; des outils de lecture plus des outils de brouillon ; aucun outil qui émet des documents, envoie des e-mails, déplace de l'argent ou modifie des paramètres. |
Trois critères plus en détail
L'idempotence est celle que vous ne pouvez pas rajouter après coup
Tout réseau finit par perdre une réponse. Le projet de l'IETF pour cet en-tête en décrit l'objectif : rendre « tolérantes aux pannes les méthodes HTTP non idempotentes telles que POST ou PATCH ». Le projet a expiré sans devenir une RFC, mais la convention qu'il documente est celle qu'utilisent la plupart des API de paiement et de comptabilité. Si l'API d'un éditeur en est dépourvue, vos seules options sont d'interroger avant chaque écriture (une condition de concurrence) ou d'accepter des clients et des factures occasionnellement en double. Aucune des deux ne survit bien à un audit.
Webhooks : les mêmes règles que celles de Stripe
Les recommandations de Stripe sur les webhooks sont devenues le standard de fait, et constituent une bonne référence pour toute API comptable : des signatures pour « vérifier que les événements webhook proviennent bien » de l'expéditeur, une tolérance aux doublons parce que les endpoints « peuvent occasionnellement recevoir le même événement plus d'une fois », aucun ordre garanti, et un 2xx rapide avant tout traitement lourd. Demandez à l'éditeur si ses livraisons portent une signature, un horodatage et un identifiant d'événement — et si la signature est calculée sur le corps brut, car une signature sur du JSON resérialisé ne peut pas être vérifiée de manière fiable.
MCP : lire beaucoup, préparer un peu, ne rien déclencher
Le Model Context Protocol est « un protocole ouvert qui permet une intégration transparente entre les applications LLM et les sources de données et outils externes », utilisant des messages JSON-RPC 2.0 entre hôtes, clients et serveurs. Sa spécification est explicite : les outils « représentent une exécution de code arbitraire et doivent être traités avec la prudence appropriée » et « les hôtes doivent obtenir le consentement explicite de l'utilisateur avant d'invoquer un outil ». Pour un grand livre comptable, cela se traduit par un test simple : listez les outils et vérifiez qu'aucun d'eux ne peut émettre une facture, envoyer un document, déplacer de l'argent ou modifier un paramètre. Un assistant capable de répondre à « qui est en retard de paiement ? » et de préparer un brouillon de facture pour révision par une personne est utile ; un assistant capable de l'émettre est un passif.
Comment KRONENWERK répond à chaque critère
Les chiffres ci-dessous sont ceux que l'API applique aujourd'hui ; la référence se trouve sur la référence développeurs. L'API, les webhooks, le serveur MCP et l'annuaire des intégrations font partie du plan Enterprise — voir plans. PRIS EN CHARGE AVEC LIMITATIONS
| Critère | KRONENWERK |
|---|---|
| Authentification et tenant | Clé d'API Bearer, préfixe greif_live_ ou greif_test_, à l'adresse https://kronenwerk.org/api/extern/v1. Une société par clé, fixée à la création ; aucun en-tête ni chemin ne sélectionne une société. GET /me renvoie la société et les scopes. Seul un hachage de la clé est stocké ; une clé perdue est remplacée, non récupérée. Voir authentification. |
| Scopes | customers:read, customers:write, invoices:read, invoices:write, transactions:read, transactions:write, reports:read, companies:read. Lecture et écriture sont des droits distincts. |
| Idempotence | Idempotency-Key obligatoire sur chaque POST. Même clé et même corps : l'enregistrement original ; même clé et corps différent : refusé avec 409 et le code IDEMPOTENZ_KONFLIKT ; les clés vivent 24 heures. Voir idempotence. |
| Webhooks | Événements invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. En-têtes KRONENWERK-Signature (t=…,v1=…, HMAC-SHA256 sur t.raw_body, tolérance de 5 minutes), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt, Idempotency-Key. HTTPS uniquement, nouvelles tentatives jusqu'à acceptation, redirections non suivies. Voir webhooks. |
| Limites de débit | Un budget de 240 requêtes par clé, se rechargeant en continu à environ deux par seconde. Le dépassement renvoie 429 avec Retry-After et le code ZU_VIELE_ANFRAGEN. Voir limites. |
| Bac à sable | Une clé greif_test_ fonctionne contre la même API en mode test pour la société qui l'a créée. Il n'existe pas d'hôte bac à sable distinct. |
| Erreurs et versionnage | Les erreurs sont du JSON avec un code machine et une phrase, p. ex. {"fehler": "…", "code": "NICHT_GEFUNDEN"} ; le code fait partie du contrat, la phrase peut être reformulée. La version est dans le chemin (/v1) ; au sein d'une version, des champs peuvent être ajoutés mais ni supprimés ni retypés, et les codes conservent leur signification. Voir erreurs. |
| MCP | Serveur à /api/extern/mcp, Streamable HTTP, même clé d'API. Outils de lecture : get_customer, search_customers, get_invoice, list_invoices, get_transaction, list_transactions, list_receivables, list_payables, get_profit_and_loss, get_balance_sheet, get_business_attention. Outils de brouillon : create_invoice_draft, create_transaction, add_transaction_note. Aucun outil n'émet de facture, n'envoie d'e-mail, ne déplace d'argent ni ne modifie de paramètres. Voir MCP. |
La liste complète des endpoints est courte à dessein : GET /me, GET /customers, GET /customers/{id}, POST /customers, GET /invoices, GET /invoices/{number}, POST /invoices/drafts, GET /transactions, POST /transactions, GET /reports/outstanding. Une requête et son refus ressemblent à ceci :
GET /api/extern/v1/invoices?status=OPEN&size=1 HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_live_…
HTTP/1.1 200 OK
Content-Type: application/json
{"data":[{"number":"R-2026-0001","issuedOn":"2026-04-02","buyer":"Kellermann GmbH",
"currency":"EUR","gross":{"minor":105910,"currency":"EUR"},
"outstanding":{"minor":105910,"currency":"EUR"},"paymentState":"OPEN","overdue":false}],
"page":0,"size":1,"total":1,"more":false}HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{"fehler":"…","code":"ZU_VIELE_ANFRAGEN"}L'API est décrite en prose sur la page de l'API comptable ; l'examen de sécurité se trouve sur sécurité pour développeurs ; l'évaluation plus large pour les entreprises européennes — formats, TVA, langues — sur ce dont une entreprise européenne a besoin.
Questions fréquentes
Une clé d'API suffit-elle, ou dois-je exiger OAuth ?
Pour une intégration serveur à serveur où vous contrôlez les deux extrémités, une clé à scopes liée à une seule société est plus simple et tout aussi sûre. OAuth compte lorsque des tiers agissent au nom de nombreux utilisateurs ; ce n'est pas le cas d'une société qui intègre sa propre application à son propre grand livre.
Quelle est une limite de débit raisonnable pour une API comptable ?
Assez pour une rafale en fin de mois et un flux régulier le reste du temps. Le budget de KRONENWERK de 240 requêtes se rechargeant à environ deux par seconde correspond à ce schéma ; ce qui compte davantage, c'est que la limite soit indiquée et que le 429 porte Retry-After.
Pourquoi KRONENWERK ne laisse-t-il pas l'API émettre des factures ?
Parce que l'émission attribue un numéro légal, génère la facture électronique et vérifie le numéro de TVA ; le produit garde cette étape derrière la validation et une personne. Brouillons via l'API, émission dans le produit.
Puis-je utiliser le bac à sable sans plan payant ?
Une clé de test est créée au sein d'une société sur le plan Enterprise ; il n'existe pas d'hôte bac à sable public distinct. Voir plans.
Le serveur MCP donne-t-il à un assistant un accès en écriture à mes livres ?
Uniquement aux brouillons et aux notes : il peut préparer un brouillon de facture ou une transaction pour révision par une personne. Il ne peut rien émettre, envoyer, payer ni reconfigurer.
Sources
- KRONENWERK developer documentation — consulté le
- IETF — The Idempotency-Key HTTP Header Field (Internet-Draft, httpapi WG) — consulté le
- Model Context Protocol — Specification 2025-06-18 — consulté le
- Stripe documentation — Receive Stripe events in your webhook endpoint — consulté le