Qu'est-ce qu'une API de grand livre en partie double pour les marketplaces ?

Une marketplace peut afficher une table orders florissante tout en se trompant dans ses comptes. La commande indique "payée". Le tableau de bord du vendeur affiche un solde. Pourtant, rien dans cette table ne prouve le montant des liquidités détenues par la plateforme, ce qu'elle doit à chaque vendeur, la part du paiement correspondant à ses commissions ou le montant de la TVA exigible. Une API de grand livre en partie double sert à enregistrer ces conséquences financières de manière correcte, transaction équilibrée après transaction.

En clair : une API de grand livre en partie double est un système comptable programmable. Votre application lui transmet un événement financier, tel qu'un paiement encaissé ou un versement approuvé, et le grand livre consigne cet événement sous forme d'un journal comprenant des débits et des crédits égaux répartis sur des comptes nommés. Elle ne déplace pas l'argent. Elle consigne la réalité des flux financiers qui se sont produits ailleurs.

Ce que signifie "grand livre en partie double" ici

Un grand livre est le registre des variations des comptes, et non une simple table affichant le dernier solde. Un grand livre fonctionnel repose sur trois notions interdépendantes :

• Compte : une position financière nommée, telle que créance sur le prestataire de paiement, dette envers le vendeur, chiffre d'affaires sur commissions ou TVA à payer.
• Transaction (journal) : un événement financier atomique contenant plusieurs lignes équilibrées.
• Écriture (posting) : une ligne unique de débit ou de crédit au sein de cette transaction.

L'invariant qui garantit la cohérence de l'ensemble est simple : le total des débits doit être égal au total des crédits, pour chaque transaction et dans chaque devise. Les API de grand livre rejettent généralement toute écriture déséquilibrée avant son enregistrement. La documentation de Modern Treasury définit une transaction de grand livre comme impliquant au moins deux comptes avec au moins un débit et un crédit de montants égaux, et considère une transaction validée comme immuable.

La partie double ne signifie pas qu'il y a exactement deux lignes. Une vente unique sur une marketplace nécessite souvent un débit et plusieurs crédits. C'est l'élément le plus fréquemment mal interprété.

Pourquoi les marketplaces ont besoin d'un grand livre et non d'une simple table de paiements

Une marketplace gère simultanément plusieurs relations financières. Un acheteur paie. Un prestataire règle la transaction. La plateforme contrôle parfois temporairement les fonds. Le vendeur en perçoit une fraction. La plateforme conserve une commission. La TVA devient exigible. Une réserve peut être retenue. Plus tard, un virement décaisse l'argent, tandis que les remboursements ou les rétrofacturations (chargebacks) en annulent une partie.

Une table payments indique le statut commercial d'une commande. En revanche, elle ne peut pas vous indiquer avec certitude :

• le montant des créances sur les prestataires ou de la trésorerie disponible
• ce qui est dû à chaque vendeur
• le montant du chiffre d'affaires revenant à la plateforme
• le montant de la TVA due, et dans quel pays
• les montants réservés pour faire face aux remboursements ou aux litiges
• si un virement a correctement réduit la dette envers le vendeur
• si les règlements des prestataires correspondent aux prévisions de la plateforme

Le guide des API de grand livre en partie double pour la comptabilité des marketplaces de Nordlet pose des limites claires : les tables applicatives décrivent l'état des produits, tandis que le grand livre enregistre les répercussions financières de cet état. Il rappelle également un point crucial : les rapports des prestataires de paiement constituent des intrants pour le rapprochement, et non des livres en partie double complets.

Exemple concret d'une vente sur une marketplace

Imaginons qu'un acheteur paie 100 €, que le vendeur ait droit à 85 € et que la commission de la plateforme s'élève à 15 €. Faisons abstraction de la TVA et des frais du prestataire pour plus de clarté.

Compte	Débit	Crédit	Motifs
Créance sur le prestataire de paiement	100 €		Le prestataire doit le paiement encaissé à la plateforme
Dette envers le vendeur		85 €	La plateforme doit de l'argent au vendeur
Chiffre d'affaires (commissions)		15 €	La plateforme a perçu sa commission
Total	100 €	100 €	Soldé

La distinction importante ici réside dans le fait que les 85 € dus au vendeur constituent un passif, et non le chiffre d'affaires de la plateforme. Selon le cadre conceptuel de l'IASB, un passif est une obligation actuelle de transférer une ressource économique. Une marketplace ne doit pas comptabiliser l'intégralité du produit de la vente du vendeur comme ses propres revenus au seul motif que l'acheteur a payé par son intermédiaire. Votre rôle d'agent, de mandant ou de redevable légal (deemed supplier) modifie le traitement comptable, mais le mécanisme du grand livre reste inchangé.

Lorsque le vendeur devient éligible à un virement, aucun nouveau chiffre d'affaires n'est comptabilisé. Vous soldez le passif :

Compte	Débit	Crédit
Dette envers le vendeur	85 €
Banque ou compte de virement en transit		85 €
Total	85 €	85 €

Si le prestataire prélève des frais de 3 € avant le règlement, le mouvement de trésorerie se traduit par un journal à trois lignes : 97 € en banque, 3 € en frais de traitement, et 100 € sortant des créances sur le prestataire. Chaque modification de position comporte une source et une destination.

Fonctionnement de l'API, étape par étape

1. Votre application détecte un événement commercial. Un paiement est encaissé, une commande est exécutée, un virement est approuvé, un remboursement est émis, un litige est ouvert, un règlement est reçu. Votre base de données gère toujours l'état opérationnel, tandis que le grand livre consigne l'impact monétaire.

2. Vous envoyez une requête structurée. Celle-ci contient généralement le type d'événement, le montant et la devise, l'identifiant de la commande ou du paiement, les identifiants de l'acheteur et du vendeur, la commission, les données fiscales, les comptes concernés, les dates d'effet et de comptabilisation, une clé d'idempotence, ainsi que les métadonnées renvoyant aux enregistrements du prestataire et du produit. L'exemple d'API publique de Nordlet présente une requête de vente conceptuelle comprenant l'identifiant du vendeur, le type de vente, le montant, la devise, ainsi que le pays et le taux de TVA.

3. L'API valide la requête. Elle vérifie que les débits et les crédits s'équilibrent, que les comptes existent et acceptent les écritures, que la devise est prise en charge, que le montant utilise un traitement précis des unités mineures, que la clé d'idempotence n'est pas réutilisée pour un résultat différent, que la période est ouverte et que les métadonnées requises sont présentes. En cas d'échec de la vérification, aucun journal partiel n'est enregistré.

4. Elle valide les écritures de manière atomique. La transaction complète est enregistrée en une seule opération. Il doit être impossible d'enregistrer le débit si le crédit correspondant échoue. Sur une marketplace, une écriture fractionnée pourrait générer un solde vendeur fictif sans trésorerie correspondante, ou comptabiliser une commission sans l'obligation envers le vendeur.

5. Les soldes et les rapports sont issus du grand livre. Après la validation, vous pouvez consulter les soldes des comptes, les soldes en attente et disponibles des vendeurs, la balance des comptes (trial balance), l'activité du grand livre général, les récapitulatifs de TVA et l'historique à une date passée. Le solde du vendeur doit pouvoir être reconstitué à partir des écritures, et non provenir d'un champ modifiable auquel on se fierait aveuglément.

6. Les webhooks informent votre produit. Des événements tels que sale_invoice.paid, un journal validé, un virement disponible ou une anomalie de rapprochement vous sont transmis. Traitez-les de manière idempotente. Un webhook est une notification, et non une autorisation d'appliquer l'événement financier une seconde fois. Les conventions de l'API détaillent les périmètres (scopes), les clés d'idempotence, la structure des erreurs et la signature des webhooks.

Les soldes des vendeurs ne se résument pas à un chiffre unique

La plupart des marketplaces se retrouvent en difficulté lorsqu'elles traitent le solde d'un vendeur comme un montant unique. L'argent doit être réparti selon différents états :

État	Signification
En attente (Pending)	Le vendeur y a peut-être droit, mais les conditions de déblocage ne sont pas réunies
Disponible (Available)	Éligible pour un virement
Réservé (Reserved)	Retenu pour parer à d'éventuels remboursements, retours ou litiges
Versé (Paid out)	Obligation éteinte par un transfert
Négatif (Negative)	Les remboursements, rétrofacturations ou frais dépassent les fonds disponibles

Les modèles des prestataires de services de paiement reflètent cette organisation. Le flux de frais et de transferts distincts de Stripe permet à une plateforme de débiter son propre compte, puis de transférer des portions vers des comptes connectés, les frais, remboursements et rétrofacturations s'imputant sur le solde de la plateforme. Le modèle marketplace d'Adyen distingue les comptes de solde utilisateurs, qui détiennent les fonds jusqu'au virement, d'un compte de solde débiteur capable d'absorber les soldes négatifs liés aux remboursements ou aux rétrofacturations. Ces éléments constituent des données utiles pour votre grand livre, sans pour autant former votre modèle comptable complet.

Virements et revenus des vendeurs interviennent à des moments différents

Un vendeur peut réaliser une vente le lundi et recevoir ses fonds le lundi suivant. Entre ces deux moments, la commande est expédiée, une réserve est constituée, un lot de virements est préparé, un prestataire effectue le règlement net des frais, et un virement bancaire arrive sur le compte. Le grand livre doit préserver chaque étape au lieu d'écraser la commande par un statut final "payé". C'est ce qui vous permet d'expliquer les décalages temporels entre l'activité des commandes, les droits du vendeur, le règlement, le déclenchement du virement et la réception bancaire.

Remboursements et rétrofacturations : contre-passer, ne pas modifier

Les remboursements et les rétrofacturations constituent de nouveaux événements liés au paiement initial. Dans un grand livre immuable, vous procédez à une correction par une écriture de contre-passation (reversing entry) suivie d'une écriture rectificative, de sorte que l'opération d'origine reste visible à des fins d'audit. Modern Treasury traite les transactions validées comme immuables et gère les clés d'idempotence afin d'éviter les doublons lors des nouvelles tentatives.

Un remboursement réduit généralement la trésorerie ou les créances sur les acheteurs, contre-passe la dette envers le vendeur, peut annuler une partie de la commission selon la politique en vigueur, ajuste la taxe et peut prélever des fonds sur une réserve de remboursement. Une rétrofacturation réduit la trésorerie ou les créances sur le prestataire, peut réactiver un montant dû par le vendeur ou la plateforme, enregistre une charge pour litige ainsi que des frais de prestataire, et achemine les fonds par un compte de réserve.

Rapprochement : relier le grand livre à l'argent réel

Un grand livre peut être équilibré en interne tout en étant erroné par rapport à la réalité extérieure. Le rapprochement (reconciliation) compare les registres internes aux justificatifs externes : rapports de règlement des prestataires, relevés bancaires, fichiers de virement, dossiers de remboursement et de litige.

Une boucle de rapprochement efficace s'articule ainsi :

1. Importer le lot de règlements ou le fichier bancaire.
2. Associer chaque ligne à une commande, un paiement, un remboursement, des frais, un virement ou un litige.
3. Comparer le montant brut attendu, les déductions, les réserves et le net.
4. Enregistrer les mouvements confirmés dans le grand livre.
5. Affecter les éléments non appariés à un compte d'attente (suspense account) désigné.
6. Investiguer les anomalies.
7. Clôturer la période.

La documentation de Nordlet relative au rapprochement décrit précisément ce processus, en important les lots de règlements, en associant les lignes de frais et de remboursement, et en acheminant les recettes non appariées vers un compte d'attente plutôt que de deviner à quelle facture les rattacher. Deux vérifications s'avèrent indispensables et aucune ne remplace l'autre : la validation en partie double vérifie si chaque journal est équilibré, tandis que le rapprochement s'assure de sa concordance avec le prestataire, la banque et l'événement commercial.

Choix de conception déterminants pour la réussite

Idempotence. Associez la clé à un événement stable, tel que payment_captured:pi_123. Une nouvelle tentative renvoie le résultat initial, et non un second journal.

Atomicité. Toutes les lignes d'un même événement sont enregistrées ensemble, ou aucune ne l'est.

Immutabilité et contre-passations. L'historique validé n'est pas modifiable par de simples mises à jour. Les corrections génèrent des écritures liées qui préservent le montant, la date, la classification, le motif et l'auteur d'origine.

Précision monétaire. Proscrivez les nombres à virgule flottante binaires. Utilisez des unités mineures entières ou des décimales exactes, une devise explicite et une règle d'arrondi déterministe pour les répartitions. Si vous répartissez 100 € entre différents vendeurs et frais sans règle précise, un centime égaré faussera votre équilibre.

Dates d'effet et dates de comptabilisation. La date de paiement de l'acheteur, la date d'acquisition des revenus par le vendeur, la date de règlement par la banque et la date de comptabilisation de l'écriture sont distinctes. Les confondre rend peu fiables les reportings périodiques et le calcul des échéances fiscales.

Multi-devises. Les débits et les crédits doivent s'équilibrer au sein d'une même devise. La conversion nécessite un événement de taux explicite avec des comptes dédiés aux frais, aux arrondis et aux éventuels gains ou pertes de change. L'acceptation d'un champ currency ne transforme pas pour autant un grand livre en moteur de change.

Ce qu'une API de grand livre ne fera pas à votre place

Elle ne définira pas votre plan comptable. Il vous appartiendra toujours de déterminer si vous agissez en tant que mandant ou agent, à quel moment la commission est acquise, quelle partie supporte les frais du prestataire, de quelle manière les remboursements affectent la commission, ainsi que la méthode de calcul et de déclaration de la TVA. Les recommandations de Nordlet consistent à cartographier d'abord les flux financiers, à rédiger le plan comptable, à le soumettre à l'avis d'un expert-comptable, puis à implémenter un flux complet (de la commande au virement et au rapprochement) avant d'intensifier l'activité.

Elle ne résoudra pas non plus les questions fiscales. La TVA dépend du lieu d'établissement de l'acheteur et du vendeur, du type de produit, du statut d'immatriculation et des règles applicables aux assujettis réputés (deemed suppliers) ; le guide de la TVA dans l'UE précise ce que le moteur calcule et ce qu'il signale à l'attention d'un opérateur humain. La couverture de la TVA par Nordlet se concentre sur l'UE et l'EEE, de sorte qu'elle ne s'applique pas à la taxe sur les ventes américaine (sales tax) ni à la facturation électronique en Amérique latine. Enfin, elle ne lèvera pas les ambiguïtés opérationnelles, qu'il s'agisse de l'expiration d'un délai de retour, du blocage d'un virement ou du caractère frauduleux d'un paiement. Ces décisions relèvent de votre responsabilité. Le grand livre se contente d'enregistrer leur traduction financière.

Le positionnement de Nordlet

Nordlet est une API comptable conçue pour les plateformes et les marketplaces, dotée d'un grand livre en partie double immuable, de la gestion des virements et de la TVA européenne, de points de terminaison REST, de kits de développement (SDK) typés et de webhooks accessibles via une interface unique. Sa particularité réside dans l'intégration de la comptabilité au cœur de votre propre produit, plutôt que par le recours à une solution de paiement tierce. Au moment de la rédaction de cet article, le produit est en phase d'accès anticipé avec un bac à sable (sandbox) pour les partenaires de conception ; il convient donc de le considérer comme un exemple de premier plan dans sa catégorie et d'évaluer sa maturité en production, sa disponibilité et sa couverture réglementaire pour votre cas d'usage avant tout engagement.

Pour les développeurs de marketplaces et de plateformes, le modèle mental utile repose sur la dissociation entre le mouvement des paiements et la réalité financière. Votre prestataire déplace l'argent. Une API de grand livre en partie double enregistre ce qui est dû à chacun, ce que vous avez gagné, le montant des taxes et des réserves que vous supportez, et vérifie si le monde extérieur concorde avec vos livres comptables.

FAQ

Une API de grand livre en partie double est-elle la même chose qu'un prestataire de services de paiement ?

Non. Un prestataire autorise, encaisse, règle et verse parfois des fonds. Une API de grand livre enregistre les conséquences comptables de ces événements. La plupart des marketplaces utilisent les deux : un prestataire tel que Stripe ou Adyen pour les flux financiers et un grand livre pour la comptabilité.

Puis-je me contenter du tableau de bord de mon prestataire de paiement comme grand livre général ?

Vous pouvez essayer, mais cela finira par échouer lors d'un audit. Les rapports des prestataires affichent les frais, les transferts et les règlements, mais ils omettent généralement la totalité de vos obligations envers les vendeurs, vos passifs fiscaux, vos charges hors prestataires ou vos régularisations comptables. Considérez-les comme des données d'entrée pour le rapprochement.

Un grand livre équilibré garantit-il l'exactitude de mes comptes ?

Cela signifie seulement que vos écritures respectent la règle du débit et du crédit. Une transaction parfaitement équilibrée peut tout de même être affectée au mauvais compte, au mauvais vendeur ou faire l'objet d'un traitement fiscal erroné. L'équilibre est nécessaire, mais insuffisant. Le rapprochement permet de détecter le reste.

Si le grand livre est immuable, comment corriger des erreurs ?

Vous enregistrez une écriture de contre-passation (reversing entry) suivie d'une écriture rectificative. L'opération d'origine reste visible, ce qui est précisément l'objectif recherché. L'immutabilité protège la piste d'audit sans pour autant figer vos erreurs.

Une API comptable me met-elle automatiquement en conformité ?

Non. Elle impose une structure comptable et produit des documents exploitables. La conformité juridique dépend toujours de votre juridiction, de votre rôle contractuel, de votre régime fiscal, de la réglementation des paiements, de vos procédures KYC et AML, ainsi que de vos obligations de reporting.

Pour aller plus loin

• API de grand livre en partie double pour la comptabilité des marketplaces
• Définir les grands livres en partie double, Formance (en anglais)