Introdução

🎯 O que este módulo faz?

O módulo Orders permite que você crie, gerencie e acompanhe pedidos de clientes - desde o checkout do carrinho de compras até o processamento de pagamento e a execução do pedido - lidando com todo o ciclo de vida do pedido de e-commerce.

Pense nisso como seu sistema de gerenciamento de pedidos - os clientes adicionam itens ao carrinho, fazem pedidos, realizam pagamentos e você acompanha tudo, desde a criação do pedido até a entrega, tudo dentro do OneEntry.

📖 Explicação Simples

Toda aplicação de e-commerce precisa de gerenciamento de pedidos:

🛒 Carrinho de Compras - Usuários adicionam produtos, prosseguem para o checkout
📋 Criação de Pedido - Converter carrinho em pedido com os detalhes do cliente
💳 Processamento de Pagamento - Aceitar pagamentos (cartão de crédito, PayPal, etc.)
📦 Rastreamento de Pedido - Acompanhar status (pendente, em processamento, enviado, entregue)
📊 Gerenciamento de Pedidos - Ver todos os pedidos, filtrar por status, pesquisar
🧾 Detalhes do Pedido - Ver itens, totais, informações do cliente

Problemas:

🔒 Sem integração de pagamento - Acompanhamento manual de pagamentos
📊 Rastreamento ruim - Difícil encontrar pedidos, filtrar por status
🔄 Sem automação - Atualizações de status manuais, sem notificações
💸 Sem cálculo de impostos/frete - Calcular manualmente

A solução Orders:

Benefícios:

🔒 Pagamentos integrados - Stripe, PayPal, outros gateways
📊 Rastreamento avançado - Filtrar, pesquisar, exportar pedidos
🔄 Fluxos de trabalho automatizados - Atualizações de status, notificações
💸 Cálculos automáticos - Impostos, frete, descontos

✨ Conceitos Chave

O que é um Pedido?

Um Pedido é uma transação de compra do cliente contendo:

Itens do Pedido - Produtos/serviços sendo comprados (quantidade, preço)
Informações do Cliente - Nome, e-mail, telefone
Endereço de Entrega - Local de entrega
Endereço de Cobrança - Informações de cobrança do pagamento
Detalhes do Pagamento - Método de pagamento, ID da transação
Totais do Pedido - Subtotal, imposto, frete, total
Status do Pedido - Estado atual (pendente, em processamento, concluído)
Carimbos de Data/Hora - Datas de criação, atualização, conclusão

Estrutura do Pedido

Cada pedido tem esta estrutura:

{
  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' },
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
    },
  ],
  isCompleted: true,
}

Ciclo de Vida do Pedido

1. O cliente adiciona itens ao carrinho
   ↓
2. Prossegue para o checkout
   ↓
3. Insere informações de entrega/cobrança
   ↓
4. Seleciona o método de pagamento
   ↓
5. Pedido criado (status: pendente)
   ↓
6. Pagamento processado (status: em processamento)
   ↓
7. Pedido confirmado (status: confirmado)
   ↓
8. Itens preparados (status: em processamento)
   ↓
9. Pedido enviado (status: enviado)
   ↓
10. Pedido entregue (status: concluído)

Exemplos de Status de Pedido

Status	Significado	Quando Usar
pendente	Pedido criado, aguardando pagamento	Acabou de ser feito, pagamento não processado
em processamento	Pagamento recebido, preparando itens	Pagamento confirmado, embalando itens
confirmado	Pedido confirmado, pronto para envio	Pagamento liberado, pedido verificado
enviado	Pedido despachado para o cliente	Pacote enviado via transportadora
entregue	Pedido recebido pelo cliente	Entrega confirmada
concluído	Pedido finalizado, nenhuma ação necessária	Transação completa
cancelado	Pedido cancelado	Cliente/admin cancelou
reembolsado	Pagamento devolvido ao cliente	Reembolso processado
falhou	Pagamento ou processamento falhou	Pagamento recusado

Operações Comuns de Pedido

Operação	Descrição	Exemplo de Caso de Uso
Criar Pedido	Converter carrinho em pedido	Botão de checkout clicado
Obter Pedidos	Listar todos os pedidos (paginados)	Painel de administração
Obter Pedido por ID	Buscar pedido específico	Ver detalhes do pedido
Atualizar Status	Mudar status do pedido	Marcar como enviado
Calcular Totais	Calcular imposto, frete, total	Resumo do checkout
Cancelar Pedido	Cancelar pedido pendente	Cliente solicita cancelamento
Reembolsar Pedido	Retornar pagamento ao cliente	Devolução de produto

Por que usar o módulo Orders?

Benefício	Descrição
Gerenciamento de Pedidos Automatizado	Sem acompanhamento manual, tudo automatizado
Integração de Pagamento	Stripe, PayPal, outros gateways integrados
Rastreamento de Status	Atualizações de status de pedido em tempo real
Notificações ao Cliente	Envio automático de confirmações de pedido, atualizações de envio
Gerenciamento de Estoque	Dedução automática de estoque ao fazer o pedido
Análise e Relatórios	Relatórios de vendas, acompanhamento de receita
Segurança	Processamento de pagamento em conformidade com PCI

📋 O que você precisa saber

Pedidos são Criados a partir de Dados do Carrinho

Você precisa fornecer:

Informações do cliente - Nome, e-mail, telefone
Itens do pedido - Produtos, quantidades, preços
Endereço de entrega - Local de entrega
Método de pagamento - Como o cliente pagará

Gerenciamento de Status do Pedido

Acompanhe o progresso do pedido através dos status:

Fluxos de status comuns:

Produtos digitais: pendente → em processamento → concluído
Produtos físicos: pendente → em processamento → enviado → entregue → concluído
Cancelado: qualquer status → cancelado
Reembolsado: concluído → reembolsado

Processamento de Pagamento

Os pedidos se integram com gateways de pagamento

💡 Notas Importantes

Pedidos são Criados no OneEntry

O módulo Orders lida com todo o ciclo de vida do pedido:

✅ Criar pedidos a partir de dados do carrinho
✅ Processar pagamentos
✅ Atualizar status do pedido
✅ Acompanhar envio
❌ NÃO lida com a interface do carrinho de compras (você constrói isso)

Sua responsabilidade:

Construir a interface do carrinho de compras
Coletar informações do cliente
Exibir confirmação do pedido

Processamento de Pagamento

Os pedidos se integram com gateways de pagamento:

Stripe (recomendado)
PayPal
Gateways personalizados

Importante:

Nunca armazene detalhes do cartão de crédito diretamente
Use tokenização (Stripe.js, PayPal SDK)
O OneEntry lida com o processamento seguro de pagamentos

Gerenciamento de Estoque

Os pedidos automaticamente:

✅ Deduzem o estoque na criação do pedido
✅ Restauram o estoque no cancelamento
✅ Acompanham os níveis de estoque

Melhor prática: Verifique o estoque antes de criar o pedido

Segurança

Os pedidos contêm dados sensíveis:

Informações pessoais do cliente
Detalhes do pagamento
Endereços de entrega

Sempre:

Use HTTPS para páginas de checkout
Valide os dados antes de criar pedidos
Implemente autenticação adequada
Siga a conformidade PCI DSS para pagamentos

📊 Tabela de Referência Rápida

Método	Descrição
createOrder()	Criar novo pedido
getAllOrdersByMarker()	Obter todos os pedidos (paginados)
getOrderByMarker()	Obter um objeto de armazenamento de pedido específico 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.

❓ Perguntas Comuns (FAQ)

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

Passe um array de objetos de produtos nos dados do pedido. Cada produto deve incluir id, quantidade e preço. O total é calculado automaticamente com base nas quantidades e preços dos produtos.

Posso atualizar um pedido depois que ele foi criado?

Sim, use updateOrderByMarkerAndId() para modificar detalhes do pedido, como status, endereço de entrega ou dados do pedido. No entanto, uma vez que o pagamento é processado, tenha cuidado ao modificar itens ou totais do pedido.

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

Use o campo statusIdentifier para acompanhar o estado atual do pedido. Você também pode configurar webhooks ou usar o módulo Events para receber notificações quando o status do pedido mudar.

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

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

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

Atualize o status do pedido para 'cancelado' usando updateOrderByMarkerAndId(). Para reembolsos, use o módulo Payments para processar a transação de reembolso e, em seguida, atualize o status do pedido para 'reembolsado'.

Posso recuperar o histórico de pedidos de um cliente?

Sim, use getAllOrdersByMarker() com filtros apropriados para buscar todos os pedidos de um cliente específico. Você pode filtrar por ID de usuário, intervalo de datas ou outros critérios.

🎓 Melhores Práticas

Valide o carrinho antes de criar o pedido - Verifique a disponibilidade do estoque
Calcule os totais no servidor - Nunca confie em cálculos do lado do cliente
Envie confirmações de pedido - Envie e-mails para os clientes após o pedido ser feito
Acompanhe o status do pedido - Atualize o status à medida que o pedido avança
Lide com falhas de pagamento - Lógica de repetição, mensagens de erro claras
Implemente a busca de pedidos - Permita que os clientes encontrem seus pedidos facilmente
Armazene o histórico de pedidos - Mantenha registros para atendimento ao cliente
Use paginação - Não carregue todos os pedidos de uma vez

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

Definição do módulo Orders


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

🔗 Documentação Relacionada

Módulo de Produtos - Gerenciar produtos disponíveis para compra
Módulo de Usuários - Gerenciar clientes que fazem pedidos
Módulo IntegrationCollections - Integrações de gateways de pagamento
Módulo de Eventos - Notificações de status de pedidos

Introdução

🎯 O que este módulo faz?​

📖 Explicação Simples​

✨ Conceitos Chave​

O que é um Pedido?​

Estrutura do Pedido​

Ciclo de Vida do Pedido​

Exemplos de Status de Pedido​

Operações Comuns de Pedido​

Por que usar o módulo Orders?​

📋 O que você precisa saber​

Pedidos são Criados a partir de Dados do Carrinho​

Gerenciamento de Status do Pedido​

Processamento de Pagamento​

💡 Notas Importantes​

Pedidos são Criados no OneEntry​

Processamento de Pagamento​

Gerenciamento de Estoque​

Segurança​

📊 Tabela de Referência Rápida​

❓ Perguntas Comuns (FAQ)​

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

Posso atualizar um pedido depois que ele foi criado?​

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

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

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

Posso recuperar o histórico de pedidos de um cliente?​

🎓 Melhores Práticas​

Definição do módulo Orders​

🔗 Documentação Relacionada​

🎯 O que este módulo faz?

📖 Explicação Simples

✨ Conceitos Chave

O que é um Pedido?

Estrutura do Pedido

Ciclo de Vida do Pedido

Exemplos de Status de Pedido

Operações Comuns de Pedido

Por que usar o módulo Orders?

📋 O que você precisa saber

Pedidos são Criados a partir de Dados do Carrinho

Gerenciamento de Status do Pedido

Processamento de Pagamento

💡 Notas Importantes

Pedidos são Criados no OneEntry

Processamento de Pagamento

Gerenciamento de Estoque

Segurança

📊 Tabela de Referência Rápida

❓ Perguntas Comuns (FAQ)

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

Posso atualizar um pedido depois que ele foi criado?

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

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

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

Posso recuperar o histórico de pedidos de um cliente?

🎓 Melhores Práticas

Definição do módulo Orders

🔗 Documentação Relacionada