VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Pedidos

Consultar pedido

Retorna um pedido completo, com itens, endereços, pagamento, histórico de status e sub-pedidos.

Use esta operação quando você já sabe o id do pedido e precisa do detalhe: os itens comprados, os endereços de cobrança e entrega, o meio de pagamento e o que aconteceu com o pedido até agora. É o passo seguinte natural depois de Listar pedidos, que devolve só o resumo.

A resposta é um envelope com cinco blocos: order, items, addresses, status_history e, quando existem, sub_orders e order_data.

GET/api/v1/admin/orders/{id}Admin

Consulta um pedido

Exige o privilégio view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do pedido.
GET/api/v1/admin/orders/{id}/dataAdmin

Registros de metadados (order_data) de um pedido

Devolve apenas a lista de registros auxiliares do pedido (order_data): dados que outras partes da plataforma anexam ao pedido, como o detalhe do pagamento, o rateio de uma promoção ou a resposta de um ERP. O mesmo conteúdo já vem dentro do detalhe, no bloco order_data; use esta rota quando só ele interessa.

Path parameters

iduuidobrigatório
Id do pedido.

Exemplo de requisição

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

Resposta

200Pedido retornado (trecho)
json
{
  "order": {
    "id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "order_number": "PEDIDO-20261010-0004",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "vendor_name": "Loja Seller Teste",
    "customer_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
    "subtotal": 30000,
    "shipping_total": 0,
    "tax_total": 0,
    "discount_total": 7500,
    "total": 22500,
    "currency": "BRL",
    "payment_method": "pix",
    "payment_method_name": "PIX",
    "payment_status": "captured",
    "sales_channel": "web",
    "shipping_method": "Frete Grátis acima de R$199",
    "shipping_method_id": "50000000-0000-0000-0000-000000000003",
    "shipping_method_name": "Frete Grátis acima de R$199",
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza",
    "ip_address": "203.0.113.10",
    "is_guest": false,
    "created_at": "2026-10-11T02:56:25.843882Z",
    "updated_at": "2026-10-11T02:56:38.131475Z",
    "status": "P",
    "status_text": "processing",
    "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
    "total_str": "225.00",
    "timestamp": 1791687385
  },
  "items": [
    {
      "id": "020ead81-da4e-4b70-b80b-88562ba9497a",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "product_name": "Camisa do Flamengo Masculina I 26 Adidas",
      "product_sku": "FLA-I-26",
      "options": {},
      "unit_price": 30000,
      "quantity": 1,
      "discount": 7500,
      "tax": 0,
      "total": 22500,
      "item_id": "020ead81-da4e-4b70-b80b-88562ba9497a",
      "amount": 1,
      "price_str": "300.00",
      "total_str": "225.00"
    }
  ],
  "addresses": [
    {
      "id": "d6038e99-b194-4852-b833-924b1d2cdcbf",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "address_type": "billing",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "district": "Bela Vista",
      "phone": "11999990000",
      "cpf": "123.456.789-09",
      "b_address": "Avenida Paulista, 1000",
      "b_zipcode": "01310-100"
    }
  ],
  "status_history": [
    {
      "id": "b5799638-2816-4653-a90a-1f545cc24507",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "old_status": "pending",
      "new_status": "pending",
      "notes": "order_created",
      "created_at": "2026-10-11T02:56:25.843882Z",
      "reason": "order_created"
    },
    {
      "id": "53d32d3d-a6d1-4d8f-87c5-5b9ca63f62ea",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "old_status": "pending",
      "new_status": "processing",
      "notes": "Pagamento aprovado",
      "created_at": "2026-10-11T02:56:38.131475Z"
    }
  ],
  "order_data": [
    {
      "id": "fd9a0bfd-ae5e-47d9-9e36-2df910de28be",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "data_type": "promotion",
      "data_key": "discount_total",
      "data_value": { "discount_total": 7500 },
      "created_at": "2026-10-11T02:56:25.843882Z"
    }
  ]
}

Campos da resposta

orderobject
O pedido. Traz todos os campos descritos em Listar pedidos, mais os listados abaixo.
order.parent_iduuid
Id do pedido pai. Só em sub-pedido.
order.payment_methodstring
Código (slug) da forma de pagamento.
order.payment_method_namestring
Nome legível da forma de pagamento. Ausente quando o código não corresponde a uma forma cadastrada.
order.payment_refstring
Identificador do pagamento no gateway, quando existe.
order.tracking_numberstring
Código de rastreio gravado no pedido (veja Alterar pedido). Rastreios por remessa ficam em Remessas.
order.shipped_atstring
Quando o pedido foi enviado. RFC 3339.
order.delivered_atstring
Quando o pedido foi entregue. RFC 3339.
order.min_delivery_daysinteger
Prazo mínimo de entrega, em dias, prometido na compra.
order.max_delivery_daysinteger
Prazo máximo de entrega, em dias, prometido na compra.
order.customer_notesstring
Observação do cliente.
order.admin_notesstring
Observação interna. Não é exibida ao cliente.
order.is_guestboolean
true quando o pedido foi feito sem cadastro. Nesse caso customer_id é vazio e guest_email, guest_name e guest_phone identificam o comprador.
order.assigned_touuid
Usuário responsável pelo pedido na equipe da loja.
order.coupon_codestring
Cupom(ns) aplicado(s), separados por vírgula.
order.discount_breakdownarray
De onde veio o desconto. Cada item tem kind (por exemplo promotion, other), label (texto legível), name (quando há) e amount_cents. A soma dos amount_cents é igual a discount_total.
order.payment_adjustment_centsinteger
Ajuste da forma de pagamento em centavos: negativo é desconto (por exemplo, PIX), positivo é acréscimo. Entra no total, mas não em discount_total.
order.purchase_order_numberstring
Número da ordem de compra do cliente, quando o pedido nasceu de uma.
itemsarray
Linhas do pedido.
items[].iduuid
Id da linha. item_id repete o valor.
items[].product_iduuid
Produto do catálogo.
items[].variation_iduuid
Variação do produto, quando existe.
items[].product_namestring
Nome no momento da compra.
items[].product_skustring
SKU no momento da compra.
items[].eanstring
Código de barras do cadastro, quando existe.
items[].optionsobject
Opções escolhidas na compra (cor, tamanho...).
items[].unit_priceinteger
Preço unitário em centavos.
items[].quantitynumber
Quantidade. Pode ter até 3 casas decimais em produtos vendidos por peso ou medida. amount é a mesma quantidade arredondada.
items[].discountinteger
Desconto da linha em centavos.
items[].taxinteger
Imposto da linha em centavos.
items[].totalinteger
Total da linha em centavos, já com o desconto.
items[].notestring
Observação do cliente para a linha ("sem cebola").
addressesarray
Endereço de cobrança (address_type: "billing") e de entrega ("shipping"). Cada um traz first_name, last_name, address_line1, address_line2, district, complement, city, state, postal_code, country, phone e cpf.
status_historyarray
Cada mudança de status do pedido, da mais antiga para a mais recente. Veja Histórico do pedido.
sub_ordersarray
Sub-pedidos, com os itens de cada um. Só aparece em pedido pai.
order_dataarray
Registros auxiliares: id, order_id, data_type, data_key, data_value (JSON livre) e created_at. O conteúdo depende dos módulos ativos na loja; não conte com chaves específicas além das que você mesmo gravou.

Erros

StatusQuandoCorpo
400Id vazio ou inválido no caminho{"error":"invalid id parameter"}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem o privilégio view_orders/manage_orders{"error":"insufficient privileges","privilege_required_any":["manage_orders","view_orders"]}
404O pedido não existe (ou o id não é válido){"error":"order not found"}
Dinheiro e datas

O valor de um pedido de R$ 225,00 vem como "total": 22500 (inteiro em centavos), e a data de criação como "created_at": "2026-10-11T02:56:25Z" (RFC 3339, em UTC). Os campos *_str (decimal em string) e timestamp (Unix, em segundos) repetem os mesmos valores em outros formatos, para quem prefere não converter; os campos oficiais são os inteiros em centavos e as datas RFC 3339.

Veja também

  • Listar pedidos
  • Sub-pedidos
  • Histórico do pedido
  • Fatura e NF-e
Anterior
Listar pedidos
Próxima
Criar pedido
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também