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

Listar pedidos

Retorna os pedidos da loja, do mais novo para o mais antigo, com filtros e paginação.

Use esta operação para varrer os pedidos da loja: um ERP que busca os pedidos novos a cada poucos minutos, um painel de BI, ou uma tela de busca. A lista traz o resumo de cada pedido (totais, status, cliente, pagamento). Para ver itens, endereços e histórico, abra o pedido com Consultar pedido.

A lista inclui pedidos pai e sub-pedidos no mesmo vetor. Em uma compra com produtos de mais de um seller (lojista), a plataforma cria um pedido pai e um sub-pedido por seller (o pai traz is_parent_order e os filhos apontam para ele em parent_order_id). Para ignorar os sub-pedidos, descarte os itens que têm pai (parent_order_id não vazio).

GET/api/v1.0/ordersAdmin

Listar pedidos

A lista é sempre ordenada da criação mais recente para a mais antiga; não há parâmetro de ordenação nesta API. Autenticação: HTTP Basic com e-mail:chave_de_api de um usuário administrador, ou Authorization: Bearer <JWT>. A rota também responde em /api/orders (sem /v1.0); nessa forma os ids saem como números decimais em string (veja a home da seção).

Parâmetros de consulta

pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.
items_per_pageintegerpadrão: 10
Itens por página. Aceita de 1 a 100. Valores acima de 100 não são limitados a 100: voltam ao padrão da plataforma (20). 0 ou texto são ignorados e valem 10.
statusstring
Filtra por status. Mande a letra (O, P, S, C, I, R...). Nomes longos passam por uma tabela antiga e podem filtrar outro status (por exemplo shipped vira P e refunded vira D). Um valor desconhecido com mais de um caractere é cortado na primeira letra.
user_idstring
Somente pedidos deste cliente (UUID; na rota /api/orders, o id decimal).
company_idstring
Somente pedidos deste seller (UUID; na rota /api/orders, o id decimal).
order_idstring
Busca por texto no número do pedido, e-mail e nome do cliente. Não é igualdade por id: passar o UUID de um pedido não o encontra. Para buscar um pedido pelo id use Consultar pedido.
periodstring
todaythis_weekthis_monthlast_monththis_yearlast_year
Atalho de período, calculado no fuso do servidor. Outro valor é ignorado.
time_frominteger
Início do período em Unix timestamp (segundos). Só o dia (no fuso do servidor) conta: o horário é descartado. Sobrescreve period.
time_tointeger
Fim do período em Unix timestamp (segundos). O dia informado entra por inteiro. Sobrescreve period.

Exemplo de requisição

bash
curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/orders?status=O&items_per_page=50&time_from=1791676800"

Resposta

200Pedidos retornados
json
{
  "orders": [
    {
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "is_parent_order": "N",
      "parent_order_id": "",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "total": "225.00",
      "subtotal": "300.00",
      "discount": "75.00",
      "shipping_cost": "0.00",
      "tax_subtotal": "0.00",
      "payment_tax": "0.00",
      "shipping_tax": "0.00",
      "status": "P",
      "timestamp": 1791687385,
      "order_number": "PEDIDO-20261010-0004",
      "email": "maria.souza@example.com",
      "ip_address": "203.0.113.10",
      "currency": "BRL",
      "lang_code": "pt-BR",
      "shipping_id": "50000000-0000-0000-0000-000000000003",
      "shipping_method_name": "Frete Grátis acima de R$199",
      "payment_method_name": "PIX",
      "payment_method": { "payment": "pix", "payment_id": "pix" },
      "notes": "",
      "coupon_codes": [],
      "promotion_ids": [],
      "suborder_ids": []
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 2310 }
}

Campos da resposta

ordersarray
Pedidos da página. Cada item é o resumo do pedido, sem products, shipping, user_data e payment_info (esses só vêm em Consultar pedido).
orders[].order_idstring
Id do pedido. UUID em /api/v1.0; decimal em string em /api/.
orders[].is_parent_orderstring
YN
Na lista é sempre N, mesmo para um pedido pai. Para saber se um pedido tem sub-pedidos, consulte-o individualmente.
orders[].parent_order_idstring
Id do pedido pai quando este é um sub-pedido. Vazio nos demais.
orders[].user_idstring
Id do cliente. Vazio em pedido de visitante.
orders[].company_idstring
Id do seller dono do pedido. Vazio quando o pedido é da loja (marketplace) ou é um pedido pai.
orders[].totalstring
Total do pedido em string decimal com ponto ("225.00" = R$ 225,00).
orders[].subtotalstring
Soma dos itens, string decimal.
orders[].discountstring
Descontos, string decimal.
orders[].shipping_coststring
Frete, string decimal.
orders[].tax_subtotalstring
Impostos, string decimal.
orders[].payment_taxstring
Sempre "0.00" (campo mantido por compatibilidade).
orders[].shipping_taxstring
Sempre "0.00" (campo mantido por compatibilidade).
orders[].statusstring
Letra de status guardada no pedido. Cada loja pode ter o seu alfabeto; consulte tabela de status da home da seção.
orders[].timestampinteger
Data de criação em Unix timestamp (segundos, UTC).
orders[].order_numberstring
Número do pedido mostrado ao cliente. Sub-pedidos usam o número do pai mais -V1, -V2...
orders[].emailstring
E-mail do cliente.
orders[].ip_addressstring
IP de quem fez o pedido. Vazio quando não foi registrado.
orders[].currencystring
Moeda ISO 4217 (BRL).
orders[].lang_codestring
Sempre pt-BR.
orders[].shipping_idstring
Id da forma de envio escolhida. Vazio se não houver.
orders[].shipping_method_namestring
Nome da forma de envio no momento da compra.
orders[].payment_method_namestring
Nome da forma de pagamento.
orders[].payment_methodobject
payment e payment_id, ambos com o código (slug) da forma de pagamento.
orders[].notesstring
Observação do cliente no pedido.
orders[].coupon_codesarray
Sempre [] na lista; os cupons aparecem em Consultar pedido.
orders[].promotion_idsarray
Sempre [] na lista.
orders[].suborder_idsarray
Sempre [] na lista.
orders[].marketplace_originstring
ST
Só aparece em pedido vindo de marketplace externo: S Shopee, T TikTok.
orders[].marketplace_order_idstring
Número do pedido no marketplace externo, quando existe.
paramsobject
Paginação: page, items_per_page e total_items (total de pedidos que atendem ao filtro, todas as páginas).
GET/api/v1.0/users/{id}/ordersAdmin

Pedidos de um cliente

Atalho para os pedidos de um cliente. Equivale a /api/v1.0/orders?user_id={id}, mas só aceita paginação e não filtra por status nem por data. Devolve o mesmo envelope orders + params, ordenado do mais novo para o mais antigo.

Parâmetros de caminho

idstringobrigatório
Id do cliente (UUID; na rota /api/users/{id}/orders, o id decimal).

Parâmetros de consulta

pageintegerpadrão: 1
Página.
items_per_pageintegerpadrão: 10
Itens por página, de 1 a 100. Acima de 100 volta ao padrão da plataforma (20).

Erros

StatusQuandoCorpo
400(rota /api/orders) user_id ou company_id em formato de id inválido{"message":"Invalid id","status":400}
401Sem credenciais ou chave de API inválida{"message":"Invalid credentials","status":401}
403Usuário que não é administrador{"message":"Forbidden: admin scope required","status":403}
404(rota /api/orders) user_id, company_id ou {id} decimal que não corresponde a nenhum registro{"message":"Not found","status":404}
Como sincronizar com um ERP

Guarde o maior timestamp já processado e, a cada ciclo, chame time_from com esse valor. Como o filtro tem granularidade de dia, o mesmo pedido pode voltar em ciclos seguidos: use o id do pedido para descartar repetidos. A lista vem do mais novo para o mais antigo; para processar na ordem de chegada, percorra as páginas de trás para a frente.

Veja também

  • Consultar pedido
  • Alterar o status
Anterior
Pedidos
Próxima
Consultar pedido
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também