Aller au contenu principal

Introduction

Créez et suivez les commandes des clients tout au long du processus de paiement, de la transaction à l'exécution.

Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/category/orders

🎯 Que fait ce module ?​

Le module Orders vous permet de créer, gérer et suivre les commandes des clients — du paiement à l'exécution. Vous construisez l'interface utilisateur du panier ; ce module transforme le panier en commande, prévisualise les totaux (remises, coupons, bonus), suit l'état et gère les demandes de remboursement.

Les commandes se trouvent dans des stockages de commandes (conteneurs que vous configurez dans le panneau d'administration) et sont référencées par un marqueur de stockage. Le paiement est délégué à la passerelle configurée pour le compte de paiement choisi — voir le module Payments.

🚀 Démarrage rapide​

Initialisez le module à partir de defineOneEntry :


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

Créez une commande dans un stockage et lisez le résultat (auth requis) :

// Create an order in the "order_storage_1" storage.
const order = await Orders.createOrder("order_storage_1", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 "300.00" "inProgress"

✨ Concepts clés​

Qu'est-ce qu'une commande ?​

Une commande est une transaction d'achat d'un client. Chaque objet commande contient :

  • id — identifiant de la commande
  • storageId — le stockage de commande auquel elle appartient
  • formIdentifier / formData — le formulaire de commande et les données soumises par le client
  • products — articles de ligne (productId, quantity, price, …)
  • totalSum / currency — total de la commande et devise
  • paymentAccountIdentifier — le compte de paiement choisi
  • paymentUrl — lien de paiement de la passerelle (ou null)
  • statusIdentifier / isCompleted — état actuel
  • createdDate — horodatage

Structure de la commande​

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'Ivan' }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  paymentUrl: null,
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
      isGift: false,
    },
  ],
  isCompleted: true,
}

Stockage de commande vs. commandes individuelles​

Un stockage de commande est un conteneur qui regroupe des commandes liées (par exemple, des commandes d'un formulaire ou d'un canal de vente spécifique). Les commandes individuelles sont les transactions réelles à l'intérieur d'un stockage. Vous adressez un stockage par son marqueur et une commande à l'intérieur par marqueur + id.

Statuts des commandes​

Chaque stockage définit son propre ensemble de statuts ; l'état actuel d'une commande se trouve dans statusIdentifier. Récupérez les statuts disponibles pour un stockage avec getAllStatusesByStorageMarker(), et mettez à jour le statut d'une commande avec updateOrderByMarkerAndId().

📋 Ce que vous devez savoir​

Les commandes sont construites à partir des données du panier​

Vous fournissez les données du formulaire de commande et les articles de ligne ; OneEntry calcule les totaux. Pour créer une commande, vous passez :

  1. formIdentifier — le formulaire de commande
  2. formData — les champs de formulaire soumis par le client
  3. products — articles de ligne (productId, quantity, signedPrice optionnel)
  4. paymentAccountIdentifier — comment le client paiera

Ce que le module fait et ne fait pas​

  • ✅ Créer des commandes à partir des données du panier, prévisualiser les totaux, mettre à jour le statut, gérer les demandes de remboursement
  • ✅ Déléguer le paiement à la passerelle via la session de paiement / paymentUrl
  • ❌ Ne fournit pas l'interface utilisateur du panier — vous la construisez
  • ❌ Ne stocke pas les données de carte brutes — le paiement est géré par la passerelle

Remboursements​

La gestion des remboursements se fait dans le module Orders : demandez un remboursement avec createRefundRequest(), listez les demandes de remboursement d'une commande avec getRefunds(), et annulez-en une avec cancelRefundRequest().

📊 Tableau de référence rapide​

MéthodeDescription
createOrder() 🔐Créer une nouvelle commande
getAllOrdersByMarker() 🔐Obtenir toutes les commandes pour un stockage (paginé)
getOrdersStorageByMarker() 🔐Obtenir un objet de stockage de commande par marqueur.
getAllOrdersStorage() 🔐Obtenir tous les objets de stockage de commande.
getOrderByMarkerAndId() 🔐Obtenir une commande par marqueur et id à partir de l'objet de stockage de commande créé par l'utilisateur.
updateOrderByMarkerAndId() 🔐Mettre à jour une commande par marqueur et id à partir de l'objet de stockage de commande créé par l'utilisateur.
previewOrder() 🔐Prévisualiser les totaux de la commande, les remises et les coupons avant de la créer.
getAllStatusesByStorageMarker()Obtenir tous les statuts de commande pour un marqueur de stockage.
getRefunds()Obtenir toutes les demandes de remboursement pour une commande.
createRefundRequest()Créer une demande de remboursement pour une commande.
cancelRefundRequest()Annuler une demande de remboursement pour une commande.

🔐 = Nécessite une autorisation

Prix fixe du produit (signedPrice)​

signedPrice est un jeton signé qui verrouille le prix d'un produit. Lorsqu'il est présent sur une ligne de commande, le serveur facture ce prix fixe exact au lieu de rechercher à nouveau le prix — donc le montant que le client a vu dans le catalogue ou le panier est le montant qu'il paie.

signedPrice — type string

Le prix signé du produit est obtenu avec les données du produit lorsque signPrice est défini.

Où l'obtenir​

Vous ne générez pas signedPrice vous-même — il arrive dans les données du produit, mais seulement lorsque vous avez demandé les produits avec le paramètre signPrice défini sur le marqueur de votre stockage de commande :

  • Products module — passez signPrice dans userQuery (getProducts, getProductsByPageUrl, …).
  • Blocks module — passez signPrice comme argument de méthode de recommandation (getCartSimilar, getRecentlyViewed, …).

Chaque produit retourné contient alors une chaîne signedPrice. Lisez-en plus dans la section Fixer le prix (signPrice) du module Products.

Comment l'utiliser​

Passez le jeton dans chaque produit du corps de createOrder(). La commande conserve alors le prix fixe :


const { items } = await Products.getProducts([], "fr_FR", {
  signPrice: "ma-commande"
});

const body = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].signedPrice
    }
  ]
};

const order = await Orders.createOrder("ma-commande", body);

Si vous omettez signedPrice, la commande est créée avec le prix actuel du produit au moment du paiement.

❓ Questions fréquentes (FAQ)​

Comment créer une commande avec plusieurs produits ?​

Passez un tableau d'objets produit dans le champ products du corps de la commande. Chaque élément a besoin de productId et quantity (et optionnellement signedPrice). Le total est calculé automatiquement.

Puis-je mettre à jour une commande après sa création ?​

Oui — utilisez updateOrderByMarkerAndId() pour modifier les détails de la commande tels que le statut, les données du formulaire ou les produits. Soyez prudent lors de la modification des articles ou des totaux une fois le paiement en cours.

Comment suivre les changements de statut d'une commande ?​

Lisez le champ statusIdentifier pour l'état actuel, et récupérez les statuts disponibles du stockage avec getAllStatusesByStorageMarker(). Vous pouvez également utiliser le module Events pour réagir aux changements.

Quelle est la différence entre le stockage de commande et les commandes individuelles ?​

Le stockage de commande est un conteneur qui regroupe des commandes liées (par exemple, des commandes d'un formulaire ou d'un canal de vente spécifique). Les commandes individuelles sont les transactions à l'intérieur de ce stockage. Utilisez des marqueurs pour identifier et organiser les stockages.

Comment gérer les annulations et les remboursements de commandes ?​

Mettez à jour le statut de la commande avec updateOrderByMarkerAndId(). Pour les remboursements, utilisez les méthodes de remboursement des Orders : createRefundRequest() pour en demander un, getRefunds() pour lister les demandes d'une commande, et cancelRefundRequest() pour annuler une.

🎓 Meilleures pratiques​

  • Prévisualisez avant de créer — appelez previewOrder() pour afficher les remises, les coupons et les bonus dans le résumé de paiement.
  • Utilisez signedPrice lorsque les produits alimentent le paiement afin que le prix ne puisse pas varier entre la navigation et la commande.
  • Authentifiez-vous d'abord — les méthodes de création/lecture/mise à jour de commande nécessitent un utilisateur autorisé (voir AuthProvider).
  • Paginer les listes de commandes (offset + limit) — ne chargez pas toutes les commandes en une seule fois.
  • Référencez les stockages et les formulaires par marqueur, pas par nom d'affichage — les marqueurs sont stables.

🔗 Documentation connexe​