Consultar pedido
Abre um pedido completo do cliente (ou do visitante) e busca pedido por número e e-mail.
Abre um pedido completo: totais, itens, endereços, histórico de status e os sinais de que o cliente ainda pode pagar. Use depois de Meus pedidos, quando o cliente toca em um pedido, e também na tela de confirmação logo após a compra.
Esta é uma das poucas rotas desta seção que também aceita visitante (quem comprou sem conta). Há duas formas de chegar ao pedido: o cliente logado manda o token; o visitante manda ?email= com o e-mail da compra, e a loja precisa permitir compra sem conta. Para quem só tem o número do pedido e o e-mail, veja a segunda rota desta página.
/api/v1/storefront/orders/{id}AutenticadaConsulta um pedido (cliente logado ou visitante)
Parâmetros de caminho
iduuidobrigatórioid devolvido por Meus pedidos ou por Criar pedido). Um texto que não é UUID responde 404 order not found.Parâmetros de consulta
emailstring401), e se email vier errado a resposta é 404. É ignorado quando há token.Exemplo de requisição
Resposta
Campos da resposta
orderobjectResumo do pedido.
iduuidorder_id repete o mesmo valor.order_numberstring-V1, -V2.vendor_iduuidcompany_id repete o valor.customer_iduuidsubtotalinteger4990 = R$ 49,90).shipping_totalintegertax_totalintegerdiscount_totalintegertotalintegercurrencystringBRL.payment_methodstringpix, credit_card...). payment_method_name traz o nome para exibir.payment_statusstringpending, authorized, captured, refunded ou failed.statusstringO, P, S, C, I...). Cada loja tem o seu cadastro: leia-o em Status de pedido.status_textstringpending, processing, shipped...) ou o código próprio da loja.sales_channelstringweb, pos, whatsapp...).shipping_method_namestringmin_delivery_days e max_delivery_days guardam o prazo prometido.is_guestbooleantrue quando o pedido foi feito sem conta.created_atstringupdated_at é a última alteração.itemsarrayLinhas do pedido.
iduuidorder_item_id que a devolução pede.product_iduuidproduct_namestringproduct_sku traz o SKU.unit_priceintegerquantitynumberdiscountintegertotalintegeroptionsobject{} quando não há.addressesarrayEndereços gravados no pedido (uma cópia, não o endereço do seu caderno). Um item com address_type billing e outro shipping.
cpfstringtax_id.districtstringstatus_historyarrayold_status, new_status, reason e created_at.can_repaybooleantrue quando o status atual da loja permite pagar de novo (ver Retomar pagamento).can_retry_paymentbooleantrue enquanto a janela de retomada do pagamento está aberta. payment_retryable repete o valor; payment_retry_token só vem para quem pode usá-lo.pickupobjectcredit_split_grouparrayorder_dataarrayErros
| Status | Quando | Corpo |
|---|---|---|
| 401 | Sem token e a loja não permite compra sem conta, ou pedido que não é de visitante | {"error":"authentication required"} |
| 401 | Token inválido ou expirado | {"error":"invalid or expired token"} |
| 404 | O id não existe ou o pedido não é seu (a API nunca diz qual dos dois) | {"error":"order not found"} |
| 500 | Falha interna ao ler o pedido | {"error":"failed to get order","detail":"..."} |
/api/v1/storefront/orders/trackPúblicaBusca um pedido pelo número e pelo e-mail (visitante)
Rota pública para o visitante que perdeu o link: com o número do pedido (o order_number que a loja mostrou e mandou por e-mail) e o e-mail da compra, devolve o mesmo pedido da rota anterior, sem precisar de login.
Corpo da requisição
order_numberstringobrigatórioemailstringobrigatórioO corpo segue o mesmo formato de order, items, addresses e status_history da primeira rota (aqui encurtado). Atenção: a resposta inclui os endereços completos e o CPF gravados no pedido; só mostre na tela depois de conferir o e-mail com o usuário.
| Status | Quando | Corpo |
|---|---|---|
| 400 | order_number ou email vazios, ou corpo que não é JSON | {"error":"order_number and email are required"} |
| 404 | Nenhum pedido combina número e e-mail | {"error":"order not found","detail":"no order matches the provided order number and email"} |
| 500 | Falha interna na busca | {"error":"failed to look up order","detail":"..."} |