# Pedidos

Os pedidos podem ser criados de duas maneiras: automaticamente quando um cliente conclui o checkout, ou manualmente pelo painel administrativo quando uma venda acontece fora da plataforma (Instagram DM, WhatsApp, telefone, pessoalmente). No painel administrativo você pode visualizar todos os pedidos, criar pedidos manuais, inspecionar detalhes e atualizar os status — cada alteração de status pode disparar uma notificação por e-mail ao cliente.

## Navegando pelos pedidos

Abra **Orders** na barra lateral do painel administrativo para ver a lista completa de pedidos. A tabela exibe o número do pedido, cliente, status, quantidade de itens, total e data de criação.

![Orders list](/features/orders/orders-list.png)

| Coluna       | Descrição                                                    |
| ------------ | ------------------------------------------------------------ |
| Order Number | Número único auto-incrementado (clique para ver os detalhes) |
| User         | Nome e e-mail do cliente                                     |
| Status       | Status atual do pedido exibido como um badge colorido        |
| Items        | Número de produtos no pedido                                 |
| Total        | Total do pedido na moeda da sua loja                         |
| Created At   | Data em que o pedido foi realizado                           |

Você pode **ordenar** clicando nos cabeçalhos das colunas Order Number, Total ou Created At. Use a **barra de pesquisa** para encontrar pedidos por número ou nome/e-mail do cliente. O filtro **Status** permite restringir os resultados a um status específico, o filtro **User** permite buscar os pedidos de um cliente específico, e o filtro **Source** separa pedidos **Online** (checkout) dos pedidos **Manual**.

Pedidos manuais para clientes de loja física ou em dinheiro sem um e-mail real cadastrado exibem um badge **Offline customer** no lugar do endereço de e-mail, para que você identifique rapidamente quais pedidos não acionarão notificações ao cliente.

## Exportando pedidos

Clique no botão **Export Orders** no topo da lista de pedidos para descarregar a visualização atual em formato CSV. A exportação respeita os filtros e a pesquisa ativa — apenas as linhas visíveis na lista são incluídas, pelo que pode limitar a exportação a um único status, um intervalo de datas, um cliente específico ou apenas a pedidos manuais.

Use para contabilidade, conciliação com marketplaces, ou para alimentar pedidos num sistema externo de fulfillment.

## Criando um pedido manual

Clique em **Create manual order** na lista de pedidos para registrar uma venda que aconteceu fora da plataforma. Um pedido manual funciona exatamente como um pedido de checkout — o estoque é decrementado, os totais são calculados, e o cliente pode opcionalmente receber um e-mail de confirmação — mas você controla cada campo manualmente.

![Create manual order — Customer and Items](/features/orders/manual-order-create-top.png)

### Etapa 1 — Escolha um cliente

Escolha entre duas opções no topo do formulário:

- **Existing customer** — busque por nome ou e-mail e selecione um usuário que já existe na sua loja.
- **New customer** — informe um **Name** (obrigatório). **Email (Optional)** pode ficar em branco para vendas presenciais ou em dinheiro sem dados de contato; nesse caso o sistema cria um usuário leve com um e-mail marcador e nenhuma confirmação é enviada.

> **Tip:** Se o mesmo e-mail for usado posteriormente para criar uma conta real, os dois serão vinculados automaticamente.

### Etapa 2 — Adicione itens

Cada linha tem **Product**, **Qty** e **Unit price**. Ao selecionar um produto o preço atual é preenchido automaticamente, mas pode ser sobrescrito para negociações exclusivas. Clique em **+ Add item** para adicionar mais linhas.

> **Important:** Produtos com variantes devem ser adicionados como uma variante específica, não como o produto pai. Os itens são **travados após a criação do pedido** — se precisar alterar os itens, cancele o pedido e crie um novo.

![Create manual order — Shipping, payment, status](/features/orders/manual-order-create-bottom.png)

### Etapa 3 — Endereço de entrega (opcional)

Ative **Add shipping address** se quiser registrar um endereço de entrega. Quando ativado, **Name**, **Street**, **Zip** e **Country** são obrigatórios; **Phone**, **State** e **City** são opcionais. Você também pode pular esta etapa e adicionar o endereço depois pela página do pedido.

### Etapa 4 — Envio e pagamento (opcional)

| Campo               | O que faz                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Shipping Method** | Filtra pelo país do endereço de entrega. Limpa automaticamente se você mudar o país e a opção não corresponder mais.   |
| **Payment Method**  | Apenas métodos off-line (pagamento na entrega, transferência bancária, etc.). Métodos Stripe/PSP são ocultos em pedidos manuais. |

### Etapa 5 — Status e totais

| Campo                          | Observações                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Status**                      | Padrão **Paid**, pois o pagamento já aconteceu fora da plataforma. Escolha qualquer status que reflita a realidade. |
| **Manual discount (Optional)**  | Valor fixo a ser subtraído do total. É separado de qualquer cupom.                                            |
| **Manual surcharge (Optional)** | Valor fixo a ser somado ao total. Use para taxas de manuseio de dinheiro, adicionais de entrega, arredondamentos, etc. É separado do custo de envio. |
| **Send confirmation email to**  | Sobrescreve o e-mail de contato para a confirmação. Deixe em branco para usar o e-mail do cliente. Nada é enviado se o cliente tiver um e-mail marcador. |
| **Delivery date (Optional)**    | Escolha uma data. Datas passadas são permitidas para retroativar um pedido.                                   |

A prévia **Total (before tax)** mostra subtotal + envio + acréscimo − desconto. Os impostos são calculados no servidor quando você clica em **Save**, usando as regras de imposto específicas do país para os itens e o país do endereço de entrega.

### Confirmando o pedido

Clicar em **Save** abre a caixa de confirmação **"Create this order?"**. Ela lembra que um e-mail de confirmação será enviado se o cliente tiver um e-mail real cadastrado, e que **após a criação apenas o status pode mudar — todos os outros campos ficam travados**.

Se você pulou algum dos campos opcionais (endereço de entrega, método de envio, método de pagamento, data de entrega), a caixa os lista em um aviso âmbar **Missing:**. O aviso **não** impede a criação — clique em **Create order** para prosseguir mesmo assim, ou em **Go back** para preencher os campos. Após confirmar, você é levado à página de detalhes do pedido.

## Visualizando um pedido

Clique em qualquer número de pedido na lista para abrir a página de detalhes do pedido. A página está dividida em várias seções que mostram todas as informações do pedido.

![Order detail — top section](/features/orders/order-detail-top.png)

### Informações do pedido

| Campo          | Descrição                                                        |
| -------------- | ---------------------------------------------------------------- |
| Customer       | Nome e e-mail do comprador                                       |
| Contact Email  | O endereço de e-mail associado ao pedido                         |
| Current Status | Badge mostrando o status atual                                   |
| Update Status  | Menu suspenso para transicionar o pedido para um novo status     |
| Created At     | Data e hora em que o pedido foi realizado                        |
| Updated At     | Data e hora da última modificação                                |
| Delivery Date  | Data prevista de entrega (se um método de envio foi selecionado) |

### Endereço de entrega

Exibe o endereço de entrega completo fornecido pelo cliente no checkout: nome, rua, cidade, estado, CEP, país e número de telefone.

### Endereço de cobrança

Quando o cliente marcou **Billing same as shipping** durante o checkout (padrão), os detalhes do pedido exibem um único bloco rotulado "Billing same as shipping" em vez de um cartão duplicado. Quando o cliente informou um endereço de cobrança separado, ambos os blocos aparecem lado a lado para que você veja exatamente para onde o pedido foi enviado e onde foi cobrado para fins de imposto. O país de cobrança é o que determinou o cálculo de imposto do pedido.

### Envio e pagamento

| Campo           | Descrição                                           |
| --------------- | --------------------------------------------------- |
| Shipping Method | Nome da opção de envio selecionada e seu custo      |
| Delivery Date   | Data estimada de entrega com base na opção de envio |
| Payment Method  | Nome e tipo do método de pagamento selecionado      |

### Cupom

Se o cliente aplicou um código de cupom, esta seção exibe o código do cupom, o tipo de desconto e o valor do desconto.

### Itens do pedido

![Order detail — items section](/features/orders/order-detail-bottom.png)

Lista todos os produtos do pedido com imagem em miniatura, título (link para o editor do produto), preço unitário, quantidade e total da linha. Abaixo da lista de itens você encontrará o resumo financeiro:

| Linha     | Descrição                                          |
| --------- | -------------------------------------------------- |
| Subtotal  | Soma de todos os totais dos itens antes dos extras      |
| Shipping  | Custo de envio (exibe "Free" quando zero)               |
| Tax       | Valor estimado de impostos                              |
| Surcharge | Acréscimo manual aplicado na criação (se houver)        |
| Discount  | Valor do desconto (exibido em verde)                    |
| **Total** | Valor final cobrado do cliente                          |

## Status dos pedidos

Cada pedido tem um status que reflete em que ponto está no ciclo de fulfillment. Os status são exibidos como badges coloridos em todo o painel administrativo e na página de pedidos do cliente.

| Status          | Significado                                           |
| --------------- | ----------------------------------------------------- |
| Pending Payment | Pedido realizado, aguardando confirmação de pagamento |
| Payment Failed  | O pagamento não pôde ser processado                   |
| Paid            | Pagamento confirmado, pronto para fulfillment         |
| Shipped         | Pedido foi despachado                                 |
| Delivered       | Pedido entregue ao cliente                            |
| Cancelled       | Pedido foi cancelado (terminal)                       |
| Returned        | Cliente devolveu o pedido (terminal)                  |
| Refunded        | Reembolso foi processado (terminal)                   |

> **Important:** Pedidos em status terminal (Cancelled, Returned, Refunded) não podem ser transicionados para nenhum outro status.

## Atualizando o status do pedido

Na página de detalhes do pedido, use o menu suspenso **Update Status** para selecionar o novo status e clique em **Update Status**. Apenas as transições válidas são exibidas no menu — você não pode pular etapas nem reverter estados terminais.

Ao confirmar, abre-se a caixa de diálogo **"Change status to {status}?"**. Ela destaca que **se um e-mail for enviado, ele não pode ser revogado** e exibe uma caixa azul de informação lembrando que o cliente pode receber um e-mail de notificação `"{status}"` dependendo das suas configurações em **Settings → Email**. Clique em **Change to {status}** para aplicar a transição, ou em **Cancel** para desistir.

### Transições permitidas

| De              | Pode transicionar para                  |
| --------------- | --------------------------------------- |
| Pending Payment | Paid, Cancelled, Payment Failed         |
| Payment Failed  | Cancelled                               |
| Paid            | Shipped, Delivered, Cancelled, Refunded |
| Shipped         | Delivered, Cancelled, Refunded          |
| Delivered       | Returned, Refunded                      |
| Cancelled       | _(nenhum — terminal)_                   |
| Returned        | _(nenhum — terminal)_                   |
| Refunded        | _(nenhum — terminal)_                   |

> **Tip:** Para pagamentos PSP (Stripe), a transição de Pending Payment para Paid (ou para Payment Failed, se o pagamento for recusado) acontece automaticamente quando o provedor de pagamento envia um webhook. Você não precisa atualizar esses status manualmente.

## Editando um pedido após a criação

Uma vez que um pedido existe no sistema — seja criado pelo checkout ou registrado manualmente — **apenas o status pode ser alterado**. Todos os campos voltados ao cliente ficam travados:

- Cliente
- Itens (produto, quantidade, preço unitário)
- Endereço de entrega
- Método de envio e método de pagamento
- Desconto e acréscimo
- Data de entrega
- E-mail de contato

**Por que tudo fica travado?** No momento em que o pedido é criado, o e-mail de confirmação é enviado imediatamente ou fica na fila para sair assim que o pagamento for confirmado. Alterar qualquer um desses campos depois deixaria o cliente com um comprovante que não corresponde mais ao pedido no sistema.

**O que fazer em vez disso:** se um item, endereço ou total precisar ser corrigido, cancele o pedido (o que restaura o estoque) e crie um novo com os valores corretos.

## Notificações por e-mail

A plataforma pode enviar notificações por e-mail aos clientes em dois momentos do ciclo de vida do pedido: quando um pedido é realizado pela primeira vez e sempre que você altera seu status.

### E-mails de novo pedido

Quando um cliente conclui o checkout, o sistema envia **dois e-mails** (se habilitado em Settings > Email):

1. **E-mail do cliente** — uma confirmação com o número do pedido, itens, totais, endereço de entrega, endereço de cobrança e data estimada de entrega. Quando o endereço de cobrança difere do de entrega, ambos são listados; caso contrário, um único bloco indica que a cobrança coincide com a entrega. Enviado no idioma preferido do cliente.
2. **E-mail da loja** — uma notificação ao proprietário da loja com os mesmos detalhes do pedido. Enviado em inglês para o e-mail configurado nas configurações da sua loja.

Esses e-mails são controlados pelo botão **Send email on new order** em Settings > Email.

### E-mails de alteração de status

Cada vez que você atualiza o status de um pedido, o sistema pode enviar um e-mail de notificação ao cliente. Cada status tem seu próprio botão de ativação e campo de texto personalizado opcional em Settings > Email — você pode habilitar ou desabilitar os e-mails individualmente para Payment Failed, Paid, Shipped, Delivered, Cancelled, Returned e Refunded.

Cada e-mail contém uma mensagem específica ao status (por exemplo, "Your order is on its way!" para Shipped), o número do pedido, lista de itens e totais do pedido. Se você fornecer um texto personalizado para um status, ele aparecerá como um parágrafo adicional no e-mail.

> **Tip:** Os e-mails de alteração de status são enviados no idioma preferido do cliente. Configure suas traduções em Settings > Languages para garantir que os clientes recebam os e-mails no idioma deles.

## Como os clientes visualizam seus pedidos

### Página de confirmação do pedido

Após concluir o checkout, os clientes são redirecionados para a página de confirmação do pedido. Ela exibe um banner de agradecimento, o número do pedido, itens, totais, endereço de entrega e método de pagamento.

Para pagamentos PSP (Stripe), a página exibe um indicador de status de pagamento em tempo real que consulta o servidor a cada 2 segundos por até 30 segundos. Assim que o pagamento é confirmado, o banner é atualizado para exibir uma mensagem de sucesso. Se o pagamento falhar, um banner de erro vermelho é exibido.

### Histórico de pedidos

Os clientes podem visualizar todos os seus pedidos anteriores na página **Profile**, na seção **Order History**.

![Profile — order history](/features/orders/profile-order-history.png)

Cada cartão de pedido exibe o número do pedido, data, badge de status, valor total e uma lista de itens com miniaturas. Clicar em um cartão de pedido abre a página completa de detalhes do pedido. Os pedidos são paginados com 5 por página.

## Como os pedidos são criados

Os pedidos chegam ao banco de dados de duas maneiras:

**Pelo checkout.** Quando um cliente clica em **Complete Order** na loja, um pedido é criado a partir do snapshot de checkout com todos os itens, preços, endereço, envio e detalhes de pagamento. O estoque permanece decrementado (foi reservado quando o cliente entrou no checkout), o carrinho é marcado como concluído, o contador de uso de qualquer cupom aplicado é incrementado, os e-mails de novo pedido são enviados (se habilitado) e o cliente é redirecionado para a página de confirmação do pedido.

**Manualmente.** Quando você clica em **Create manual order** na lista de pedidos, você preenche o cliente, os itens e os campos opcionais de envio/pagamento manualmente (veja [Criando um pedido manual](#criando-um-pedido-manual)). O estoque é decrementado da mesma forma e o pedido aparece diretamente na lista — nenhum snapshot de checkout é envolvido. As diferenças em relação aos pedidos de checkout são: (a) nenhum snapshot de checkout é criado, (b) métodos Stripe/PSP não estão disponíveis pois pedidos manuais são para pagamentos fora da plataforma, e (c) o e-mail de confirmação é ignorado se o cliente tiver um e-mail marcador (sem endereço cadastrado). Depois de criados, os dois tipos de pedido são editados da mesma forma — apenas o status pode mudar.