Aller au contenu principal

Orders

Créez et suivez les commandes des clients tout au long du parcours de paiement, de règlement et d'exécution.

Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/category/orders (ouvre dans un nouvel onglet)

Le module Orders transforme un panier en commande, prévisualise les totaux (remises, coupons, bonus), suit le statut de la commande et gère les demandes de remboursement. L'interface du panier est à votre charge.

Les commandes sont rangées dans des stockages de commandes : des conteneurs que vous configurez dans le panneau d'administration et référencez par marqueur. Le paiement passe par la passerelle configurée pour le compte de paiement choisi ; voir le module Payments.

Démarrage rapide​

Initialisez le module depuis defineOneEntry :


const {  } = defineOneEntry(
  , {
    
  }
);

Créez une commande dans un stockage et relisez le résultat (cet exemple utilise un utilisateur connecté) :

// Create an order in the "my_order" storage.
const order = await Orders.createOrder("my_order", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});
if ('statusCode' in order) throw new Error(order.message);

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 285 "inProgress-payment"

Objet commande​

Les méthodes de lecture (getOrderByMarkerAndId(), getOrderById(), getAllOrdersByMarker()) renvoient les commandes sous cette forme (IOrderByMarkerEntity). createOrder() et updateOrderByMarkerAndId() renvoient un IBaseOrdersEntity plus court.

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'John' }
  ],
  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: false,
}

Les champs que vous utiliserez le plus :

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

Stockages et statuts​

Un stockage de commandes regroupe des commandes liées, par exemple les commandes d'un formulaire ou d'un canal de vente précis. Vous désignez un stockage par son marqueur, et une commande qu'il contient par marqueur et id. Les marqueurs sont stables : référencez les stockages et les formulaires par marqueur plutôt que par leur nom affiché.

Chaque stockage définit son propre ensemble de statuts, et l'état actuel d'une commande se trouve dans statusIdentifier. Obtenez les statuts disponibles dans un stockage avec getAllStatusesByStorageMarker(), et changez le statut d'une commande avec updateOrderByMarkerAndId(). Pour réagir aux changements de statut, utilisez le module Events.

Créer une commande​

Vous fournissez les données du formulaire et les lignes de commande ; OneEntry calcule le total. Pour créer une commande, transmettez :

  1. formIdentifier : le formulaire de commande
  2. formData : les champs envoyés par le client
  3. products : un tableau de lignes de commande, chacune avec productId, quantity et un signedPrice facultatif
  4. paymentAccountIdentifier : le mode de paiement du client

Appelez d'abord previewOrder() pour afficher les remises, coupons et bonus dans le récapitulatif de commande. Les méthodes de lecture et de mise à jour nécessitent un utilisateur authentifié (voir AuthProvider). createOrder() fonctionne aussi pour les invités si le groupe d'utilisateurs invité en a la permission. Paginez les listes de commandes avec offset et limit au lieu de charger toutes les commandes d'un coup.

Le module ne stocke pas les données brutes des cartes : le paiement est traité par la passerelle, via la session de paiement ou paymentUrl.

Vous pouvez modifier une commande après sa création avec updateOrderByMarkerAndId() : son statut, ses données de formulaire ou ses produits. Soyez prudent en modifiant les articles ou les totaux une fois le paiement en cours.

Annulations et remboursements​

Pour annuler une commande, mettez à jour son statut avec updateOrderByMarkerAndId(). Les remboursements sont gérés dans ce module : demandez-en un avec createRefundRequest(), listez les demandes de remboursement d'une commande avec getRefunds() et annulez-en une avec cancelRefundRequest().

Méthodes​

MéthodeDescription
createOrder()Crée une nouvelle commande
getAllOrdersByMarker() 🔐Récupérer toutes les commandes d'un stockage (paginées)
getOrdersStorageByMarker() 🔐Récupérer un stockage de commandes par marqueur
getAllOrdersStorage() 🔐Récupérer tous les stockages de commandes
getOrderByMarkerAndId() 🔐Récupérer l'une des commandes de l'utilisateur par marqueur de stockage et id
getOrderById() 🔐Récupère une commande de l'utilisateur par id, sans le marqueur de stockage
updateOrderByMarkerAndId() 🔐Modifier l'une des commandes de l'utilisateur par marqueur de stockage et id
previewOrder()Prévisualise les totaux, remises et coupons d'une commande avant sa création
getAllStatusesByStorageMarker() 🔐Récupérer tous les statuts de commande d'un stockage
getRefunds() 🔐Récupérer toutes les demandes de remboursement d'une commande
createRefundRequest() 🔐Créer une demande de remboursement pour une commande
cancelRefundRequest() 🔐Annuler une demande de remboursement d'une commande
getOrdersByVectorSearch() 🔐Recherche sémantique (vectorielle) dans les commandes de l'utilisateur authentifié

🔐 = Nécessite une autorisation

Prix de produit fixé (signedPrice)​

signedPrice est un jeton signé qui verrouille le prix d'un produit. Lorsqu'une ligne de commande le contient, le serveur facture ce prix fixé au lieu de rechercher à nouveau le prix, si bien que le client paie le montant qu'il a vu dans le catalogue ou le panier. Utilisez-le chaque fois que des produits alimentent le paiement, pour que le prix ne puisse pas varier entre la navigation et la commande.

Où l'obtenir​

Vous ne générez pas signedPrice vous-même. Il est fourni dans les données du produit, mais seulement si vous avez demandé les produits avec le paramètre signPrice défini sur le marqueur de votre stockage de commandes :

  • Module Products : transmettez signPrice dans userQuery (getProducts, getProductsByPageUrl, …).
  • Module Blocks : transmettez signPrice en argument des méthodes de recommandation (getCartSimilar, getRecentlyViewed, …).

Chaque produit renvoyé contient alors une chaîne signedPrice. Voir Fixer le prix (signPrice) pour plus de détails.

Comment l'utiliser​

Renvoyez le jeton dans chaque produit du body de createOrder(), et la commande conserve le prix fixé :


const products = await Products.([], "en_US", {
  signPrice: "my_order"
});
if ('statusCode' in products) throw new Error(products.message);
const { items } = products;

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

const order = await Orders.createOrder("my_order", body);

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

Voir aussi​

  • Products : produits disponibles à l'achat
  • Payments : sessions de paiement des commandes
  • Users : les clients qui passent les commandes
  • AuthProvider : autorisation pour les méthodes de commande
  • Events : notifications de statut de commande