Ciama : unifier Amazon, Cdiscount, Fnac Darty et Mirakl sans effacer leurs différences

1. Ciama, un produit Dawap pour les opérations commerce

Une plateforme commerce et un périmètre technique clairement défini

Ciama est une plateforme conçue et développée par Dawap pour réunir plusieurs univers de vente dans un même modèle : marketplace, e-commerce et B2B. Le produit porte des comptes, des connexions fournisseur, des canaux, des commandes, des offres et des outils de pilotage spécialisés.

Le module technique marketplace s’adresse aux équipes qui doivent brancher des comptes Amazon, Cdiscount, Fnac Darty ou une marketplace Mirakl sans recopier toute la logique métier pour chaque source. Les écrans de pilotage et les outils comme Product Explorer, Stock Dispatcher ou Listing Gap Matrix exploitent ce socle dans des parcours dédiés.

Le besoin n’est donc pas « connecter le plus d’API possible ». Il est de disposer d’un contrat stable pour le domaine, d’un adaptateur responsable de chaque protocole externe et d’une frontière de compte impossible à contourner par erreur. Une nouvelle source doit pouvoir entrer par le bon contrat sans ajouter une branche par marque dans le cas d’usage central.

La valeur du module vient de propriétés directement observables : validation des connexions, choix explicite du canal, déduplication, traitements séparés, planification, journalisation et protection de l’état en cas de relevé douteux. Ces mécanismes rendent l’intégration plus lisible à étendre, plus sûre à rejouer et plus précise à exploiter.

2. De flux séparés à une orchestration centrée fournisseur

Une évolution continue de mars à septembre 2026

Le périmètre retenu commence le 11 mars 2026, au moment où les offres évoluent vers des points de mesure et où le socle de tests est consolidé. Le 12 mars constitue le tournant : les collectes commandes et offres passent à une orchestration centrée sur le fournisseur, tandis que les anciens collecteurs séparés marketplace et e-commerce sont retirés.

En avril, le système dépasse la simple lecture. Le 25, la réconciliation sait désactiver les offres absentes d’un relevé complet. Le 26, l’intégration Mirakl est enrichie et des clients d’écriture de stock sont ajoutés. Cette extension rend nécessaire une distinction stricte entre les capacités réellement disponibles chez chaque fournisseur.

Les 8 et 9 septembre, plusieurs risques de production sont traités : bon identifiant pour Amazon Espagne, décodage des rapports compressés, conservation des offres après une réponse vide, signalement d’un relevé Amazon incomplet et harmonisation des statuts de commande. Les 183 jours calendaires entre les deux bornes montrent une architecture enrichie par étapes, au contact de formats et de comportements fournisseurs différents.

3. Pourquoi les API ne sont pas interchangeables

Partager un domaine sans fabriquer un protocole imaginaire

Une commande possède les mêmes notions générales quel que soit le canal : un identifiant, une date d’achat, un statut, une devise, un client et des lignes. Pourtant, Amazon, Cdiscount, Fnac Darty et Mirakl n’exposent pas ces éléments de la même manière. Les états n’emploient pas le même vocabulaire, les lignes ne se récupèrent pas toujours au même endroit et certaines informations restent facultatives.

Les offres présentent la même difficulté. Un canal peut identifier l’offre par le SKU vendeur, un autre séparer identifiant et condition. La pagination peut utiliser une page, un offset, un lien suivant ou un rapport asynchrone. La quantité, la devise, le fulfillment, les métadonnées produit et l’exhaustivité du relevé n’ont pas partout la même garantie.

La mauvaise réponse serait de disperser ces détails dans le domaine Ciama. Chaque nouveau fournisseur obligerait alors à modifier la collecte, la déduplication, l’écriture et les écrans. La réponse retenue consiste à donner aux adaptateurs la responsabilité de comprendre leur API, puis à exiger d’eux une collection de commandes ou d’offres conforme au contrat interne.

Cette frontière explique pourquoi le projet appartient à l’API marketplace technique. Son produit final n’est pas un écran isolé : c’est la capacité d’accueillir plusieurs protocoles externes sans transformer le cœur métier en succession de conditions propres à chaque marque.

4. La connexion fournisseur comme frontière

Refuser une collecte ambiguë avant le premier appel distant

Chaque collecte commence avec un identifiant de connexion fournisseur. Ciama refuse une connexion introuvable, inactive ou dont les accès ne sont pas valides. Il vérifie ensuite que le fournisseur existe, qu’il est actif et disponible. Si une version est attachée à la connexion, cette version doit elle aussi exister et être active.

Le canal peut être fourni explicitement. Dans ce cas, il doit appartenir au même compte et au même fournisseur que la connexion. Sans canal explicite, Ciama recherche les canaux actifs correspondants : aucun candidat produit une erreur, et plusieurs candidats aussi. Le système ne choisit donc pas arbitrairement lorsqu’une connexion pourrait alimenter deux canaux.

Ce contrôle protège la frontière multi-compte. Un identifiant de canal valide dans l’absolu ne suffit pas s’il dépend d’un autre compte. La relation avec le fournisseur est vérifiée avant de lire ou d’écrire une commande ou une offre, ce qui réduit le risque d’associer une donnée distante au mauvais espace commercial.

Les commandes acceptent les fournisseurs marketplace, e-commerce et ERP dans le cas d’usage commun. Les offres acceptent marketplace et e-commerce. Le module étudié réunit quatre familles marketplace ; les autres lecteurs configurés dans la plateforme prolongent le contrat commun vers leurs propres univers.

5. Deux contrats et huit adaptateurs

Sélectionner une capacité par support plutôt que par branche de marque

Le premier contrat demande à un lecteur s’il supporte une connexion, puis lui confie une période et un canal pour obtenir une collection de commandes. Le second applique la même logique aux offres. Les orchestrateurs parcourent les clients enregistrés, retiennent le premier compatible et lèvent une erreur explicite si aucun lecteur ne correspond.

Quatre lecteurs marketplace sont enregistrés pour les commandes : Amazon, Cdiscount, Fnac Darty et Mirakl. Quatre autres le sont pour les offres. Les huit adaptateurs couvrent donc deux intentions — commandes et offres — dans quatre familles, avec un spécialiste par combinaison.

Cette construction rend l’extension locale. Ajouter un fournisseur revient à implémenter le bon contrat et sa méthode de support, puis à enregistrer l’adaptateur. Le cas d’usage central continue de valider la connexion, choisir le canal, compter les objets et répartir ajout ou mise à jour sans connaître le protocole du nouveau venu.

L’unification reste volontairement limitée. Chaque adaptateur peut appliquer sa pagination, ses filtres, sa conversion de statuts et ses contrôles de réponse. Le domaine reçoit une forme commune ; il ne dicte pas à Amazon de fonctionner comme Fnac Darty ni à Mirakl d’abandonner ses champs enrichis.

6. Normaliser une commande

Conserver un noyau commun et accepter les absences de la source

Une commande normalisée conserve son identifiant externe, le canal, la date d’achat, le statut, la méthode de fulfillment et une collection obligatoire de lignes. Le pays, le prix TTC, la devise, la société, la TVA, le téléphone, le client et les adresses peuvent rester absents lorsque la source ne les fournit pas.

Chaque ligne porte au minimum les références et quantités nécessaires à l’écriture. Les adaptateurs traduisent leurs statuts vers le vocabulaire Ciama et indiquent si l’expédition est prise en charge par le vendeur. Amazon distingue notamment les commandes gérées par son réseau des expéditions vendeur.

La période de lecture est obligatoire pour les commandes et une borne de début postérieure à la fin est refusée. En planification, la fenêtre couvre les deux dernières heures. Ce chevauchement volontaire rend possible la reprise d’une commande modifiée récemment, à condition que l’identité métier empêche sa duplication.

Le contrat commun ne promet pas que tous les champs sont remplis avec la même profondeur. Il garantit plutôt que le domaine sait quelles données sont obligatoires, lesquelles sont optionnelles et à quel canal rattacher la vente. C’est une base fiable pour l’OMS, la recherche et les calculs ultérieurs.

7. Normaliser une offre

Rendre comparables SKU, quantité, prix, activité et fulfillment

L’offre commune porte le canal, l’identifiant vendeur, la condition, la quantité, le prix TTC, son état actif, le mode de fulfillment et la devise. Selon le fournisseur, elle peut aussi transporter un identifiant produit, un titre, une image, une marque, une catégorie ou des dates de création et de mise à jour.

Le prix source est conservé avant conversion. Lors de l’ajout ou de la mise à jour, Ciama peut demander une conversion vers l’euro à la date la plus pertinente disponible. Cette opération rend les montants utilisables dans un cadre commun, mais ne transforme pas le prix en marge ni en recommandation commerciale.

L’identité la plus précise associe canal, identifiant d’offre et condition. Un repli par canal et identifiant permet de reprendre des données existantes lorsque la condition évolue ou manque dans l’historique. Cette règle reste limitée au canal : un même identifiant sur deux marketplaces ne devient pas un doublon global.

La collection retournée transporte aussi un statut de complétude et des avertissements. Cette métadonnée ne décrit pas une offre ; elle qualifie la confiance que Ciama peut accorder à l’ensemble du relevé. Elle devient décisive lorsque le système envisage de désactiver les offres absentes.

8. Les particularités Amazon

API de commandes, rapports d’offres et limitation de débit

Pour les commandes récentes, l’adaptateur Amazon interroge l’API Orders avec une fenêtre de dernière mise à jour, récupère les lignes de chaque commande et suit la pagination par jeton. Pour l’historique, il peut demander un rapport, attendre sa disponibilité, télécharger le document et regrouper les lignes par identifiant de commande.

Le statut Amazon passe par un mapper dédié. Les variantes comme Pending, Unshipped, PartiallyShipped, Shipped, Cancelled ou Unfulfillable rejoignent des états Ciama cohérents. Le durcissement du 9 septembre a justement supprimé deux traductions concurrentes entre lecture planifiée et lecture historique.

Les offres Amazon viennent de deux rapports distincts : les listings vendeur et les quantités FBA. Un listing attendu mais absent, un rapport FBA manquant pour des offres FBA ou l’échec de conversion d’une ligne rendent le relevé incomplet. Les offres valides peuvent continuer à avancer, mais l’absence des autres n’est pas interprétée comme une suppression.

La lecture gère aussi la limitation 429 avec une temporisation croissante, tient compte de l’en-tête Retry-After et borne l’attente à 120 secondes. Les documents compressés et l’identifiant propre à Amazon Espagne ont fait l’objet de corrections datées du 8 septembre. Pour approfondir ce protocole, voir notre expertise Amazon SP-API.

9. Les particularités Cdiscount et Octopia

Parcourir les pages sans confondre lecture et écriture

L’adaptateur Cdiscount s’appuie sur les interfaces Octopia pour lire commandes et offres. La pagination des offres suit le lien suivant fourni par la réponse, avec un plafond de 500 pages. Ce plafond protège le collecteur contre une boucle distante incohérente sans prétendre que tous les catalogues atteignent ce volume.

Les statuts et conditions sont traduits dans les objets Ciama avant écriture. Les identifiants restent liés au canal Cdiscount, ce qui permet de rejouer un relevé sans collision avec un SKU identique présent sur Amazon ou Fnac Darty.

La capacité de rafraîchir une offre Cdiscount existe. En revanche, le client déclaré pour pousser une quantité reconnaît bien le fournisseur mais lève immédiatement une erreur « non implémenté ». Le périmètre Cdiscount couvre donc la relecture ciblée, mais pas encore la mise à jour distante du stock.

Cette frontière est essentielle pour cadrer un déploiement. Ciama sait lire et normaliser Cdiscount ; un besoin de diffusion de stock demande encore un chantier spécifique et ses tests de contrat. Les pages API Cdiscount et intégration Octopia permettent de cadrer cette suite.

10. Les particularités Fnac Darty

Assumer un protocole XML dans un domaine commun

Fnac Darty utilise un dialogue XML. Le client s’authentifie avec les informations du compte vendeur, puis les lecteurs transforment les réponses de commandes et d’offres en collections Ciama. Les offres sont parcourues par pages de 200 résultats selon le nombre total de pages retourné.

La condition du produit est traduite depuis les codes Fnac vers les états acceptés par Ciama. Une condition explicite inconnue peut conduire à écarter l’offre plutôt qu’à lui attribuer arbitrairement un état neuf, occasion ou reconditionné.

Le rafraîchissement ciblé cherche une offre par SKU vendeur, vérifie quantité et prix, puis produit l’objet commun. L’écriture de stock construit de son côté un document XML offers_update, attend une réponse valide et exige un identifiant de lot. Le stock négatif n’est pas envoyé tel quel.

Cette implémentation montre l’intérêt de l’adaptateur : le domaine ne manipule ni XML, ni jeton Fnac, ni taille de page. Il demande une offre ou une commande normalisée. Pour une intégration dédiée, notre page API Fnac Darty prolonge ce cas.

11. Les particularités Mirakl

Une famille d’API capable de servir plusieurs marketplaces

Mirakl n’est pas traité comme un canal unique. L’adaptateur peut supporter une connexion Mirakl et des catalogues comme Cultura, avec une URL fournie par les accès ou une configuration connue. Les commandes et offres sont lues par les API de la plateforme puis rattachées au canal demandé.

Les offres Mirakl acceptent plusieurs noms possibles pour certaines informations : SKU, quantité, prix ou devise. Lorsque la réponse les contient, le connecteur peut également enrichir titre, description, image, identifiant produit, catégorie et dates. Ces champs restent facultatifs et ne sont jamais présentés comme garantis par toutes les implémentations Mirakl.

Le rafraîchissement cible le SKU vendeur et peut exiger la quantité selon le contexte. La mise à jour de stock génère un fichier CSV envoyé au point d’import Mirakl, avec la clé d’API et éventuellement l’identifiant de boutique. Le retour du fournisseur doit confirmer la création de l’import.

La famille conserve donc un noyau commun tout en laissant la configuration d’hôte au niveau de la connexion. Cela évite d’inscrire chaque opérateur utilisant Mirakl dans le domaine. Pour ce type de déploiement, voir l’intégration API Mirakl.

12. Ajouter ou mettre à jour sans doublon

Faire de l’identité canal–objet une règle métier

Après la lecture, Ciama ne persiste pas aveuglément toute la collection. Pour une commande, il cherche le couple canal–identifiant externe. L’absence distribue une demande d’ajout ; la présence distribue une demande de mise à jour. Un même relevé conduit donc au même objet métier plutôt qu’à une nouvelle commande.

Pour une offre, la recherche commence par canal, identifiant et condition, puis se replie sur canal et identifiant. Les demandes d’ajout et de mise à jour sont également séparées. Les réponses de collecte exposent combien d’objets ont été lus et combien de messages de chaque type ont été distribués.

Ces compteurs décrivent une décision d’orientation. Ils ne prouvent pas encore que chaque écriture asynchrone est terminée avec succès. Le message peut attendre, échouer ou être repris. Cette nuance empêche de transformer « 100 messages envoyés » en « 100 objets synchronisés » sans consulter l’état d’exécution.

L’identité scellée par le canal évite aussi une collision entre deux écosystèmes. Deux marketplaces peuvent employer le même SKU ou le même identifiant de commande sans que Ciama les fusionne. Le canal reste une partie de la vérité métier, pas un simple filtre d’écran.

13. Protéger l’état des offres

Trois conditions avant de désactiver ce que la source ne renvoie plus

Une synchronisation d’offres doit résoudre une ambiguïté dangereuse : une offre absente a-t-elle été supprimée du canal, ou manque-t-elle parce que la réponse est vide, paginée, partielle ou en erreur ? Interpréter chaque absence comme une désactivation transformerait une panne fournisseur en suppression de catalogue.

Ciama ne désactive les offres actives absentes que si trois conditions sont réunies. La demande doit être un relevé global sans bornes de dates ; au moins une offre doit avoir été collectée ; la collection doit se déclarer complète. La désactivation reste ensuite limitée au canal concerné.

Une réponse vide conserve donc l’état connu. Un relevé incomplet peut mettre à jour les offres valides qu’il contient, transmettre ses avertissements et indiquer son manque de complétude, sans désactiver les identifiants non vus. Le garde-fou vide date du 8 septembre et la propagation de complétude Amazon du 9.

Cette règle apporte un gain observable de sécurité opérationnelle : la donnée existante ne disparaît pas du seul fait qu’un fournisseur n’a rien renvoyé. Elle ne garantit pas que toute offre est exacte ; elle empêche une conclusion destructrice lorsque la preuve d’absence n’est pas suffisante.

14. Asynchrone et journal d’exécution

Séparer collecte, ajout et mise à jour pour suivre leur état

Les collectes planifiées n’exécutent pas toutes les écritures directement dans le processus planifié. Elles ouvrent un journal d’exécution puis distribuent un message portant la connexion, la période et le contexte. Les cas d’usage séparent ensuite les messages d’ajout et de mise à jour pour commandes et offres.

Le journal démarre en attente avec une progression nulle. Il conserve le compte, la connexion, le fournisseur, sa version éventuelle, la période et le nom du message ou de la commande. Cet ancrage permet de relier une opération technique au bon périmètre commercial.

La séparation améliore la lisibilité d’une reprise : relancer une collecte n’impose pas de confondre la lecture distante avec la création d’un objet. Elle ne constitue cependant pas une garantie d’exécution exactement une fois. La fiabilité finale dépend des clés métier, des handlers, des transactions et de la capacité à reprendre les messages en erreur.

L’asynchrone repose sur Symfony Messenger et les files configurées dans Ciama. Ce choix reste cohérent avec l’application Symfony et permet de séparer les responsabilités sans introduire une seconde plateforme d’événements. Un autre transport ne se justifierait que par des contraintes mesurées de volume, de reprise ou de contrats.

Faire évoluer cette orchestration vers une plateforme d’événements Confluent constituerait un chantier séparé, pertinent seulement si les contraintes de débit et de rejeu le demandent. Dawap peut alors cadrer une intégration Confluent autour des flux réellement concernés.

15. Cadences et activation

Planifier une capacité seulement lorsque la connexion l’autorise

En production, la commande de collecte des commandes est planifiée toutes les dix minutes. Chaque exécution cherche les connexions dont la fonction orders_sync est active, ignore les connexions inactives ou invalides ainsi que les fournisseurs indisponibles, puis distribue une fenêtre couvrant les deux dernières heures.

Les offres sont collectées toutes les deux heures. La commande cible la fonction offers_sync active et demande un relevé global sans bornes, condition nécessaire à une éventuelle réconciliation. Connexion et fournisseur passent les mêmes contrôles avant distribution.

Le chevauchement de deux heures pour les commandes rend la collecte tolérante à un passage manqué ou à une modification tardive, grâce à la déduplication par canal et identifiant. Le relevé global des offres sert une autre finalité : comparer l’état actuel reçu à l’état actif connu.

Ces cadences organisent l’exploitation sans devenir des engagements contractuels. Le réglage doit rester lié aux quotas, au volume, au temps d’attente dans les files et au besoin métier de chaque compte.

16. Lecture et écriture : la frontière

Ne jamais déduire une capacité de diffusion d’un connecteur de collecte

Les quatre familles possèdent un lecteur de commandes et un lecteur d’offres. Des clients de rafraîchissement ciblé existent aussi pour Amazon, Cdiscount, Fnac Darty et Mirakl. Ces capacités permettent de relire une offre précise sans rejouer nécessairement tout le catalogue.

La diffusion de stock n’a pas exactement le même périmètre. Amazon, Fnac Darty et Mirakl disposent d’une écriture distante concrète avec validation de la réponse. Le client Cdiscount reconnaît le fournisseur, mais son traitement lève une erreur non implémentée. Une interface commune n’efface donc pas l’absence d’adaptateur opérationnel.

Le repricing est encore plus spécifique. Le composant d’écriture présent dans ce périmètre prend en charge Amazon Europe, convertit le prix vers la devise du canal puis envoie une modification de l’offre. Aucun composant équivalent Cdiscount, Fnac Darty ou Mirakl n’est configuré dans cette architecture.

Cette cartographie permet un cadrage honnête : lecture commandes, lecture offres, rafraîchissement, stock et prix sont évalués séparément pour chaque fournisseur. Une proposition peut ainsi chiffrer la capacité manquante au lieu d’annoncer un connecteur « complet » sans définir ce que complet signifie.

17. La couverture de qualité

Tester le cœur commun et les différences qui peuvent casser un flux

Des tests unitaires et d’intégration ciblent les collecteurs de commandes et d’offres, leurs handlers et leurs commandes planifiées. Ils vérifient notamment les validations de connexion, la résolution du canal, la séparation ajout–mise à jour et les compteurs de réponse.

Les adaptateurs possèdent leurs propres contrôles. Les scénarios couvrent des lecteurs Amazon et des clients d’écriture ou de rafraîchissement pour les fournisseurs marketplace. Des réponses de référence conservées pour Fnac Darty, Mirakl/Cultura et Cdiscount/Octopia permettent de tester la forme réelle des charges utiles sans appeler les API en direct pendant PHPUnit.

Les garde-fous de réconciliation ont des tests dédiés. Une réponse vide ne désactive pas l’existant. Un relevé incomplet peut retourner ses avertissements sans supprimer les absences. La planification de production est elle aussi contrôlée afin d’éviter qu’une commande disparaisse silencieusement du crontab.

La couverture est suivie par scénarios plutôt que résumée à un pourcentage global : contrat commun, comportement de chaque adaptateur, réponses vides ou incomplètes et présence des tâches planifiées. Les corrections Amazon des 8 et 9 septembre rappellent qu’un connecteur externe reste un composant vivant : nouveaux formats, statuts, compression, quotas et comportements de source doivent être suivis.

18. Les capacités réellement livrées

Des bénéfices directement attribuables à l’architecture

Pour l’équipe qui ajoute un fournisseur, la valeur réside dans les deux contrats et la sélection par support. L’adaptateur absorbe authentification, pagination et vocabulaire distant ; le domaine conserve validation, identité, ajout, mise à jour et distribution. L’extension ne demande pas de recopier tout le pipeline.

Pour l’exploitation, chaque collecte part d’une connexion et d’un canal vérifiés, possède un journal et distribue des messages distincts. Une ambiguïté de canal devient une erreur visible plutôt qu’un choix silencieux. Une réponse d’offres vide ou incomplète ne se transforme pas en suppression de masse.

Pour les équipes métier, les commandes et offres rejoignent des objets comparables sans perdre leur canal, leur devise ou leur mode de fulfillment. Cette normalisation alimente les recherches et outils Ciama, mais ne prétend pas que toutes les sources offrent la même richesse de données.

Pour le cadrage commercial, la matrice de capacités évite un mot-valise. Amazon, Cdiscount, Fnac Darty et Mirakl sont confirmés en lecture commandes et offres. Stock, rafraîchissement et repricing sont qualifiés séparément. Le résultat observable est un périmètre technique vérifiable, extensible, qui fait apparaître sans ambiguïté les capacités restant à développer.

19. Choisir la bonne suite

Passer de la preuve technique au chantier adapté

Si le besoin porte d’abord sur authentification, quotas, pagination, mapping, webhooks ou résilience d’un fournisseur, la bonne porte est l’intégration API marketplace. Les pages Amazon SP-API, Cdiscount, Fnac Darty et Mirakl précisent chaque écosystème.

Si le besoin porte sur la diffusion d’offres, les stocks, l’ERP, les erreurs et le run quotidien d’un vendeur, l’accompagnement connecteurs marketplace et ERP devient prioritaire. La couche API reste le moyen ; la continuité opérationnelle vendeur devient le résultat recherché.

Si commandes, offres, stock, marge et supervision doivent former un cockpit récurrent, le prolongement est Ciama Marketplace. Le produit capitalise sur le socle commun au lieu de transformer chaque nouveau canal en projet isolé.

Enfin, lorsqu’aucune solution standard ne couvre les contrats ou règles attendus, notre expertise de création d’API sur mesure permet de concevoir le middleware, ses objets, ses reprises et son observabilité. Retrouvez aussi l’ensemble de nos projets d’intégration API.