Clôture mensuelle à partir de pièces, non de relevés bancaires

En fin de mois, un versement de la marketplace arrive sur le compte. Y sont compensés ventes, port, remboursements et frais. Le conseiller fiscal veut chacun séparément et avec pièce — et personne ne veut les reconstituer à partir d’un versement global.

Les pièces du contrat Commerce séparent précisément ces montants : factures avec net, taxe et brut par ligne, avoirs liés à leur facture, relevés de frais aux lignes recalculables et remboursements par commande. La clôture se construit à partir d’elles, non du versement.

Ce que ce cas suppose

• Un compte de vente raccordé. Les pièces naissent des commandes ; sans commande, pas de pièce.
• Une correspondance avec vos comptes. Les pièces fournissent montants et références, non votre plan comptable.
• Une récupération par pages. Les listes arrivent avec nextCursor ; une clôture les lit en entier.
• Une règle pour les postes ouverts. outstandingAmount montre ce qui reste impayé.

Le déroulement

Le tableau indique pour chaque étape l’appel compétent et ce qui existe ensuite. La justification de l’étape figure en dessous.

Pourquoi chaque étape est nécessaire

1. Lister les factures. GET /commerce/v1/invoices renvoie par pages invoiceId, salesOrderId, documentReference, state, issuedAt et dueAt. Le curseur prouve ici l’exhaustivité : une clôture qui saute une page est fausse.
2. Lire la facture. GET /commerce/v1/invoices/{invoiceId} indique par ligne netAmount, taxAmount et grossAmount, et dans totals en plus paidAmount et outstandingAmount. Net, taxe et brut arrivent séparés — la comptabilité n’a rien à reconstituer.
3. Lire l’avoir. GET /commerce/v1/credit-notes/{creditNoteId} renvoie à invoiceId et salesOrderId et porte un reasonCode. Une correction est donc toujours liée à une facture, non un simple montant négatif du mois.
4. Lire le relevé de frais. GET /commerce/v1/fee-statements/{feeStatementId} renvoie des lignes avec basis, feeBasisPoints et feeAmount, les corrections avec adjustmentOfLineId. Le taux applicable dans feeBasisPoints est défini hors du contrat ; les lignes se recalculent à partir de basis et feeBasisPoints.
5. Rapprocher les remboursements. GET /commerce/v1/refunds liste les remboursements avec amount, state, salesOrderId, returnId et reasonCode. Chaque remboursement devrait avoir un avoir en face ; sinon, c’est un constat pour la clôture.

curl -H 'X-Api-Key: <API_KEY>' \
  'https://commerce-preview.invalid/commerce/v1/invoices?limit=100'

Ce que l’on obtient

Au final, le mois se compose de pièces : chiffre d’affaires des factures, corrections des avoirs, frais des relevés de frais et remboursements, avec leur état, de la liste des remboursements — chaque montant séparé et lié à sa commande.

Où cela figure dans la documentation

Les listes de champs contractuelles, les codes d’erreur et les réponses d’exemple se trouvent dans le contrat OpenAPI de cette surface, à l’adresse docs.tapinomahub.com (tapinoma-commerce). Tous les cas d’usage classés par surface et par rôle : aperçu des cas d’usage.