Raccorder un canal de vente sans avoir deux systèmes écrivains

Un négociant vend via une marketplace et tient un ERP en parallèle. Les deux systèmes se croient de référence. Qui l’a vécu connaît le résultat : des stocks qui oscillent, des prix redevenus anciens une nuit plus tard, et une pièce unique vendue deux fois.

Le contrat Commerce place donc volontairement une étape avant le transfert : avant toute écriture, un plan de synchronisation consigne qui écrit ; au plus une affectation d’écriture active est admise par compte de vente, zone de marché, offre facultative et flux métier. Ensuite vient un aperçu, et seule une validation explicite en fait une modification.

Ce que ce cas suppose

• Un compte de vente autorisé. La connexion est créée avec une preuve d’autorisation ; les accès du canal ne sont ni divulgués ni transmis.
• Une décision sur le système de référence. Cette question est commerciale, non technique. Le contrat impose seulement qu’on y réponde.
• La volonté de lire l’essai à blanc. Un aperçu que personne ne regarde renonce à la seule occasion d’échouer sans conséquence.
• Une clé d’idempotence par appel écrivain. Un appel répété ne doit pas produire un second effet.

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. Lire les capacités. GET /commerce/v1/capabilities indique par canal supportLevel, flows et la prise en charge des réservations. Cette étape établit avant tout travail ce que le canal sait faire — sinon un raccordement sur une fonction non prise en charge échoue tard et cher.
2. Créer la connexion. POST /commerce/v1/connections prend channelId, channelAccountReference, marketAreaReference, authorizationProof et ownershipMode. Les détails liés au canal restent derrière une frontière de traduction privée ; les identifiants publics sont opaques.
3. Fixer la responsabilité. POST /commerce/v1/sync-plans est l’étape décisive : writerAssignments admet au plus une affectation d’écriture active par compte de vente, zone de marché, offre facultative et flow, conflictPolicy règle le litige, et dryRunRequired peut rendre l’essai à blanc obligatoire.
4. Faire un essai à blanc. POST /commerce/v1/sync-runs en mode aperçu renvoie counts avec read, changed, rejected et conflicted. Quatre chiffres qui disent, avant la première écriture réelle, ce qui se passerait.
5. Valider. POST /commerce/v1/sync-runs/{syncRunId}/approval prend decision, previewRevision et expectedRevision ; les trois champs sont obligatoires. On valide donc exactement l’aperçu contrôlé — non un état entre-temps modifié.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: lauf-2026-09-12-01' \
  -d '{"syncPlanId":"<syncPlanId>","mode":"preview"}' \
  'https://commerce-preview.invalid/commerce/v1/sync-runs'

Ce que l’on obtient

Il reste une connexion où le plan consigne qui écrit, et un premier transfert lu en aperçu avant validation. Le contrat ne garantit pas que le stock cesse d’osciller pour autant : il ne peut empêcher un travail manuel à côté dans le canal.

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.