Pedidos da mini-loja

Depois do checkout, a mini-loja continua útil: é nela que o cliente reabre o Pix que perdeu, troca a forma de pagamento, anexa o comprovante, pede para cancelar, acompanha a entrega e compra de novo. Estas rotas servem a aba "Pedidos" e a tela de cada pedido, que o link das mensagens de WhatsApp abre.

Esta seção também reúne o que acontece em torno do pedido: a oferta de um clique logo depois da compra, a proposta de um representante que vira pedido e as assinaturas e compras agendadas.

Como funciona

A régua que decide o que o cliente pode fazer é a etapa (stage):

1. Acompanhar

   GET /orders/{token} mostra a lista; GET /order/{token}/{orderID} mostra um pedido com itens, pagamento, linha do tempo e rastreio.

2. Pagar ou corrigir o pagamento

   Se o Pix venceu ou o cartão foi recusado, o cliente troca a forma de pagamento ou tenta outro cartão. Para Pix manual, anexa o comprovante.

3. Cancelar, se precisar

   POST .../cancel cancela na hora ou registra o pedido de cancelamento, conforme a etapa.

4. Comprar de novo

   POST .../reorder leva os itens do pedido para a sacola, revalidados.

Conceitos-chave

Quem é o dono do pedido

O dono é identificado pelo telefone do token e pela conta ligada a ele: pedidos feitos como convidado com aquele número, pedidos da conta do cliente e pedidos feitos antes em outro canal e ligados à mesma conta. Um visitante sem conta só vê, pelo detalhe, os pedidos feitos com o número do token. A lista exige conta identificada.

Status do pedido e do pagamento

Cada loja define o seu fluxo de status. O pedido traz status (a letra gravada), status_code (código estável, como pending ou shipped), status_name (o nome que a loja dá) e status_color. Decida pelo status_code e pelo stage, e exiba o status_name. O pagamento tem o seu próprio estado em payment.state: paid, pending, analysis, refused, refunded, invoiced ou on_delivery.

Pedido dividido

Em lojas com regras de pedido por tipo, uma sacola pode virar mais de um pedido (por exemplo, um físico e um virtual). Cada um tem o seu pagamento, e o checkout devolve a lista.

Avaliações

Avaliar os produtos de um pedido entregue é feito pelas rotas de Avaliações, na seção do catálogo. O campo can_review do detalhe diz quando o pedido já pode ser avaliado.

Endpoints

Erros comuns

• Mostrar "Pagar agora" para pedido recusado. O status pode continuar "aguardando pagamento" com o cartão recusado. Olhe payment.state e payment_state.
• Oferecer cancelar sem olhar a etapa. Use can_cancel e cancel_needs_store. Em preparing o cancelamento é um pedido à loja, não imediato.
• Tratar 204 como erro. O rastreio e a consulta de pagamento respondem 204 sem corpo quando não há o que mostrar, inclusive para pedido de outra pessoa.
• Reenviar o checkout após um timeout. Consulte a lista de pedidos antes: o pedido pode ter sido criado.
• Enviar o anexo como JSON. O envio de anexo é multipart/form-data e só aceita o tipo comprovante_pix, em lojas com Pix manual.
• Esperar que a lista seja paginada. Ela devolve no máximo 30 pedidos, sem filtros.

Próximos passos