Introduction

Gérez les produits de commerce électronique avec des catalogues dynamiques, des filtres et des recherches.

Plus d'informations sur le Catalogue dans le panneau d'administration OneEntry : https://doc.oneentry.cloud/docs/category/catalog

---

🎯 Que fait ce module ?

Le module Products (Catalogue) vous permet de récupérer, filtrer, rechercher et trier des produits dans votre boutique en ligne ou vos collections multimédias. Vous gérez le catalogue dans le panneau d'administration OneEntry (Catalogue > Produits) ; votre application récupère les produits de manière dynamique, donc changer un prix ou un attribut dans l'administration est effectif immédiatement sans redéploiement.

Au-delà du commerce électronique, le Catalogue convient également aux galeries multimédias, aux portfolios, aux bibliothèques de documents et à d'autres collections de contenu.

🚀 Démarrage rapide

Initialisez le module à partir de defineOneEntry :

const { Products } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Récupérez une page de produits et lisez leurs champs :

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

La plupart des méthodes de listing partagent la même structure : un filtre body optionnel, un langCode, et un userQuery optionnel (pagination/tris). Voir Paramètres ci-dessous pour l'ensemble complet.

✨ Concepts clés

Qu'est-ce qu'un produit ?

Un produit est une entité de catalogue (IProductsEntity) composée de :

• Informations de base - localizeInfos (titre, etc.), sku, prix
• Images - photos de produits / galerie (stockées en tant qu'attributs)
• Attributs personnalisés - tous les champs que vous définissez (attributeValues) : marque, matériau, taille, couleur, variantes, stock, …
• Localisation - contenu par langue

Il n'y a pas de types de produits fixes dans le SDK — toute structure (variantes, options, téléchargements, bundles) est modélisée avec les attributs personnalisés que vous configurez pour le catalogue.

Organisation des produits

Les produits sont organisés à travers plusieurs fonctionnalités du catalogue :

• Catégories - sections du catalogue (pages de type Catalogue, créées dans le module Pages)
• Statuts des produits - conditions de filtrage supplémentaires au-delà des filtres d'attributs (par exemple, "en stock", "en solde")
• Liens de produits - connectez des produits par critères d'attributs (par exemple, tous les téléphones noirs ensemble)
• Filtres de produits - recherche rapide par critères de filtre spécifiés
• Attributs personnalisés - marque, taille, couleur, matériau, …

Exemple de hiérarchie :

📁 Electronics
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

📋 Ce que vous devez savoir

Architecture du catalogue

Les catégories de catalogue sont des pages de type Catalogue créées via le module Pages — créez-les avant d'ajouter des produits :

1. Ouvrez le module Pages dans le panneau d'administration.
2. Créez des pages de type Catalogue — celles-ci deviennent vos catégories de produits.
3. Ajoutez des produits à ces catégories via Catalogue > Produits.

Le catalogue d'administration fournit également un Téléchargement en masse du Catalogue, des Filtres de Produits, des Liens de Produits, des Statuts de Produits, et des Paramètres par catalogue.

Pagination

Ne chargez pas tout d'un coup — parcourez les résultats avec limit et offset :

Formule d'offset : offset = (pageNumber - 1) * limit

Limite par défaut : vous pouvez récupérer 10 objets par défaut. Pour paginer plus, configurez les permissions du module selon vos besoins.

Tri

Passez sortKey et sortOrder dans userQuery :

sortKey	Ce que cela fait	Exemple d'utilisation
price	Trier par prix	Afficher les moins chers d'abord
date	Trier par date de création	Afficher les produits les plus récents
title	Trier par ordre alphabétique	Liste de produits A-Z
position	Ordre personnalisé (par défaut)	Ordre choisi par l'administrateur
id	Trier par ID	Tri technique

Ordre de tri : ASC (bas→haut) ou DESC (haut→bas, par défaut).

Filtrage

Le filtrage se fait via le body de la requête (un tableau de IFilterParams), pas userQuery. Chaque condition combine un attributeMarker, un conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs), et un conditionValue. Combinez plusieurs conditions dans le tableau pour filtrer par plusieurs critères à la fois. La référence complète des conditions se trouve dans Paramètres ci-dessous.

---

📊 Tableau de référence rapide - Méthodes courantes

Méthode	Description	Cas d'utilisation
getProducts()	Obtenir tous les produits avec filtrage/tris	Page principale du catalogue
getProductById()	Obtenir un produit unique par ID	Page de détail du produit
getProductsByPageId()	Obtenir des produits d'une catégorie par ID de page	Page de catégorie
getProductsByPageUrl()	Obtenir des produits d'une catégorie par URL de page	Page de catégorie par URL
getRelatedProductsById()	Obtenir des produits similaires	Section "Vous pourriez aussi aimer"
searchProduct()	Rechercher des produits par requête	Fonctionnalité de recherche
getProductsCount()	Obtenir le nombre total de produits	Informations de pagination
getProductsCountByPageId()	Obtenir le nombre de produits par ID de catégorie	Pagination de catégorie
getProductsCountByPageUrl()	Obtenir le nombre de produits par URL de catégorie	Pagination de catégorie
getProductBlockById()	Obtenir un bloc de produit par ID	Blocs de contenu de produit
getProductsEmptyPage()	Obtenir la structure de page vide des produits	Gestion de l'état vide
getProductsPriceByPageUrl()	Obtenir les prix des produits par URL de page	Filtrage des prix
getProductsByIds()	Obtenir des produits par une liste d'IDs	Panier, liste de souhaits, comparaison
getProductsByVectorSearch()	Recherche sémantique (vectorielle) pour les produits	Recherche alimentée par l'IA

Paramètres

Ce module accepte un ensemble de paramètres utilisateur appelés userQuery. Si un paramètre n'est pas passé, son défaut est appliqué. Certaines méthodes acceptent également un body pour le filtrage — passez un tableau vide (ou rien) lorsque vous n'avez pas besoin de filtres.

const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
    signPrice: 'orders',
}

Remarque : la structure de userQuery dépend de la méthode. Les champs ci-dessus sont la base commune (IProductsQueryBase), utilisée par getProducts, getProductsByPageId, getProductsByPageUrl et getProductsEmptyPage. D'autres méthodes diffèrent : getRelatedProductsById accepte également statusMarker et templateMarker ; getProductsPriceByPageUrl accepte également statusMarker (pas de sortKey) ; getProductsByIds accepte uniquement signPrice. Le filtrage (attributeMarker / conditionMarker / conditionValue) se fait via le body de la requête, pas userQuery — voir ci-dessous.

Schéma

offset : nombre
Paramètre de pagination. Par défaut 0
exemple : 0

limit : nombre
paramètre de pagination. Par défaut 30
exemple : 30

sortKey : chaîne
Champ pour le tri (par défaut non défini - tri par position, valeurs possibles : id, title, date, price, position)
Valeurs disponibles : id, position, title, date, price

sortOrder : chaîne
ordre de tri DESC | ASC (par défaut DESC)
exemple : "DESC"

signPrice : chaîne
Marqueur de stockage de commande pour la fixation des prix. Si le paramètre est défini, le prix est fixé pour un certain temps (voir la section Fixation du prix ci-dessous).
exemple : "orders"

Champs spécifiques à la méthode : statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) et templateMarker (getRelatedProductsById) — string | null, par défaut null.

Utilisez des conditions pour trouver des données spécifiques sur les produits :

attributeMarker : L'identifiant textuel de l'attribut indexé par lequel les valeurs sont filtrées. conditionMarker : Le type de condition à appliquer à la valeur de l'attribut.

Marqueur	Signification	Exemple
eq	Égal	statusId = 1 (actif uniquement)
neq	Pas égal	category ≠ "archivé"
in	Contient (un des)	category in ["électronique", "livres"]
nin	Ne contient pas	brand not in ["fausse_marque"]
mth	Supérieur à	price > 100
lth	Inférieur à	stock < 10
exs	Existe (a une valeur)	A une description
nexs	N'existe pas	Pas d'image

conditionValue : La valeur à comparer.

---

Fixation du prix (signPrice)

Lorsque vous récupérez des produits, vous pouvez passer un paramètre signPrice optionnel à l'intérieur de userQuery (c'est également un argument sur les méthodes de recommandation du module Blocks). Il accepte le marqueur d'un stockage de commande et demande au serveur de verrouiller le prix retourné pour une durée limitée.

signPrice — type string

Marqueur de stockage de commande pour la fixation des prix. Si le paramètre est défini, le prix est fixé pour un certain temps.

Pourquoi l'utiliser. Les prix peuvent changer pendant qu'un client fait ses achats — une remise commence, ou un administrateur modifie le prix. signPrice garantit que le prix affiché dans le catalogue ou le panier est exactement le prix facturé lors du paiement, de sorte qu'il ne peut pas varier entre la navigation et la commande.

Comment cela fonctionne :

1. Récupérez des produits avec signPrice défini sur votre marqueur de stockage de commande (par exemple "orders").
2. Chaque produit retourné porte maintenant un champ signedPrice — un jeton signé qui encode le prix verrouillé.
3. Envoyez ce jeton signedPrice lorsque vous créez la commande, afin que le serveur honore le prix fixe.

const { items } = await Products.getProducts([], "fr_FR", {
  signPrice: "orders"
});
const signedPrice = items[0].signedPrice;

➡️ Le jeton retourné est consommé par createOrder(). Voir où le prendre et comment le passer dans la section Prix de produit fixe (signedPrice) du module Orders.

---

❓ Questions fréquentes (FAQ)

Puis-je filtrer par plusieurs critères à la fois ?

Oui — passez plusieurs conditions dans le tableau body ; elles sont combinées ensemble :

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

---

Comment gérer les variantes de produits (tailles, couleurs) ?

Les variantes sont stockées dans les attributeValues du produit — lisez-les à partir de l'objet produit récupéré. La structure est celle de l'ensemble d'attributs que vous avez configuré pour le catalogue.

---

Comment implémenter un bouton "Charger plus" ?

Augmentez offset de limit à chaque clic et ajoutez les nouveaux items à votre liste (utilisez total pour savoir quand vous arrêter).

---

Puis-je afficher des produits de plusieurs catégories ?

Oui — filtrez avec l'attribut category et le marqueur de condition in, en passant la liste des valeurs de catégorie.

---

Comment implémenter une section "Nouveautés" ?

Triez par date de création : userQuery: { sortKey: "date", sortOrder: "DESC" }.

---

🎓 Meilleures pratiques

• Paginer toujours (limit + offset) — ne récupérez jamais tout le catalogue d'un coup.
• Mettre en cache les listes de produits pour les catégories fréquemment consultées afin de réduire les appels API.
• Utilisez signPrice lorsque les prix sont intégrés dans un panier/checkout afin que le prix ne puisse pas varier.
• Gérez les résultats vides (total === 0) et les champs manquants (price, images) de manière élégante.

---

🔗 Documentation connexe

• Panneau d'administration OneEntry - Catalogue - Documentation officielle du panneau d'administration
• Module Pages - Créer des catégories de catalogue (pages de type Catalogue)
• Module AttributesSets - Champs et attributs de produit personnalisés
• Module Templates - Modèles d'affichage des produits
• Module Blocks - Blocs de contenu de produit réutilisables
• Module Orders - Gérer les commandes de produits

---