Pular para o conteúdo principal

Introdução

Crie e acompanhe pedidos de clientes ao longo de todo o ciclo de checkout, pagamento e cumprimento.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/orders

🎯 O que este módulo faz?​

O módulo Orders permite que você crie, gerencie e acompanhe pedidos de clientes — desde o checkout até o pagamento e o cumprimento. Você constrói a interface do carrinho; este módulo transforma o carrinho em um pedido, visualiza totais (descontos, cupons, bônus), acompanha o status e lida com solicitações de reembolso.

Os pedidos vivem dentro de armazenamentos de pedidos (contêineres que você configura no painel de administração) e são referenciados por um marcador de armazenamento. O pagamento é delegado ao gateway configurado para a conta de pagamento escolhida — veja o módulo de pagamentos.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


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

Crie um pedido em um armazenamento e leia o resultado (autenticação necessária):

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

✨ Conceitos Chave​

O que é um Pedido?​

Um Pedido é uma transação de compra de um cliente. Cada objeto de pedido contém:

  • id — identificador do pedido
  • storageId — o armazenamento de pedidos ao qual pertence
  • formIdentifier / formData — o formulário do pedido e os dados que o cliente enviou
  • products — itens de linha (productId, 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 — timestamp

Estrutura do 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,
}

Armazenamento de pedidos vs. pedidos individuais​

Um armazenamento de pedidos é um contêiner que agrupa pedidos relacionados (por exemplo, pedidos de um formulário específico ou canal de vendas). Pedidos individuais são as transações reais dentro de um armazenamento. Você se refere a um armazenamento pelo seu marcador e a um pedido dentro dele pelo marcador + id.

Status dos Pedidos​

Cada armazenamento define seu próprio conjunto de status; o estado atual de um pedido está em statusIdentifier. Busque os status disponíveis para um armazenamento com getAllStatusesByStorageMarker(), e atualize o status de um pedido com updateOrderByMarkerAndId().

📋 O que Você Precisa Saber​

Os pedidos são construídos a partir dos dados do carrinho​

Você fornece os dados do formulário do pedido e os itens de linha; o OneEntry calcula os totais. Para criar um pedido, você passa:

  1. formIdentifier — o formulário do pedido
  2. formData — os campos do formulário enviados pelo cliente
  3. products — itens de linha (productId, quantity, signedPrice opcional)
  4. paymentAccountIdentifier — como o cliente pagará

O que o módulo faz e não faz​

  • ✅ Cria pedidos a partir dos dados do carrinho, visualiza totais, atualiza status, gerencia solicitações de reembolso
  • ✅ Delegar pagamento ao gateway via a sessão de pagamento / paymentUrl
  • ❌ Não fornece a interface do carrinho de compras — você constrói isso
  • ❌ Não armazena dados brutos do cartão — o pagamento é tratado pelo gateway

Reembolsos​

O tratamento de reembolsos vive no módulo Orders: solicite um reembolso com createRefundRequest(), liste as solicitações de reembolso de um pedido com getRefunds(), e cancele uma com cancelRefundRequest().

📊 Tabela de Referência Rápida​

MétodoDescrição
createOrder() 🔐Criar novo pedido
getAllOrdersByMarker() 🔐Obter todos os pedidos para um armazenamento (paginado)
getOrdersStorageByMarker() 🔐Obter um objeto de armazenamento de pedidos por marcador.
getAllOrdersStorage() 🔐Obter todos os objetos de armazenamento de pedidos.
getOrderByMarkerAndId() 🔐Obter um pedido por marcador e id do objeto de armazenamento de pedidos criado pelo usuário.
updateOrderByMarkerAndId() 🔐Atualizar um pedido por marcador e id do objeto de armazenamento de pedidos criado pelo usuário.
previewOrder() 🔐Visualizar totais do pedido, descontos e cupons antes de criá-lo.
getAllStatusesByStorageMarker()Obter todos os status de pedidos para um marcador de armazenamento.
getRefunds()Obter todas as solicitações de reembolso para um pedido.
createRefundRequest()Criar uma solicitação de reembolso para um pedido.
cancelRefundRequest()Cancelar uma solicitação de reembolso para um pedido.

🔐 = Requer autorização

Preço fixo do produto (signedPrice)​

signedPrice é um token assinado que fixa o preço de um produto. Quando está presente em uma linha de pedido, o servidor cobra exatamente esse preço fixo em vez de procurar o preço novamente — assim, o valor que o cliente viu no catálogo ou carrinho é o valor que ele paga.

signedPrice — tipo string

O preço assinado do produto é obtido junto com os dados do produto quando signPrice está definido.

Onde obtê-lo​

Você não gera signedPrice você mesmo — ele chega dentro dos dados do produto, mas apenas quando você solicitou os produtos com o parâmetro signPrice definido para o marcador de armazenamento do seu pedido:

  • Módulo de Produtos — passe signPrice em userQuery (getProducts, getProductsByPageUrl, …).
  • Módulo de Blocos — passe signPrice como argumento do método de recomendação (getCartSimilar, getRecentlyViewed, …).

Cada produto retornado contém então uma string signedPrice. Leia mais na seção Fixando o preço (signPrice) do Módulo de Produtos.

Como usá-lo​

Passe o token de volta em cada produto do corpo de createOrder(). O pedido então mantém o preço fixo:


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

Se você omitir signedPrice, o pedido é criado com o preço atual do produto no momento do checkout.

❓ Perguntas Comuns (FAQ)​

Como faço para criar um pedido com vários produtos?​

Passe um array de objetos de produtos no campo products do corpo do pedido. Cada item precisa de productId e quantity (e opcionalmente signedPrice). O total é calculado automaticamente.

Posso atualizar um pedido depois que ele foi criado?​

Sim — use updateOrderByMarkerAndId() para modificar detalhes do pedido, como status, dados do formulário ou produtos. Tenha cuidado ao alterar itens ou totais uma vez que o pagamento está em andamento.

Como faço para acompanhar as mudanças de status do pedido?​

Leia o campo statusIdentifier para o estado atual e busque os status disponíveis do armazenamento com getAllStatusesByStorageMarker(). Você também pode usar o Módulo de Eventos para reagir a mudanças.

Qual é a diferença entre armazenamento de pedidos e pedidos individuais?​

O armazenamento de pedidos é um contêiner que agrupa pedidos relacionados (por exemplo, pedidos de um formulário específico ou canal de vendas). Pedidos individuais são as transações dentro desse armazenamento. Use marcadores para identificar e organizar os armazenamentos.

Como faço para lidar com cancelamentos e reembolsos de pedidos?​

Atualize o status do pedido com updateOrderByMarkerAndId(). Para reembolsos, use os métodos de reembolso do Orders: createRefundRequest() para solicitar um, getRefunds() para listar as solicitações de um pedido, e cancelRefundRequest() para cancelar uma.

🎓 Melhores Práticas​

  • Visualize antes de criar — chame previewOrder() para mostrar descontos, cupons e bônus no resumo do checkout.
  • Use signedPrice quando os produtos entrarem no checkout para que o preço não possa variar entre a navegação e o pedido.
  • Autentique primeiro — os métodos de criação/leitura/atualização de pedidos requerem um usuário autorizado (veja AuthProvider).
  • Paginar listas de pedidos (offset + limit) — não carregue todos os pedidos de uma vez.
  • Referencie armazenamentos e formulários pelo marcador, não pelo nome exibido — os marcadores são estáveis.

🔗 Documentação Relacionada​