Ciama × 1UP Distribution : synchroniser le catalogue Odoo 19 sans perdre les champs métier

1. 1UP Distribution, un catalogue où les attributs conditionnent plusieurs opérations

Faire d’Odoo la source d’identité sans réduire Ciama à un miroir

1UP Distribution s’appuie sur Odoo pour référencer ses produits. L’identifiant interne Odoo, le SKU, le template, le code-barres, les prix, le poids et le statut constituent le socle standard. Des champs Studio complètent ce socle pour refléter la réalité de son catalogue.

Ces attributs servent des usages différents dans Ciama. Le SKU et l’identifiant ERP permettent de retrouver le bon produit ; la marque et la catégorie structurent la navigation et les agrégats ; le poids et les dimensions éclairent la logistique ; la date de sortie fournit un repère catalogue ; le template relie les variantes et leurs images.

La difficulté n’était donc pas de copier une table. Ciama possède ses propres produits, relations, contrôles de qualité, offres marketplace, stocks et historiques. L’intégration devait traduire les objets Odoo dans ce modèle sans perdre leur origine ni écraser les relations déjà utiles.

Le projet se concentre sur cette traduction. Les commandes B2B Odoo, les devis, les factures et les achats fournisseurs empruntent la même fondation de connexion, mais chacun possède son propre contrat et son propre cycle fonctionnel.

2. Séparer transport Odoo, contrat catalogue et mapping 1UP

Trois responsabilités pour faire évoluer le connecteur sans mélanger les règles

La première couche sait parler à Odoo 19. Elle teste la connexion et expose des opérations génériques de recherche, comptage, lecture et recherche avec lecture. Elle ne décide pas comment un produit 1UP doit devenir un produit Ciama.

La deuxième couche porte les contrats du catalogue. Produits, catégories, tags et marques sont demandés par des objets dédiés puis convertis en modèles de lecture. Cette frontière permet à un autre client ERP compatible d’implémenter le même besoin sans recopier les règles du PIM.

La troisième couche traite le cas 1UP. Elle ajoute les champs Studio, choisit l’ordre des replis, retire les racines techniques de la catégorie, retrouve le produit cible et orchestre l’ajout, la mise à jour, la marque, la catégorie et la demande de synchronisation des images.

Ce découpage a rendu possible la migration de protocole de juillet puis le rétablissement du flux spécialisé en septembre. La connexion commune a changé sans obliger le modèle métier à redevenir une simple réponse Odoo brute.

3. Avant la consolidation : un connecteur standard pouvait perdre les attributs qui font le produit

Une synchronisation réussie n’est pas forcément un référentiel fidèle

Le lecteur de catalogue générique Odoo connaît les champs communs : identifiant, template, SKU, nom, code-barres, poids, statut, prix de vente, coût et date de modification. Cette base suffit à représenter un produit simple, mais pas toutes les particularités de 1UP.

Les dimensions, le poids brut en grammes, la date de sortie et la marque éditeur sont portés par des champs Studio. La catégorie arrive sous forme de chemin complet comprenant des racines d’organisation Odoo qui ne doivent pas nécessairement devenir des catégories visibles dans Ciama.

Le passage à Odoo 19 a ajouté une autre contrainte : les anciennes synchronisations ne devaient plus continuer en parallèle du protocole JSON-2. Garder deux chemins aurait entretenu des règles concurrentes, des identifiants interprétés différemment et des résultats difficiles à comparer.

Le risque à résoudre était donc double : moderniser le transport sans réintroduire les anciens appels, puis restaurer la richesse 1UP au-dessus du nouveau socle. Le flux livré en septembre assume explicitement ces deux responsabilités.

4. Activer une connexion ERP seulement après un test réussi

Hôte, base et clé API vérifiés avant d’ouvrir le flux

Les ERP disponibles apparaissent dans un espace de configuration propre au compte. Pour Odoo, l’utilisateur choisit une version active et renseigne les éléments nécessaires à la connexion ; Odoo 19 est proposé lorsqu’il est disponible dans le référentiel des versions.

L’activation n’est pas immédiate. Le formulaire vérifie d’abord les informations obligatoires, exécute un test de connexion puis enregistre en session que ce contrôle a réussi. Sans cette étape, la demande d’activation est refusée.

Le test appelle un comptage simple sur les sociétés Odoo et mesure la latence. Il renvoie un succès ou une erreur structurée sans lancer une collecte de catalogue. Une clé API, un hôte ou une base manquante bloque avant toute requête réseau.

Une fois active, la connexion reste rattachée au compte. Les services de lecture refusent une connexion absente ou désactivée, puis choisissent seulement un client qui déclare prendre en charge son fournisseur et sa version.

5. Utiliser exclusivement l’API JSON-2 d’Odoo 19

Un transport unique, authentifié par clé et base ciblée

Le client construit ses appels sur le chemin JSON-2 formé par le modèle et la méthode Odoo. Les paramètres sont envoyés en JSON par requête POST, avec la clé API dans l’autorisation et la base dans un en-tête distinct.

Les anciens identifiant utilisateur et mot de passe ne participent pas à ce transport. Le client accepte les connexions marquées V19 ou « latest » et refuse explicitement une version V18 dans cette implémentation.

Recherche, comptage, lecture et recherche avec lecture utilisent le même passage. Les offsets et limites ne peuvent pas devenir négatifs ; un ordre n’est ajouté que lorsqu’il est renseigné ; un contexte francophone cohérent accompagne les requêtes.

Un statut HTTP hors succès devient une erreur avec un message extrait de la réponse lorsque celui-ci existe. Une réponse non décodable et une panne de transport reçoivent leurs propres causes. La couche métier n’a pas à interpréter une page d’erreur comme un tableau vide.

6. Donner au catalogue un contrat indépendant du fournisseur

Produits, catégories, tags et marques partagent une même porte d’entrée

Le service catalogue expose quatre collections : produits, catégories, tags et marques. Chaque demande porte sa connexion, sa fenêtre éventuelle, son offset, sa limite et son ordre lorsque ces paramètres ont un sens.

Le service retrouve la connexion active puis parcourt les clients catalogue disponibles jusqu’à trouver celui qui la prend en charge. Une connexion Odoo 19 arrive ainsi sur le lecteur Odoo sans que l’appelant connaisse sa classe concrète.

Les réponses brutes deviennent des modèles de lecture. Une catégorie conserve son identifiant, son nom, son chemin complet et son parent ; un tag garde son identité ; une marque absente du module Odoo concerné revient comme une collection vide plutôt que faire échouer tout le catalogue.

Cette abstraction ne prétend pas uniformiser tous les ERP. Elle fixe ce que Ciama attend du catalogue et laisse chaque adaptateur traduire son fournisseur. Les particularités 1UP restent ensuite dans un mapper séparé.

7. Collecter par fenêtre de modification et par pages de 200

Un parcours borné qui peut rejouer une période précise

Le flux 1UP accepte une date de début et une date de fin. Une date simple ouvre à minuit ou ferme à 23 h 59 min 59 s selon sa position ; une borne de début postérieure à la fin arrête le passage avant toute écriture.

La requête cible les variantes de produit consommables dont la date de modification Odoo se trouve dans cette fenêtre. Les résultats sont ordonnés par date croissante puis identifiant croissant, afin de garder un parcours stable lorsque plusieurs produits partagent le même instant.

Chaque page contient au maximum deux cents lignes. L’offset avance de deux cents et la collecte s’arrête dès qu’une page est plus courte. Ce choix borne la réponse Odoo sans imposer une limite globale au catalogue.

En production, la tâche s’exécute toutes les deux heures avec une fenêtre glissante de trois heures. Le recouvrement réduit le risque de manquer une modification à la frontière ; la logique d’ajout ou de mise à jour permet de relire un produit déjà rencontré.

8. Demander vingt champs utiles au référentiel 1UP

Douze attributs communs et huit particularités de catalogue

La requête lit l’identifiant, le statut actif, le nom, le SKU, le code-barres, la catégorie, deux champs de prix, le coût standard, le poids, la date de modification et le template Odoo.

Elle ajoute trois dimensions Studio en millimètres, le poids brut et le poids net en grammes, la date de sortie, la marque éditeur et le type de produit. Ce dernier sert aussi à filtrer les variantes consommables.

Tous ces champs ne sont pas écrits aveuglément au même endroit. Le mapper construit un produit normalisé puis remet la marque et le chemin de catégorie à l’orchestrateur, qui applique les services métier correspondants.

La réponse brute reste associée au modèle lu. Elle permet de conserver le contexte fournisseur sans rendre les autres couches dépendantes de chaque nom de champ Studio.

9. Rapprocher d’abord l’identifiant ERP, puis le SKU

Éviter le doublon sans dépendre d’une seule clé

Une ligne Odoo dépourvue d’identifiant ou de SKU exploitable est classée comme ignorée. Le flux ne crée pas un produit anonyme qu’il serait ensuite impossible de retrouver de manière déterministe.

Pour une ligne valide, Ciama recherche d’abord un produit du même compte portant l’identifiant ERP. Cette clé conserve le lien le plus direct avec l’enregistrement Odoo.

Si cette recherche échoue, le SKU sert de repli dans le même compte. Ce deuxième passage permet de rattacher un produit déjà créé avant que son identifiant ERP ait été correctement stocké.

Le résultat détermine une action d’ajout ou de mise à jour. Le flux ne compare jamais l’identifiant à un autre compte, et il ne transforme pas une absence de correspondance en écrasement arbitraire d’un produit voisin.

10. Traduire les champs Studio sans perdre leurs unités

Millimètres, grammes et date de sortie gardent leur sens

Le poids brut Studio est lu directement en grammes. Lorsqu’il manque, le poids standard Odoo exprimé en kilogrammes est multiplié par mille. Le repli conserve ainsi l’unité attendue par Ciama au lieu de comparer 1,75 à 820 comme s’il s’agissait de la même échelle.

Largeur, hauteur et longueur sont converties en nombres uniquement si leur valeur est numérique. Une chaîne vide ou une valeur booléenne ne devient pas artificiellement zéro.

La date de sortie est transformée en date immuable. Une valeur impossible reste absente plutôt que provoquer l’arrêt de tout le produit. Le statut actif, les prix, le code-barres et le template suivent la même logique de normalisation explicite.

Ce mapping est propre à 1UP. Il documente la différence entre le schéma Odoo générique et la signification réelle des champs Studio du distributeur, sans contaminer le contrat catalogue commun.

11. Créer ou retrouver la marque avant de la rattacher au produit

La marque éditeur devient une relation du PIM

Le champ Studio de marque est nettoyé de ses espaces. Lorsqu’il contient une valeur, le flux passe par le service d’ajout de marque, qui peut créer ou retrouver l’objet correspondant dans le compte.

Le produit est ensuite relié à cette marque en utilisant son identifiant ERP et son SKU. Si le champ marque est absent, la relation peut être remise à vide plutôt que conserver silencieusement une ancienne valeur.

Une erreur de création ou de rattachement incrémente le compteur d’erreurs de la synchronisation. Elle n’est pas transformée en réussite globale simplement parce que les champs principaux du produit ont été écrits.

La marque devient ainsi une dimension exploitable par les vues produit et les agrégats, sans rester une chaîne libre copiée sur chaque fiche.

12. Reconstituer la hiérarchie utile de catégorie

Retirer les racines Odoo avant de bâtir l’arbre Ciama

Odoo fournit la catégorie sous forme d’identifiant et de chemin complet. Le mapper découpe ce chemin sur les séparateurs, retire les segments vides puis écarte les deux premiers niveaux d’organisation.

Ainsi, un chemin de type « All / Sellable / Games / Board games » devient une hiérarchie métier « Games / Board games ». Les racines techniques ne polluent pas la navigation du PIM.

L’orchestrateur parcourt ensuite les segments dans l’ordre. Chaque catégorie est ajoutée ou retrouvée avec le parent déjà résolu ; le dernier niveau est enfin associé au produit.

Une nouvelle catégorie peut donc enrichir l’arbre sans nécessiter une table de correspondance codée à l’avance. Une erreur sur un niveau est toutefois signalée et empêche un rattachement partiel présenté comme complet.

13. Synchroniser les images sans confondre template et variante

Quatre sources Odoo réunies puis dédupliquées

Après l’écriture d’un produit, le flux peut envoyer un message de synchronisation d’images. Le traitement est séparé de la page de catalogue : une image lourde ou absente ne bloque pas la lecture des deux cents produits suivants.

Le synchroniseur consulte l’image principale du template, l’image principale de la variante, la galerie native Odoo et une galerie complémentaire. Pour chaque source, il recherche les variantes 1920, 512 et 128 disponibles.

Les médias sont dédupliqués avant écriture. Une vidéo référencée dans la galerie native n’est pas traitée comme une image. Le propriétaire — template ou variante — et le rôle principal ou galerie restent conservés.

Quand plusieurs produits partagent un template, leur image principale est rafraîchie après la synchronisation. Le référentiel peut ainsi profiter du média commun sans perdre la capacité d’une variante à porter sa propre image.

14. Écrire le produit par services métier plutôt que par mise à jour directe

Ajout, mise à jour et relations suivent leurs propres règles

Selon le rapprochement, le flux appelle le service d’ajout ou de mise à jour de produit avec le compte, la connexion fournisseur et le produit normalisé. Il récupère l’identifiant Ciama seulement si la réponse ne contient pas d’erreur.

La marque et la catégorie sont ensuite traitées par des services distincts. Cette séquence évite une écriture monolithique qui laisserait une fiche à moitié cohérente sans expliquer quelle étape a échoué.

Une option de simulation lit, classe et compte les lignes sans modifier Ciama. Une autre option évite d’envoyer les messages d’images. Ces deux leviers permettent de contrôler une période ou d’isoler le catalogue des médias.

Une erreur inattendue sur un produit est capturée avec le type d’erreur et les identifiants disponibles, puis le passage continue. Le flux privilégie une série complète assortie d’un bilan à l’abandon silencieux au premier cas particulier.

15. Rendre chaque passage lisible par ses compteurs et ses journaux

Collectés, ajoutés, mis à jour, ignorés, en erreur et images demandées

Le bilan distingue six compteurs. « Collectés » mesure les lignes Odoo parcourues ; « ajout » et « mise à jour » décrivent la décision de rapprochement ; « ignorés » couvre les lignes sans identité exploitable ; « erreurs » rassemble les échecs métier ou inattendus ; « images » compte les messages envoyés.

Chaque page traitée affiche son offset et son nombre de lignes. À la fin, le bilan rappelle aussi si le passage était une simulation. Une exécution avec au moins une erreur retourne un état d’échec, même si de nombreux produits ont été correctement écrits.

Le client JSON-2 journalise le début et la fin des recherches avec le modèle, la pagination, le nombre de lignes et la durée. Les erreurs de transport ou de statut HTTP suivent un chemin séparé.

Ces signaux permettent de distinguer une fenêtre sans modification, une page partiellement ignorée, un problème d’identité produit, une erreur Odoo ou un échec de relation dans le PIM.

16. Faire vivre le référentiel dans la production Ciama

Une tâche courte toutes les deux heures et un historique rejouable

La production lance le flux complet 1UP à la trentième minute toutes les deux heures. Il relit les trois dernières heures, utilise l’environnement de production et n’envoie pas les images dans ce passage régulier.

Cette fenêtre chevauchante accepte qu’un même produit soit relu. L’identifiant ERP puis le SKU conduisent alors vers la mise à jour, ce qui est plus sûr qu’une fenêtre sans recouvrement qui pourrait manquer une écriture Odoo tardive.

Les images suivent leur propre file et peuvent être déclenchées depuis l’ajout, la mise à jour ou une commande dédiée. Le catalogue courant n’attend donc pas l’écriture de plusieurs tailles de fichiers avant de passer au produit suivant.

Pour une reprise, les bornes de date peuvent couvrir une période plus large et la simulation permet de connaître le volume d’ajouts, de mises à jour et d’ignorés avant de modifier le référentiel.

17. Tester le protocole, le temps et le mapping métier

Les régressions les plus risquées sont contrôlées à leur frontière

Les tests du client vérifient que le comptage utilise bien JSON-2, une requête POST, une autorisation par clé et l’en-tête de base, sans revenir à l’ancien chemin JSON-RPC. Ils contrôlent aussi l’échec avant réseau lorsqu’une clé manque.

La sélection de version est couverte : V19 et « latest » sont acceptés, V18 est refusé. Les formats de dates, le tri du plus récent et le découpage des historiques possèdent leurs propres scénarios.

Le mapper 1UP est testé avec les champs Studio historiques : dimensions, poids brut, date de sortie, marque et hiérarchie. Un second cas valide le repli du kilogramme Odoo vers les grammes ; un troisième confirme qu’un SKU absent fait ignorer la ligne.

Des fixtures enregistrent aussi des réponses Odoo pour les produits, fournisseurs, achats et commandes B2B. Elles sécurisent les contrats de collecte sans exposer de clé de connexion réelle dans les parcours publics.

18. Les arbitrages qui rendent le connecteur maintenable

Générique là où le protocole est stable, spécifique là où le métier l’exige

Le premier arbitrage garde JSON-2 dans un client commun. Authentification, erreurs, pagination et journalisation n’ont pas à être réécrites dans chaque flux Odoo.

Le deuxième isole le mapping 1UP. Les champs Studio ne deviennent pas artificiellement la définition universelle d’un produit ERP ; ils enrichissent seulement le compte dont ils portent la réalité.

Le troisième privilégie l’identifiant ERP puis le SKU. Cette double clé limite les doublons pendant la transition sans considérer deux produits de comptes différents comme équivalents.

Le quatrième sépare catalogue et images. La fiche produit peut être écrite rapidement, tandis que les quatre sources de média suivent un traitement asynchrone plus coûteux.

Le cinquième fait échouer le bilan global si au moins une ligne a rencontré une erreur, mais laisse la série continuer. L’exploitation obtient à la fois les produits valides et un signal clair sur les cas à reprendre.

19. Ce qui change après la livraison

Le référentiel Ciama conserve les attributs qui donnent du sens aux usages aval

Un produit Odoo valide peut être ajouté ou mis à jour dans Ciama avec son identité ERP, son SKU, son template, son code-barres, ses prix, son poids, ses dimensions, son statut et sa date de sortie. La marque et la catégorie deviennent des relations du PIM plutôt que des chaînes isolées.

La synchronisation incrémentale ne dépend plus d’un ancien protocole concurrent. Une même couche JSON-2 sert le test de connexion et les lectures, tandis que le flux 1UP garde les règles qui lui sont propres.

L’exploitation peut simuler une fenêtre, désactiver les images, suivre six compteurs et distinguer une erreur de connexion d’une ligne sans SKU ou d’un rattachement métier échoué. Le diagnostic part du bon niveau.

Les tâches régulières ramènent les modifications Odoo dans Ciama toutes les deux heures. Le recouvrement de trois heures et la mise à jour déterministe rendent une modification relisible sans fabriquer un second produit.

Enfin, le référentiel enrichi fournit une base plus juste aux offres, aux stocks, à la qualité catalogue, à la marge et aux achats. C’est la valeur concrète des connecteurs marketplace ERP lorsqu’ils sont pensés comme une continuité métier.

20. Le scénario terrain qui résume le projet

Un nouveau jeu Odoo doit rejoindre Ciama avec sa catégorie, sa marque et sa logistique

Un produit consommable est modifié dans Odoo avec un identifiant, un SKU, un template, une marque Studio, un chemin de catégorie, trois dimensions, un poids brut, une date de sortie et un code-barres.

Le prochain passage inclut sa date de modification dans la fenêtre de trois heures. La ligne entre dans une page de deux cents, le mapper valide ses deux identifiants et transforme les unités sans perdre les champs Studio.

Ciama ne trouve pas encore son identifiant ERP mais reconnaît son SKU : il choisit donc la mise à jour plutôt qu’un doublon. La marque est ajoutée ou retrouvée, le chemin Odoo est réduit à ses niveaux métier, puis la dernière catégorie est rattachée au produit.

Si les images sont demandées, un message séparé recherche le template, la variante et les galeries, déduplique les médias et rafraîchit l’image principale des produits qui partagent le template.

Le bilan comptabilise une mise à jour et, le cas échéant, une demande d’images. Si le SKU avait été vide, la ligne aurait été classée comme ignorée ; si une relation avait échoué, l’exécution aurait continué tout en retournant un échec à reprendre.

21. Relier le référentiel ERP aux projets qui l’exploitent

Produit, vente, achat et contrôle qualité gardent chacun leur responsabilité

La synchronisation des stocks ERP et marketplaces décrit la quantité diffusable, sujet volontairement séparé de la présente identité produit.

Le référentiel fournisseurs et achats utilise Odoo pour suivre fournisseurs, commandes et lignes d’achat. La lecture des commandes B2B traite les ventes Odoo après leur collecte.

Le projet de qualité du catalogue rend notamment visible l’absence d’identifiant ERP. Il donne une destination opérationnelle aux garde-fous du mapping.

Dans Ciama Marketplace, ces briques partagent une même source sans devenir un flux indistinct : le connecteur produit préserve le référentiel, puis chaque module applique son contrat métier.