Orders

Crea y sigue los pedidos de los clientes a lo largo de todo el ciclo de checkout, pago y cumplimiento.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/orders (abre en una nueva pestaña)

---

El módulo Orders convierte un carrito en un pedido, calcula una vista previa de los totales (descuentos, cupones, bonificaciones), sigue el estado del pedido y gestiona las solicitudes de reembolso. La interfaz del carrito la construyes tú.

Los pedidos se guardan en almacenamientos de pedidos: contenedores que configuras en el panel de administración y a los que haces referencia por marcador. El pago se realiza a través de la pasarela configurada para la cuenta de pago elegida; consulta el módulo Payments.

Inicio rápido

Inicializa el módulo desde defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Crea un pedido en un almacén y lee el resultado (este ejemplo usa un usuario con sesión iniciada):

// 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"

Objeto de pedido

Los métodos de lectura (getOrderByMarkerAndId(), getOrderById(), getAllOrdersByMarker()) devuelven los pedidos con esta forma (IOrderByMarkerEntity). createOrder() y updateOrderByMarkerAndId() devuelven un IBaseOrdersEntity más corto.

{
  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,
}

Los campos que más usarás:

• id: identificador del pedido
• storageId: el almacenamiento de pedidos al que pertenece el pedido
• formIdentifier / formData: el formulario del pedido y los datos que envió el cliente
• products: líneas del pedido (id, title, quantity, price, …)
• totalSum / currency: total del pedido y moneda
• paymentAccountIdentifier: la cuenta de pago elegida
• paymentUrl: enlace de checkout de la pasarela, o null
• statusIdentifier / isCompleted: estado actual
• createdDate: marca de tiempo

Almacenamientos y estados

Un almacenamiento de pedidos agrupa pedidos relacionados, por ejemplo los pedidos de un formulario o de un canal de venta concreto. Te diriges a un almacenamiento por su marcador y a un pedido dentro de él por marcador e id. Los marcadores son estables, así que haz referencia a los almacenamientos y formularios por marcador y no por el nombre visible.

Cada almacenamiento define su propio conjunto de estados, y el estado actual de un pedido está en statusIdentifier. Obtén los estados disponibles en un almacenamiento con getAllStatusesByStorageMarker() y cambia el estado de un pedido con updateOrderByMarkerAndId(). Para reaccionar a los cambios de estado, usa el módulo Events.

Crear un pedido

Tú aportas los datos del formulario y las líneas del pedido; OneEntry calcula el total. Para crear un pedido, pasa:

1. formIdentifier: el formulario del pedido
2. formData: los campos que envió el cliente
3. products: un array de líneas, cada una con productId, quantity y un signedPrice opcional
4. paymentAccountIdentifier: cómo pagará el cliente

Llama primero a previewOrder() para mostrar descuentos, cupones y bonos en el resumen del pago. Los métodos de lectura y actualización requieren un usuario autenticado (consulta AuthProvider). createOrder() también funciona para invitados si el grupo de usuarios de invitados tiene permiso. Pagina las listas de pedidos con offset y limit en lugar de cargar todos los pedidos a la vez.

El módulo no almacena datos de tarjeta sin procesar: el pago lo gestiona la pasarela, mediante la sesión de pago o paymentUrl.

Puedes modificar un pedido después de crearlo con updateOrderByMarkerAndId(): su estado, los datos del formulario o los productos. Ten cuidado al cambiar artículos o totales cuando el pago ya está en curso.

Cancelaciones y reembolsos

Para cancelar un pedido, actualiza su estado con updateOrderByMarkerAndId(). Los reembolsos se gestionan en este módulo: solicita uno con createRefundRequest(), lista las solicitudes de reembolso de un pedido con getRefunds() y cancela una con cancelRefundRequest().

---

Métodos

Método	Descripción
createOrder()	Crea un pedido nuevo
getAllOrdersByMarker() 🔐	Obtiene todos los pedidos de un almacenamiento (con paginación)
getOrdersStorageByMarker() 🔐	Obtiene un almacenamiento de pedidos por marcador
getAllOrdersStorage() 🔐	Obtiene todos los almacenamientos de pedidos
getOrderByMarkerAndId() 🔐	Obtiene uno de los pedidos del usuario por marcador de almacenamiento e id
getOrderById() 🔐	Obtiene uno de los pedidos del usuario por id, sin el marcador de almacenamiento
updateOrderByMarkerAndId() 🔐	Actualiza uno de los pedidos del usuario por marcador de almacenamiento e id
previewOrder()	Previsualiza los totales, descuentos y cupones del pedido antes de crearlo
getAllStatusesByStorageMarker() 🔐	Obtiene todos los estados de pedido de un almacenamiento
getRefunds() 🔐	Obtiene todas las solicitudes de reembolso de un pedido
createRefundRequest() 🔐	Crea una solicitud de reembolso para un pedido
cancelRefundRequest() 🔐	Cancela una solicitud de reembolso de un pedido
getOrdersByVectorSearch() 🔐	Búsqueda semántica (vectorial) en los pedidos del usuario autenticado

🔐 = Requiere autorización

---

Precio fijo del producto (signedPrice)

signedPrice es un token firmado que bloquea el precio de un producto. Cuando una línea del pedido lo lleva, el servidor cobra ese precio fijo en lugar de volver a consultar el precio, de modo que el cliente paga el importe que vio en el catálogo o en el carrito. Úsalo siempre que los productos pasen al checkout, para que el precio no cambie entre la navegación y el pedido.

De dónde se obtiene

signedPrice no lo generas tú. Llega dentro de los datos del producto, pero solo si solicitaste los productos con el parámetro signPrice establecido en el marcador de tu almacenamiento de pedidos:

• Módulo Products: pasa signPrice en userQuery (getProducts, getProductsByPageUrl, …).
• Módulo Blocks: pasa signPrice como argumento de los métodos de recomendaciones (getCartSimilar, getRecentlyViewed, …).

Entonces cada producto devuelto contiene una cadena signedPrice. Consulta Fijar el precio (signPrice) para más detalles.

Cómo usarlo

Devuelve el token en cada producto del body de createOrder() y el pedido conservará el precio fijo:

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);

Sin signedPrice, el pedido se crea con el precio actual del producto en el momento del checkout.

---

Relacionado

• Products: productos disponibles para comprar
• Payments: sesiones de pago de los pedidos
• Users: los clientes que hacen pedidos
• AuthProvider: autorización para los métodos de pedidos
• Events: notificaciones de estado de los pedidos