Fixer les prix, recalculer les frais, constater les écarts

Un négociant fixe ses prix par une marge sur l’achat et constate en fin d’année qu’un groupe de produits n’a rien rapporté. La raison est dans les frais de canal que personne n’a jamais recalculés. La marge était juste — elle était simplement calculée sur la mauvaise base.

Les cinq branches répondent à quatre questions différentes sur le même compte de vente. Elles ne dépendent pas l’une de l’autre, et toutes ne sont pas nécessaires — mais fixer des prix sans recalculer les frais, c’est calculer sur une base inconnue.

Ce que ce cas suppose

• Un objectif net à atteindre. Avec targetNet, la règle de prix calcule à rebours ; selon le contrat, une marge fixe ne garantit aucun objectif.
• La volonté de lire les lignes de frais. Un relevé que personne ne contrôle est une facture qu’on paie.
• Deux points de contrôle pour le rapprochement. Source et cible ont chacune besoin d’un état ; sourceCheckpoint et targetCheckpoint sont des champs obligatoires du rapprochement.
• Un destinataire pour les événements si vous ne voulez pas interroger. Un abonnement sans destinataire joignable ne livre rien.

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. Créer la règle de prix. POST /commerce/v1/pricing-policies connaît, outre une marge fixe, targetNet : vous indiquez le net qui doit rester et la règle calcule à rebours — avec frais de canal, frais de service et remises, selon ce que vous incluez. C’est la différence entre chiffre d’affaires et résultat.
2. Contrôler le relevé de frais. GET /commerce/v1/fee-statements renvoie par ligne basis, feeBasisPoints et feeAmount, et pour les corrections le renvoi à la ligne corrigée. Un frais se recalcule ainsi au lieu d’être cru.
3. Lancer le rapprochement. POST /commerce/v1/reconciliations compare sourceCheckpoint et targetCheckpoint et renvoie counts, integrity avec des sommes de contrôle pour source et cible, et discrepancies avec severity. Le chiffre décisif est criticalRemaining, le nombre d’écarts critiques restants ; le rapprochement n’est pas encore activé dans le contrat.
4. S’abonner aux événements. POST /commerce/v1/webhook-subscriptions met en place une livraison signée. Interroger en boucle crée de la charge et ne détecte une lacune que tard.
5. Relire le flux. GET /commerce/v1/events renvoie les événements avec streamId et sequence. La lecture utilise une pagination par curseur stable (cursor, limit).

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: preisregel-netto-2026-09' \
  -d '{"strategy":"target_net","scope":{"catalogItemIds":["<catalogItemId>"]},"targetNet":{"target":{"amountMinor":4500,"currency":"EUR"},"calculationBasis":"item_price","includeChannelFees":true,"includeServiceFees":true,"includeDiscounts":false},"revision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/pricing-policies'

Ce que l’on obtient

Au final, vous pouvez recalculer chaque ligne de frais, faire dériver les prix d’offre avec targetNet d’un objectif et des frais inclus, et lire après un rapprochement dans criticalRemaining combien d’écarts critiques restent entre source et cible. Le contrat ne connaît pas les coûts d’achat ; vous déterminez votre marge avec vos propres chiffres.

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.