VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/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.

O pedido volta "achatado", no formato da Venddor 1.0 (products, user_data, payment_info), com valores em string decimal e data em Unix timestamp.

GET/api/v1.0/orders/{id}Admin

Consultar um pedido

Autenticação: HTTP Basic (e-mail:chave_de_api) de um administrador, ou Authorization: Bearer <JWT>. Também responde em /api/orders/{id}; nessa forma o {id} e todos os ids da resposta são decimais em string. O {id} aceita ainda o UUID.

Parâmetros de caminho

idstringobrigatório
Id do pedido (UUID em /api/v1.0; decimal em string em /api/).
GET/api/v1.0/orders/{id}/productsAdmin

Produtos (itens) de um pedido

Devolve só as linhas do pedido, no mesmo formato de products do detalhe. É o atalho que conectores de ERP e de marketplace usam para ler os itens sem baixar o pedido inteiro.

Parâmetros de caminho

idstringobrigatório
Id do pedido.

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/orders/$ORDER_ID"

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/orders/$ORDER_ID/products"

Resposta

200Pedido retornado
json
{
  "order_id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
  "is_parent_order": "Y",
  "parent_order_id": "",
  "user_id": "",
  "company_id": "",
  "total": "1928.95",
  "subtotal": "1908.95",
  "discount": "0.00",
  "shipping_cost": "20.00",
  "tax_subtotal": "0.00",
  "payment_tax": "0.00",
  "shipping_tax": "0.00",
  "status": "O",
  "timestamp": 1791749680,
  "order_number": "PEDIDO-20261011-0001",
  "email": "maria.souza@example.com",
  "phone": "11999990000",
  "ip_address": "203.0.113.10",
  "currency": "BRL",
  "lang_code": "pt-BR",
  "shipping_id": "50000000-0000-0000-0000-000000000001",
  "shipping_method_name": "Entrega Padrão",
  "payment_method_name": "Pagamento na Entrega (COD)",
  "payment_method": { "payment": "pagamento-na-entrega", "payment_id": "pagamento-na-entrega" },
  "products": [
    {
      "item_id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4",
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "product_code": "SD-004018-C",
      "product": "Notebook Vintage Vermelho",
      "price": "1678.95",
      "amount": 1,
      "discount": "0.00",
      "subtotal": "1678.95",
      "total": "1678.95"
    },
    {
      "item_id": "bc30e5de-b012-4bb8-a46c-628a932e6fd4",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_code": "SD-002373",
      "product": "Notebook Slim Rosa",
      "price": "115.00",
      "amount": 2,
      "discount": "0.00",
      "subtotal": "230.00",
      "total": "230.00"
    }
  ],
  "shipping": [
    { "shipping_id": "Entrega Padrão", "shipping": "Entrega Padrão", "rate": "20.00" }
  ],
  "payment_info": { "payment_method": "pagamento-na-entrega", "payment_status": "pending" },
  "user_data": {
    "firstname": "Maria",
    "lastname": "Souza",
    "email": "maria.souza@example.com",
    "phone": "11999990000",
    "b_firstname": "Maria",
    "b_lastname": "Souza",
    "b_address": "Avenida Paulista, 1000",
    "b_city": "São Paulo",
    "b_state": "SP",
    "b_zipcode": "01310-100",
    "b_country": "BR",
    "b_phone": "11999990000",
    "s_firstname": "Maria",
    "s_lastname": "Souza",
    "s_address": "Avenida Paulista, 1000",
    "s_city": "São Paulo",
    "s_state": "SP",
    "s_zipcode": "01310-100",
    "s_country": "BR",
    "s_phone": "11999990000"
  },
  "notes": "",
  "coupon_codes": [],
  "promotion_ids": [],
  "suborder_ids": [
    "2b4bd680-b717-4295-a2be-8b5c6771a4d0",
    "0932405c-a8c1-49b3-a7db-61aab4c4d666"
  ]
}
200Itens do pedido (/products)
json
{
  "products": [
    {
      "item_id": "bc30e5de-b012-4bb8-a46c-628a932e6fd4",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_code": "SD-002373",
      "product": "Notebook Slim Rosa",
      "price": "115.00",
      "amount": 2,
      "discount": "0.00",
      "subtotal": "230.00",
      "total": "230.00"
    }
  ]
}

Campos da resposta (além dos da lista)

is_parent_orderstring
YN
Y quando o pedido foi dividido em sub-pedidos por seller. Aqui (diferente da lista) o valor é correto.
phonestring
Telefone do cliente, tirado do endereço de cobrança (ou de entrega). Pode vir ausente.
productsarray
Linhas do pedido. Vazio em um pedido sem itens.
products[].item_idstring
Id da linha do pedido. É o id da linha dentro do pedido.
products[].product_idstring
Id do produto no catálogo.
products[].product_codestring
SKU (código do produto) no momento da compra. Vazio se o produto não tem SKU.
products[].productstring
Nome do produto no momento da compra.
products[].pricestring
Preço unitário, string decimal.
products[].amountinteger
Quantidade, arredondada para inteiro. Produtos vendidos por fração (por exemplo 1,5 kg) aparecem arredondados aqui.
products[].discountstring
Desconto da linha, string decimal.
products[].subtotalstring
Preço × quantidade, antes do desconto.
products[].totalstring
Total da linha, já com o desconto.
products[].product_optionsarray
Opções escolhidas (cor, tamanho), cada uma com option_id, option_name, variant_id e variant_name. Só aparece quando há opções.
shippingarray
Forma de envio: shipping_id, shipping (nome), rate (valor, string decimal) e, quando existe, tracking_number. Ausente se o pedido não tem envio nem rastreio.
payment_infoobject
payment_method, payment_status (pending, authorized, captured, refunded, failed) e, quando existe, transaction_id (identificador do pagamento no gateway).
user_dataobject
Cliente e endereços. Campos com prefixo b_ são de cobrança e com prefixo s_ são de entrega: firstname, lastname, address, city, state (UF), zipcode (CEP), country, phone.
coupon_codesarray
Códigos de cupom aplicados, quando houve.
promotion_idsarray
Ids das promoções aplicadas, quando houve.
suborder_idsarray
Ids dos sub-pedidos, quando is_parent_order é Y.
orderSAPstring
Referência do pedido no ERP, gravada por Sincronização com ERP. Só aparece quando existe.

Erros

StatusQuandoCorpo
400Id 0 ou vazio no caminho{"error":"invalid id parameter"}
401Sem credenciais, chave inválida ou token expirado{"message":"Invalid credentials","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
404O pedido não existe (ou o id não é válido){"message":"Order not found","status":404}
500(/products) pedido que não existe{"error":"internal server error"}
/products responde 500 para pedido inexistente

Na API 1.0, o detalhe (/orders/{id}) responde 404 quando o pedido não existe, mas /orders/{id}/products (e /status-history, /refund) respondem 500 nessa situação. Trate 500 nessas rotas como "pedido não encontrado" quando o id vier de uma fonte não confiável.

Veja também

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