VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pedidos e conta do cliente

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.

GET/api/v1/storefront/orders/{id}Autenticada

Consulta um pedido (cliente logado ou visitante)

Parâmetros de caminho

iduuidobrigatório
Id do pedido (o id devolvido por Meus pedidos ou por Criar pedido). Um texto que não é UUID responde 404 order not found.

Parâmetros de consulta

emailstring
Só para visitante: o e-mail usado na compra. Sem token, a loja precisa ter ligado a compra sem conta (senão 401), e se email vier errado a resposta é 404. É ignorado quando há token.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedido encontrado
json
{
  "order": {
    "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "company_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "company_name": "Loja Exemplo",
    "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
    "customer_name": "Maria Souza",
    "customer_email": "maria.souza@example.com",
    "subtotal": 4990,
    "shipping_total": 1000,
    "tax_total": 0,
    "discount_total": 724,
    "total": 5266,
    "currency": "BRL",
    "payment_method": "pix",
    "payment_method_name": "PIX",
    "payment_status": "pending",
    "sales_channel": "web",
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "shipping_method_name": "Entrega Padrão",
    "min_delivery_days": 10,
    "max_delivery_days": 10,
    "is_guest": false,
    "status": "O",
    "status_text": "pending",
    "created_at": "2026-10-11T20:55:25.558277Z",
    "updated_at": "2026-10-11T20:55:25.558277Z"
  },
  "items": [
    {
      "id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
      "product_id": "a34f126e-ff3b-4779-bf74-bda03502136e",
      "product_name": "Caneca Exemplo",
      "product_sku": "CAN-002",
      "unit_price": 4990,
      "quantity": 1,
      "discount": 724,
      "tax": 0,
      "total": 4266,
      "options": {}
    }
  ],
  "addresses": [
    {
      "address_type": "billing",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    },
    {
      "address_type": "shipping",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    }
  ],
  "status_history": [
    {
      "old_status": "pending",
      "new_status": "pending",
      "reason": "order_created",
      "created_at": "2026-10-11T20:55:25.558277Z"
    }
  ],
  "can_repay": true,
  "can_retry_payment": true,
  "payment_retryable": true
}

Campos da resposta

orderobject

Resumo do pedido.

iduuid
Id do pedido (UUID). order_id repete o mesmo valor.
order_numberstring
Número mostrado ao cliente. Em pedido dividido por seller, os sub-pedidos terminam em -V1, -V2.
vendor_iduuid
Seller (lojista) dono do pedido. Ausente em pedido pai de várias lojas. company_id repete o valor.
customer_iduuid
Cliente dono do pedido. Vazio em pedido de visitante.
subtotalinteger
Soma dos itens, em centavos (4990 = R$ 49,90).
shipping_totalinteger
Frete em centavos.
tax_totalinteger
Impostos em centavos.
discount_totalinteger
Descontos em centavos (cupom, promoção, desconto de PIX).
totalinteger
Total a pagar, em centavos.
currencystring
Moeda ISO 4217, BRL.
payment_methodstring
Código da forma de pagamento (pix, credit_card...). payment_method_name traz o nome para exibir.
payment_statusstring
Situação do pagamento: pending, authorized, captured, refunded ou failed.
statusstring
Letra do status do pedido (O, P, S, C, I...). Cada loja tem o seu cadastro: leia-o em Status de pedido.
status_textstring
Código longo do status (pending, processing, shipped...) ou o código próprio da loja.
sales_channelstring
Canal de origem do pedido (web, pos, whatsapp...).
shipping_method_namestring
Nome da forma de entrega no momento da compra. min_delivery_days e max_delivery_days guardam o prazo prometido.
is_guestboolean
true quando o pedido foi feito sem conta.
created_atstring
Criação, RFC 3339 em UTC. updated_at é a última alteração.
itemsarray

Linhas do pedido.

iduuid
Id da linha. É o order_item_id que a devolução pede.
product_iduuid
Produto comprado.
product_namestring
Nome do produto no momento da compra. product_sku traz o SKU.
unit_priceinteger
Preço unitário em centavos, congelado na compra.
quantitynumber
Quantidade comprada.
discountinteger
Desconto rateado nesta linha, em centavos.
totalinteger
Total da linha depois do desconto, em centavos.
optionsobject
Opções escolhidas (cor, tamanho...). {} quando não há.
addressesarray

Endereços gravados no pedido (uma cópia, não o endereço do seu caderno). Um item com address_type billing e outro shipping.

cpfstring
Documento do comprador gravado no endereço. Aparece também como tax_id.
districtstring
Bairro.
status_historyarray
Histórico de status em ordem cronológica: old_status, new_status, reason e created_at.
can_repayboolean
true quando o status atual da loja permite pagar de novo (ver Retomar pagamento).
can_retry_paymentboolean
true enquanto a janela de retomada do pagamento está aberta. payment_retryable repete o valor; payment_retry_token só vem para quem pode usá-lo.
pickupobject
Só em retirada na loja: situação e código de 6 dígitos que o cliente apresenta no balcão.
credit_split_grouparray
Só quando o pedido foi dividido entre faturado e PIX: os pedidos irmãos do mesmo grupo.
order_dataarray
Registros técnicos que a loja anexa ao pedido. O conteúdo varia de loja para loja e não é contrato; não dependa dele.

Erros

StatusQuandoCorpo
401Sem token e a loja não permite compra sem conta, ou pedido que não é de visitante{"error":"authentication required"}
401Token inválido ou expirado{"error":"invalid or expired token"}
404O id não existe ou o pedido não é seu (a API nunca diz qual dos dois){"error":"order not found"}
500Falha interna ao ler o pedido{"error":"failed to get order","detail":"..."}
Atualize o pedido sem refazer a tela

Depois de pagar por PIX, consulte esta rota a cada poucos segundos e observe order.payment_status e order.status. Pare quando payment_status deixar de ser pending ou quando can_retry_payment virar false.

POST/api/v1/storefront/orders/trackPública

Busca 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ório
Número do pedido, como a loja o exibe.
emailstringobrigatório
E-mail usado na compra. Tem de bater com o do pedido.
bash
curl -X POST "$BASE_URL/api/v1/storefront/orders/track" \
  -H "Content-Type: application/json" \
  -d '{
  "order_number": "PEDIDO-20261011-0009",
  "email": "maria.souza@example.com"
}'
200Pedido encontrado
json
{
  "order": {
    "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "vendor_name": "Loja Exemplo",
    "total": 5266,
    "payment_status": "pending",
    "status": "O",
    "status_text": "pending"
  },
  "items": [],
  "addresses": [],
  "status_history": []
}

O 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.

StatusQuandoCorpo
400order_number ou email vazios, ou corpo que não é JSON{"error":"order_number and email are required"}
404Nenhum pedido combina número e e-mail{"error":"order not found","detail":"no order matches the provided order number and email"}
500Falha interna na busca{"error":"failed to look up order","detail":"..."}

Veja também

  • Meus pedidos
  • Retomar pagamento
  • Pedido de visitante
  • Consultar pedido (administração)
Anterior
Meus pedidos
Próxima
Criar pedido
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também