Pedidos do cliente
Como a loja ou o aplicativo consulta, acompanha e age nos pedidos do cliente logado.
Esta área é a API que uma loja virtual ou um aplicativo chama em nome de um cliente logado: ver os próprios pedidos, abrir o detalhe de um deles, baixar a fatura, pedir cancelamento, acompanhar o envio, retomar um pagamento que falhou, avaliar o que comprou e comprar de novo. Quem chama não é um administrador nem um seller (lojista): é o JWT de um cliente, o mesmo que o login da vitrine devolve.
Como funciona
O ciclo de vida do pedido, do ponto de vista do cliente
O pedido nasce no checkout (Criar pedido ou, para quem não tem conta, Pedido de visitante). A partir daí a loja ou o seller move o status; o cliente só observa e, em momentos específicos, age.
Código (status_text) | O que o cliente vê | O que o cliente pode fazer |
|---|---|---|
pending | Pedido recebido, aguardando pagamento. | Pagar de novo ou trocar a forma de pagamento (Retomar pagamento); pedir cancelamento, se a loja permitir. |
paid / processing | Pagamento confirmado, pedido em preparação. | Acompanhar; pedir cancelamento dentro da regra da loja. |
on_hold | Parado pela loja, à espera de algo. | Aguardar. |
shipped | Pacote saiu da loja. | Ver rastreio (Acompanhar o envio). |
delivered / completed | Entregue e concluído. | Baixar fatura e nota fiscal, avaliar os produtos, pedir devolução ou abrir contestação, comprar de novo. |
cancelled, failed | Cancelado ou pagamento recusado. O estoque volta. | Comprar de novo. |
refunded, chargeback | Dinheiro devolvido, ou pagamento contestado no cartão. | Nada; é estado final. |
Essa é a instalação padrão. Cada loja pode renomear, esconder e criar status, e trocar as letras: o status do pedido é uma letra, e a tradução fica no cadastro público de Status de pedido. Para o catálogo completo e as regras de mudança de status do lado da loja, veja a seção de pedidos do guia rápido.
Fluxo típico de um aplicativo
- Entrar
Faça o login do cliente (Login) e guarde o token. Todas as chamadas abaixo levam esse token.
- Listar e abrir
Meus pedidos alimenta a tela de histórico; ao tocar em um pedido, Consultar pedido traz o detalhe.
- Agir conforme o estado
Pedido pendente: Retomar pagamento. Pedido a caminho: Acompanhar o envio. Pedido entregue: Fatura, Nota fiscal, Avaliações e Devoluções.
- Arrependimento
Cancelar pedido consulta primeiro se a loja aceita cancelamento naquele estado e só então pede.
Conceitos-chave
Quem pode ver o quê (propriedade do pedido)
O token do cliente identifica quem ele é, e todas as rotas filtram por isso. Um pedido é visível para o cliente quando: (1) o customer_id do pedido é o dele; (2) o pedido foi feito como visitante com o mesmo e-mail do cliente (esse pedido abre pelo id, mas não aparece na lista, que filtra só por customer_id); ou (3) a conta dele pertence a uma conta corporativa (vários usuários do mesmo CNPJ, ou membros de uma organização que pode ver os pedidos dela), caso em que a lista e o detalhe mostram os pedidos dos usuários vinculados. Fora disso a resposta é 404 order not found.
Logado ou visitante
A loja pode permitir comprar sem conta (configuração da loja). O visitante cria o pedido pela rota de pedido de visitante e depois só tem três portas de volta: Consultar pedido com ?email=, o rastreamento por número e e-mail e o link de retomada de pagamento (token ou e-mail). Todo o resto desta seção exige token de cliente. Se o visitante criar uma conta com o mesmo e-mail, os pedidos antigos passam a abrir pelo id com o token dele (mas não entram na lista).
Pedido pai e sub-pedidos
Uma compra com produtos de mais de um seller vira um pedido pai (o que o cliente paga) e um sub-pedido por seller (o que cada seller separa e envia). A lista de pedidos do cliente mostra só os pais; os sub-pedidos vêm em Acompanhar o envio.
O que depende de módulo ou configuração
| Rota | Depende de | Quando desligado |
|---|---|---|
GET /orders/{id}/tracking | módulo order-status-flow | 403 module_disabled |
GET /orders/{id}/correios/tracking | módulo correios-shipping | 403 module_disabled |
GET /orders/{id}/fulfillment | módulo fulfillment | 403 module_disabled |
GET /orders/{id}/nfe* | módulo focusnfe | 403 module_disabled |
GET /orders/{id}/reviewable, POST .../review | módulo product-reviews | 403 module_disabled |
POST /orders/{id}/invoice/send | configuração customer_invoice_email (padrão desligada) | 404 not found |
POST /orders/{id}/cancel | configuração de cancelamento pelo cliente | 409 cancellation_not_available |
/returns*, POST /orders/{id}/return | módulo returns | 403 module_disabled |
Endpoints
| Método e caminho | Para quê | Autenticação | Página |
|---|---|---|---|
GET /api/v1/storefront/orders | Lista os pedidos do cliente | cliente | Meus pedidos |
POST /api/v1/storefront/orders | Cria o pedido a partir do carrinho | cliente | Criar pedido |
GET /api/v1/storefront/orders/{id} | Detalhe de um pedido | cliente ou visitante | Consultar pedido |
POST /api/v1/storefront/orders/track | Busca por número e e-mail | pública | Consultar pedido |
GET /api/v1/storefront/order-statuses | Cadastro de status da loja | pública | Status de pedido |
GET /api/v1/storefront/orders/{id}/cancellation | Pode cancelar? De que jeito? | cliente | Cancelar pedido |
POST /api/v1/storefront/orders/{id}/cancel | Cancela ou pede cancelamento | cliente | Cancelar pedido |
GET /api/v1/storefront/orders/{id}/invoice | Fatura em JSON ou HTML | cliente | Fatura do pedido |
GET /api/v1/storefront/orders/{id}/invoice.pdf | Fatura em PDF | cliente | Fatura do pedido |
POST /api/v1/storefront/orders/{id}/invoice/send | Envia a fatura por e-mail | cliente | Fatura do pedido |
GET /api/v1/storefront/orders/{id}/nfe | Dados da NF-e | cliente | Nota fiscal (NF-e) |
GET /api/v1/storefront/orders/{id}/nfe/xml | XML da NF-e | cliente | Nota fiscal (NF-e) |
GET /api/v1/storefront/orders/{id}/nfe/danfe | DANFE em PDF | cliente | Nota fiscal (NF-e) |
GET /api/v1/storefront/orders/{id}/tracking | Etapas e linha do tempo | cliente | Acompanhar o envio |
GET /api/v1/storefront/orders/{id}/correios/tracking | Rastreio dos Correios por volume | cliente | Acompanhar o envio |
GET /api/v1/storefront/orders/{id}/fulfillment | Remessas do pedido | cliente | Acompanhar o envio |
GET /api/v1/storefront/orders/{id}/sub-orders | Sub-pedidos por seller | cliente | Acompanhar o envio |
GET /api/v1/storefront/orders/{id}/payment-retry | Dá para pagar de novo? | cliente ou visitante | Retomar pagamento |
POST /api/v1/storefront/orders/{id}/payment-retry | Paga de novo | cliente ou visitante | Retomar pagamento |
POST /api/v1/storefront/orders/{id}/payment-retry/cancel | Desiste e cancela o pedido | cliente ou visitante | Retomar pagamento |
GET /api/v1/storefront/orders/{id}/reviewable | Que itens dá para avaliar | cliente | Avaliar o que comprou |
POST /api/v1/storefront/orders/{id}/items/{productID}/review | Avalia um item | cliente | Avaliar o que comprou |
POST /api/v1/storefront/orders/{orderId}/reorder | Põe os itens de volta no carrinho | cliente | Comprar de novo |
Devoluções, contestações, perfil, endereços e preferências do cliente estão nas seções Devoluções e contestações e Conta do cliente.