Orders

Crie e acompanhe os pedidos dos clientes por todo o ciclo de checkout, pagamento e atendimento.

Mais informações sobre a interface do módulo https://doc.oneentry.cloud/docs/category/orders (abre em uma nova aba)

---

O módulo Orders transforma um carrinho em pedido, pré-visualiza totais (descontos, cupons, bônus), acompanha o status do pedido e processa solicitações de reembolso. A interface do carrinho fica por sua conta.

Os pedidos ficam em armazenamentos de pedidos: contêineres que você configura no painel de administração e referencia pelo marcador. O pagamento passa pelo gateway configurado para a conta de pagamento escolhida; veja o módulo Payments.

Início rápido

Inicialize o módulo a partir de defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Crie um pedido em um armazenamento e leia o resultado (este exemplo usa um usuário autenticado):

// 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 do pedido

Os métodos de leitura (getOrderByMarkerAndId(), getOrderById(), getAllOrdersByMarker()) retornam pedidos neste formato (IOrderByMarkerEntity). createOrder() e updateOrderByMarkerAndId() retornam um IBaseOrdersEntity mais curto.

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

Os campos que você mais vai usar:

• id: identificador do pedido
• storageId: o armazenamento de pedidos ao qual o pedido pertence
• formIdentifier / formData: o formulário do pedido e os dados enviados pelo cliente
• products: itens do pedido (id, title, quantity, price, …)
• totalSum / currency: total do pedido e moeda
• paymentAccountIdentifier: a conta de pagamento escolhida
• paymentUrl: link de checkout do gateway, ou null
• statusIdentifier / isCompleted: estado atual
• createdDate: data e hora

Armazenamentos e status

Um armazenamento de pedidos agrupa pedidos relacionados, por exemplo, pedidos de um formulário ou canal de vendas específico. Você acessa um armazenamento pelo marcador e um pedido dentro dele pelo marcador e id. Marcadores são estáveis, então referencie armazenamentos e formulários pelo marcador, e não pelo nome de exibição.

Cada armazenamento define seu próprio conjunto de status, e o estado atual de um pedido fica em statusIdentifier. Obtenha os status disponíveis em um armazenamento com getAllStatusesByStorageMarker() e altere o status de um pedido com updateOrderByMarkerAndId(). Para reagir a mudanças de status, use o módulo Events.

Criação de um pedido

Você fornece os dados do formulário e os itens do pedido; o OneEntry calcula o total. Para criar um pedido, passe:

1. formIdentifier: o formulário do pedido
2. formData: os campos enviados pelo cliente
3. products: um array de itens do pedido, cada um com productId, quantity e um signedPrice opcional
4. paymentAccountIdentifier: como o cliente vai pagar

Chame previewOrder() primeiro para mostrar descontos, cupons e bônus no resumo do checkout. Os métodos de leitura e atualização exigem um usuário autenticado (veja AuthProvider). createOrder() também funciona para convidados se o grupo de usuários de convidados tiver permissão. Pagine as listas de pedidos com offset e limit em vez de carregar todos os pedidos de uma vez.

O módulo não armazena dados brutos de cartão: o pagamento é processado pelo gateway, por meio da sessão de pagamento ou do paymentUrl.

Você pode alterar um pedido depois de criado com updateOrderByMarkerAndId(): seu status, os dados do formulário ou os produtos. Tenha cuidado ao alterar itens ou totais depois que o pagamento estiver em andamento.

Cancelamentos e reembolsos

Para cancelar um pedido, atualize seu status com updateOrderByMarkerAndId(). Os reembolsos são tratados neste módulo: solicite um com createRefundRequest(), liste as solicitações de reembolso de um pedido com getRefunds() e cancele uma com cancelRefundRequest().

---

Métodos

Método	Descrição
createOrder()	Criar um novo pedido
getAllOrdersByMarker() 🔐	Obter todos os pedidos de um armazenamento (paginado)
getOrdersStorageByMarker() 🔐	Obter um armazenamento de pedidos pelo marcador
getAllOrdersStorage() 🔐	Obter todos os armazenamentos de pedidos
getOrderByMarkerAndId() 🔐	Obter um dos pedidos do usuário pelo marcador do armazenamento e pelo id
getOrderById() 🔐	Obter um dos pedidos do usuário pelo id, sem o marcador do armazenamento
updateOrderByMarkerAndId() 🔐	Atualizar um dos pedidos do usuário pelo marcador do armazenamento e pelo id
previewOrder()	Pré-visualizar os totais, descontos e cupons do pedido antes de criá-lo
getAllStatusesByStorageMarker() 🔐	Obter todos os status de pedido de um armazenamento
getRefunds() 🔐	Obter todas as solicitações de reembolso de um pedido
createRefundRequest() 🔐	Criar uma solicitação de reembolso para um pedido
cancelRefundRequest() 🔐	Cancelar uma solicitação de reembolso de um pedido
getOrdersByVectorSearch() 🔐	Busca semântica (vetorial) nos pedidos do usuário autenticado

🔐 = Requer autorização

---

Preço fixo do produto (signedPrice)

signedPrice é um token assinado que bloqueia o preço de um produto. Quando uma linha do pedido o traz, o servidor cobra esse preço fixo em vez de consultar o preço novamente, e o cliente paga o valor que viu no catálogo ou no carrinho. Use-o sempre que os produtos alimentarem o checkout, para que o preço não mude entre a navegação e o pedido.

Onde obtê-lo

Você não gera signedPrice por conta própria. Ele vem dentro dos dados do produto, mas apenas se você solicitou os produtos com o parâmetro signPrice definido como o marcador do seu armazenamento de pedidos:

• Módulo Products: passe signPrice em userQuery (getProducts, getProductsByPageUrl, …).
• Módulo Blocks: passe signPrice como argumento dos métodos de recomendação (getCartSimilar, getRecentlyViewed, …).

Cada produto retornado passa a conter uma string signedPrice. Veja Fixação de preço (signPrice) para mais detalhes.

Como usar

Envie o token de volta em cada produto do corpo de createOrder(), e o pedido mantém o preço fixado:

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

Sem signedPrice, o pedido é criado com o preço atual do produto no momento do checkout.

---

Relacionado

• Products: produtos disponíveis para compra
• Payments: sessões de pagamento para pedidos
• Users: os clientes que fazem pedidos
• AuthProvider: autorização para os métodos de pedidos
• Events: notificações de status de pedidos