Saltar al contenido principal

Introducción

Crea y rastrea pedidos de clientes a lo largo de todo el ciclo de compra, pago y cumplimiento.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/orders

🎯 ¿Qué hace este módulo?​

El módulo de Orders te permite crear, gestionar y rastrear pedidos de clientes — desde la compra hasta el pago y el cumplimiento. Tú construyes la interfaz del carrito; este módulo convierte el carrito en un pedido, previsualiza totales (descuentos, cupones, bonificaciones), rastrea el estado y maneja solicitudes de reembolso.

Los pedidos residen dentro de almacenamientos de pedidos (contenedores que configuras en el panel de administración) y son referenciados por un marcador de almacenamiento. El pago se delega a la pasarela configurada para la cuenta de pago elegida — consulta el módulo de Payments.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


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

Crea un pedido en un almacenamiento y lee el resultado (se requiere autenticación):

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

✨ Conceptos Clave​

¿Qué es un Pedido?​

Un Pedido es una transacción de compra de un cliente. Cada objeto de pedido lleva:

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

Estructura del Pedido​

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

Almacenamiento de Pedidos vs. Pedidos Individuales​

Un almacenamiento de pedidos es un contenedor que agrupa pedidos relacionados (por ejemplo, pedidos de un formulario específico o canal de ventas). Los pedidos individuales son las transacciones reales dentro de un almacenamiento. Te diriges a un almacenamiento por su marcador y a un pedido dentro de él por marcador + id.

Estados de los Pedidos​

Cada almacenamiento define su propio conjunto de estados; el estado actual de un pedido está en statusIdentifier. Obtén los estados disponibles para un almacenamiento con getAllStatusesByStorageMarker(), y actualiza el estado de un pedido con updateOrderByMarkerAndId().

📋 Lo Que Necesitas Saber​

Los Pedidos se Construyen a Partir de Datos del Carrito​

Proporcionas los datos del formulario del pedido y los artículos de línea; OneEntry calcula los totales. Para crear un pedido pasas:

  1. formIdentifier — el formulario del pedido
  2. formData — los campos del formulario enviados por el cliente
  3. products — artículos de línea (productId, quantity, signedPrice opcional)
  4. paymentAccountIdentifier — cómo pagará el cliente

Lo Que Hace y No Hace el Módulo​

  • ✅ Crea pedidos a partir de datos del carrito, previsualiza totales, actualiza estados, gestiona solicitudes de reembolso
  • ✅ Delegar el pago a la pasarela a través de la sesión de pago / paymentUrl
  • ❌ No proporciona la interfaz del carrito de compras — tú construyes eso
  • ❌ No almacena datos de tarjetas en bruto — el pago es manejado por la pasarela

Reembolsos​

El manejo de reembolsos vive en el módulo de Orders: solicita un reembolso con createRefundRequest(), lista las solicitudes de reembolso de un pedido con getRefunds(), y cancela una con cancelRefundRequest().

📊 Tabla de Referencia Rápida​

MétodoDescripción
createOrder() 🔐Crear un nuevo pedido
getAllOrdersByMarker() 🔐Obtener todos los pedidos para un almacenamiento (paginado)
getOrdersStorageByMarker() 🔐Obtener un objeto de almacenamiento de pedidos por marcador.
getAllOrdersStorage() 🔐Obtener todos los objetos de almacenamiento de pedidos.
getOrderByMarkerAndId() 🔐Obtener un pedido por marcador e id del objeto de almacenamiento de pedidos creado por el usuario.
updateOrderByMarkerAndId() 🔐Actualizar un pedido por marcador e id del objeto de almacenamiento de pedidos creado por el usuario.
previewOrder() 🔐Previsualizar totales del pedido, descuentos y cupones antes de crearlo.
getAllStatusesByStorageMarker()Obtener todos los estados de pedidos para un marcador de almacenamiento.
getRefunds()Obtener todas las solicitudes de reembolso para un pedido.
createRefundRequest()Crear una solicitud de reembolso para un pedido.
cancelRefundRequest()Cancelar una solicitud de reembolso para un pedido.

🔐 = Requiere autorización

Precio fijo del producto (signedPrice)​

signedPrice es un token firmado que bloquea el precio de un producto. Cuando está presente en una línea de pedido, el servidor cobra ese precio fijo exacto en lugar de buscar el precio nuevamente — así que el monto que el cliente vio en el catálogo o carrito es el monto que paga.

signedPrice — tipo string

El precio firmado del producto se obtiene junto con los datos del producto cuando signPrice está configurado.

Dónde Obtenerlo​

No generas signedPrice tú mismo — llega dentro de los datos del producto, pero solo cuando solicitaste los productos con el parámetro signPrice configurado a tu marcador de almacenamiento de pedidos:

  • Módulo de Products — pasa signPrice en userQuery (getProducts, getProductsByPageUrl, …).
  • Módulo de Blocks — pasa signPrice como argumento del método de recomendación (getCartSimilar, getRecentlyViewed, …).

Cada producto devuelto contiene entonces una cadena signedPrice. Lee más en la sección Fijando el precio (signPrice) del Módulo de Products.

Cómo Usarlo​

Pasa el token de vuelta en cada producto del cuerpo de createOrder(). El pedido luego mantiene el precio fijo:


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "my-order"
});

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

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

Si omites signedPrice, el pedido se crea con el precio actual del producto en el momento de la compra.

❓ Preguntas Comunes (FAQ)​

¿Cómo creo un pedido con múltiples productos?​

Pasa un array de objetos de producto en el campo products del cuerpo del pedido. Cada elemento necesita productId y quantity (y opcionalmente signedPrice). La suma total se calcula automáticamente.

¿Puedo actualizar un pedido después de haber sido creado?​

Sí — usa updateOrderByMarkerAndId() para modificar detalles del pedido como estado, datos del formulario o productos. Ten cuidado al cambiar artículos o totales una vez que el pago está en progreso.

¿Cómo rastreo los cambios en el estado del pedido?​

Lee el campo statusIdentifier para el estado actual, y obtén los estados disponibles del almacenamiento con getAllStatusesByStorageMarker(). También puedes usar el módulo de Events para reaccionar a los cambios.

¿Cuál es la diferencia entre el almacenamiento de pedidos y los pedidos individuales?​

El almacenamiento de pedidos es un contenedor que agrupa pedidos relacionados (por ejemplo, pedidos de un formulario específico o canal de ventas). Los pedidos individuales son las transacciones dentro de ese almacenamiento. Usa marcadores para identificar y organizar los almacenamientos.

¿Cómo manejo las cancelaciones y reembolsos de pedidos?​

Actualiza el estado del pedido con updateOrderByMarkerAndId(). Para reembolsos, usa los métodos de reembolso de Orders: createRefundRequest() para solicitar uno, getRefunds() para listar las solicitudes de un pedido, y cancelRefundRequest() para cancelar una.

🎓 Mejores Prácticas​

  • Previsualiza antes de crear — llama a previewOrder() para mostrar descuentos, cupones y bonificaciones en el resumen de compra.
  • Usa signedPrice cuando los productos se integren en la compra para que el precio no varíe entre la navegación y el pedido.
  • Autentica primero — los métodos de creación/lectura/actualización de pedidos requieren un usuario autorizado (consulta AuthProvider).
  • Paginación de listas de pedidos (offset + limit) — no cargues todos los pedidos a la vez.
  • Referencia almacenamientos y formularios por marcador, no por nombre de visualización — los marcadores son estables.

🔗 Documentación Relacionada​