Transférer un catalogue en fichier — avec des remarques avant la reprise

Un négociant exporte chaque mois son stock d’articles depuis l’ERP en CSV. Aucune intégration API n’est prévue, et elle serait excessive pour ce rythme. Le risque est ailleurs : une colonne décalée dans un fichier de dix mille lignes transforme des prix en références.

Le transfert de catalogue traite donc le fichier comme une synchronisation : d’abord un aperçu avec compteurs et remarques, puis une décision sur cet aperçu précis. Selon le contrat, le transfert est créé dans le modèle Commerce canonique ; le contrat ne précise pas si le contrôle diffère selon le format.

Ce que ce cas suppose

• Un fichier téléversé avec son jeton. Le transfert renvoie au fichier par artifactToken ; le jeton est seulement écrit, jamais renvoyé.
• Le bon format. serialization connaît csv, xml et json.
• En option, une connexion. connectionId est facultatif et renvoie à une connexion ; le contrat ne décrit pas son effet sur le transfert.
• Quelqu’un qui lit les remarques. La validation ne vaut que par le contrôle qui la précède.

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 le transfert. POST /commerce/v1/catalog-transfers prend direction avec import ou export, serialization et artifactToken. La réponse porte transferId, state et les premiers counts — rien n’est encore repris.
2. Lire l’état. GET /commerce/v1/catalog-transfers/{transferId} renvoie state et counts avec read, changed, rejected et conflicted. Ces quatre chiffres sont le premier contrôle de vraisemblance : dix mille lus et dix mille modifiés est rarement juste pour un fichier mensuel.
3. Lire les remarques. GET /commerce/v1/catalog-transfers/{transferId}/issues liste par remarque severity, code, message, pointer et, s’il est présent, recordNumber. Avec recordNumber, on retrouve la ligne dans son propre fichier au lieu d’interpréter un message d’erreur.
4. Décider. POST /commerce/v1/catalog-transfers/{transferId}/approval prend decision avec approve ou reject, ainsi que previewRevision et expectedRevision. On valide l’aperçu contrôlé — si l’état a changé entre-temps, la révision ne correspond plus.
5. Récupérer le fichier résultat. GET /commerce/v1/catalog-transfers/{transferId}/artifact renvoie artifactToken, checksum et expiresAt. checksum est une chaîne de 64 caractères hexadécimaux ; le contrat ne précise ni l’algorithme ni sur quoi elle est calculée. expiresAt indique l’heure d’expiration.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: katalog-import-2026-09' \
  -d '{"direction":"import","serialization":"csv","artifactToken":"<artifactToken>","connectionId":"<connectionId>"}' \
  'https://commerce-preview.invalid/commerce/v1/catalog-transfers'

Ce que l’on obtient

Il reste un catalogue repris seulement après validation de l’aperçu contrôlé, et un fichier résultat avec checksum. Le contrat n’impose pas que quelqu’un ait lu compteurs et remarques avant la validation ; il exige previewRevision et expectedRevision — c’est pourquoi quelqu’un qui lit les remarques figure parmi les prérequis. Une colonne décalée peut se remarquer avant la validation si les compteurs ou les remarques de l’aperçu la révèlent.

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.