Aller au contenu principal

Introduction

Récupérez les étiquettes de statut des produits ("Nouveau", "En Vente", "Rupture de Stock") pour badge et filtrer les éléments du catalogue.

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

🎯 Que fait ce module ?​

Le module ProductStatuses fournit des conditions de filtrage supplémentaires pour les éléments du catalogue en plus des filtres basés sur les attributs. Les statuts des produits vous permettent de créer des étiquettes personnalisées - comme "Nouvelle Arrivée", "Meilleure Vente", "En Vente", "Rupture de Stock" - pour badge, organiser et filtrer les produits dans votre catalogue e-commerce.

Vous définissez les étiquettes de statut dans le panneau d'administration OneEntry (Catalogue > Statuts des Produits), les assignez aux produits et utilisez ce module pour récupérer les statuts et filtrer les produits par ceux-ci. Le SDK est en lecture seule : vous ne pouvez pas créer de statuts par son intermédiaire.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


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

Récupérez tous les statuts et lisez leurs champs :

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

✨ Concepts clés​

Qu'est-ce qu'un statut de produit ?​

Un Statut de Produit (IProductStatusEntity) est une étiquette/tag personnalisée pour les produits :

  • Nom du Statut (localizeInfos) - Nom d'affichage localisé (par exemple, "Nouvelle Arrivée", "En Vente")
  • Marqueur de Statut (identifier) - Identifiant unique utilisé pour le filtrage
  • Drapeau par défaut (isDefault) - Indique si c'est le statut par défaut
  • Position (position) - Ordre d'affichage

Flux de travail des statuts de produit​

1. Create status in admin panel
   (e.g., "New Arrival")
   ↓
2. Assign status to products
   (Select products in admin)
   ↓
3. Fetch statuses via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Display status badges on products
   (Render badges in product listings)
   ↓
5. Filter products by status marker
   (Products.getProducts([{ statusMarker }], langCode))

📋 Ce que vous devez savoir​

Les statuts sont créés dans le panneau d'administration​

Vous ne pouvez pas créer de statuts via le SDK - ils sont créés dans le panneau d'administration OneEntry (Catalogue > Statuts des Produits). Chaque statut nécessite un Nom (obligatoire) et un Marqueur unique (obligatoire).

Contraintes sur le marqueur :

  • Seulement des lettres latines (a-z, A-Z) et des chiffres (0-9)
  • Tiret bas (_) et tiret (-) autorisés
  • Pas d'espaces ni de caractères spéciaux
  • Doit être unique parmi tous les statuts

Le SDK est destiné à récupérer les statuts et à filtrer les produits, pas à créer des statuts.

Un statut par produit​

Un produit fait référence à au maximum un statut. L'objet produit porte statusIdentifier (le marqueur de statut, ou null) :

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

Filtrage par statut​

Pour filtrer les produits par statut, utilisez la méthode getProducts(body, langCode, userQuery) du module Produits. Passez un champ statusMarker dans le tableau IFilterParams pour récupérer les produits avec un statut spécifique.

Validation d'un marqueur​

validateMarker(marker) retourne true si le marqueur existe et false sinon. Étant donné que le SDK ne peut pas créer de statuts, utilisez-le pour vérifier un marqueur avant de le référencer dans votre code.

Statut vs attributs​

ProductStatuses sont différents des attributs de produit :

FonctionnalitéProductStatusesAttributs
ObjectifÉtiquettes/badges/filtresPropriétés du produit
Exemples"Nouveau", "En Vente", "En Vedette"Couleur, Taille, Matériau
Par produitUn statutPlusieurs attributs
FiltrageSimple (par marqueur de statut)Complexe (plages, valeurs)
Cas d'utilisationÉtiquettes marketingSpécifications du produit

Meilleure pratique : Utilisez des statuts pour des étiquettes marketing, des attributs pour des propriétés de produit.

📊 Tableau de référence rapide​

MéthodeDescriptionCas d'utilisation
getProductStatuses()Obtenir tous les statuts de produitLister tous les statuts disponibles
getProductsByStatusMarker()Obtenir un statut de produit par marqueurRécupérer le statut par identifiant
validateMarker()Vérifier si un marqueur existeValider le marqueur avant utilisation

❓ Questions fréquentes (FAQ)​

Quelle est la différence entre les statuts de produit et les attributs de produit ?​

Les statuts de produit sont des étiquettes marketing (Nouveau, En Vente, En Vedette) pour le filtrage et le badge, tandis que les attributs sont des spécifications de produit (Couleur, Taille, Matériau). Utilisez des statuts pour des étiquettes promotionnelles et des attributs pour des propriétés de produit.

Un produit peut-il avoir plusieurs statuts en même temps ?​

Non. Un produit fait référence à au maximum un statut, exposé comme statusIdentifier (le marqueur de statut) sur l'objet produit.

Comment filtrer les produits par statut ?​

Utilisez la méthode getProducts(body, langCode, userQuery) du module Produits. Passez un champ statusMarker dans le tableau IFilterParams pour récupérer les produits avec un statut spécifique.

Comment vérifier si un marqueur de statut existe ?​

Utilisez validateMarker() - il retourne true si le marqueur existe et false sinon. Le SDK ne peut pas créer de statuts ; les marqueurs sont définis dans le panneau d'administration selon les conventions de nommage (lettres latines, chiffres, tiret bas, tiret uniquement).

Puis-je changer l'ordre des statuts affichés ?​

Oui. Dans le panneau d'administration, vous pouvez faire glisser et déposer les statuts pour les réorganiser. Cela affecte le champ position, qui détermine l'ordre d'affichage dans votre application.

Comment ajouter un style personnalisé aux badges de statut ?​

Récupérez tous les statuts, puis associez les marqueurs de statut à des classes CSS ou des styles en ligne dans votre code frontend. Appliquez ces styles lors du rendu d'un badge de produit en fonction de statusIdentifier du produit.

🎓 Meilleures pratiques​

  • Utilisez des marqueurs descriptifs - new_arrival, pas status1.
  • Validez avant de référencer - appelez validateMarker() avant de coder en dur un marqueur.
  • Rendez le badge de statut - montrez le badge statusIdentifier du produit dans les listes.
  • Mettez en cache les statuts - ils changent rarement, donc mettez-les en cache pour des performances optimales.

🔗 Documentation connexe​