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 (veja Sub-pedidos). Para ignorar os sub-pedidos, descarte os itens que têm pai (parent_id não nulo).

GET/api/v1/admin/ordersAdmin

Lista os pedidos

Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio view_orders ou manage_orders. O token vem de POST /api/v1/auth/login (o login tem limite de requisições: guarde o token em vez de logar a cada chamada).

Query parameters

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Valor fora desse intervalo volta ao padrão (20), não é limitado.

sort_bystringpadrão: created_at

created_attotalorder_numberstatuscustomer_namecustomer_email

Campo de ordenação. Outro valor cai em created_at.

sort_dirstringpadrão: desc

ascdesc

Direção da ordenação.

statusstring

Status do pedido, pelo código (pending, processing, shipped...) ou pela letra (O, P, S...) do cadastro de status da loja. Status que não existe no cadastro devolve lista vazia.

payment_statusstring

pendingauthorizedcapturedpaidrefundedfailed

Situação do pagamento. paid é aceito como sinônimo de captured.

payment_methodstring

Código da forma de pagamento (pix, credit_card, boleto...), sem diferenciar maiúsculas.

customer_iduuid

Somente pedidos deste cliente. UUID inválido causa erro 500.

vendor_iduuid

Somente pedidos deste seller. UUID inválido causa erro 500.

date_fromstring

Data inicial, YYYY-MM-DD ou RFC 3339. Inclusive.

date_tostring

Data final. Com YYYY-MM-DD o dia inteiro entra; com horário, o limite é inclusivo.

min_totalinteger

Total mínimo em centavos.

max_totalinteger

Total máximo em centavos.

searchstring

Texto livre: número do pedido, e-mail, nome do cliente, CPF/CNPJ (quando o texto parece um documento) e número da ordem de compra.

product_searchstring

Pedidos que têm um item com este nome ou SKU.

cpfstring

CPF do comprador, com ou sem pontuação.

cnpjstring

CNPJ do comprador (ou da empresa matriz), com ou sem pontuação.

shipping_method_iduuid

Pedidos com esta forma de envio.

assigned_tostring

Id do usuário responsável pelo pedido. Enviado vazio (assigned_to=), traz os pedidos sem responsável.

state_codestring

UF do endereço de entrega (SP), igualdade exata.

city_namestring

Cidade de entrega (contém o texto).

district_namestring

Bairro de entrega (contém o texto).

postal_codestring

CEP de entrega (contém o texto).

country_codestring

País de entrega (BR), igualdade exata.

has_document_typestring

Pedidos que têm anexo deste tipo (id do tipo ou chave, como nota_fiscal). Exige o recurso de documentos do pedido.

missing_document_typestring

Pedidos que não têm anexo deste tipo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/orders?status=processing&date_from=2026-10-01&per_page=50&sort_by=total&sort_dir=desc" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedidos retornados

json

{
  "orders": [
    {
      "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_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",
      "customer_notes": "",
      "ip_address": "203.0.113.10",
      "is_guest": false,
      "buyer_phone": "11999990000",
      "buyer_cpf": "123.456.789-09",
      "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",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "company_name": "Loja Seller Teste",
      "total_str": "225.00",
      "subtotal_str": "300.00",
      "shipping_cost_str": "0.00",
      "tax_subtotal_str": "0.00",
      "discount_str": "75.00",
      "payment": "pix",
      "timestamp": 1791687385,
      "firstname": "Maria",
      "lastname": "Souza",
      "email": "maria.souza@example.com"
    }
  ],
  "total": 2310,
  "page": 1,
  "per_page": 20,
  "total_pages": 116
}

Campos da resposta

ordersarray

Pedidos da página, do mais novo para o mais antigo (padrão).

orders[].iduuid

Id do pedido. Os campos order_id repetem o mesmo valor.

orders[].order_numberstring

Número mostrado ao cliente. Sub-pedidos terminam em -V1, -V2...

orders[].parent_iduuid

Só aparece em sub-pedido: id do pedido pai.

orders[].vendor_iduuid

Seller dono do pedido. Ausente quando o pedido é da loja ou é um pedido pai.

orders[].customer_iduuid

Cliente. Vazio em pedido de visitante (is_guest: true).

orders[].subtotalinteger

Soma dos itens, em centavos (30000 = R$ 300,00).

orders[].shipping_totalinteger

Frete em centavos.

orders[].tax_totalinteger

Impostos em centavos.

orders[].discount_totalinteger

Descontos em centavos.

orders[].totalinteger

Total cobrado, em centavos.

orders[].statusstring

Letra de status (O, P...). Veja os códigos na home da seção.

orders[].status_textstring

Código longo do status (pending, processing...), ou o código próprio da loja para status personalizados.

orders[].payment_statusstring

pendingauthorizedcapturedrefundedfailed

Situação do pagamento.

orders[].sales_channelstring

Canal de origem (web, pos, whatsapp...).

orders[].created_atstring

Criação, RFC 3339 em UTC.

orders[].updated_atstring

Última alteração, RFC 3339 em UTC.

orders[].buyer_phonestring

Telefone do endereço de entrega (ou cobrança).

orders[].buyer_cpfstring

CPF do endereço de entrega (ou cobrança).

orders[].total_strstring

Total em string decimal ("225.00"), para quem prefere não converter centavos. O mesmo vale para subtotal_str, shipping_cost_str, tax_subtotal_str e discount_str.

orders[].timestampinteger

Criação em Unix timestamp (segundos), a mesma data de created_at.

totalinteger

Total de pedidos que atendem ao filtro, em todas as páginas.

pageinteger

Página retornada.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `view_orders`/`manage_orders`	`{"error":"insufficient privileges","privilege_required_any":["manage_orders","view_orders"]}`
429	Limite de requisições (por exemplo, login repetido)	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna, ou UUID inválido em `customer_id`/`vendor_id`, ou data inválida em `date_from`/`date_to`	`{"error":"failed to list orders","detail":"o valor \"garbage\" não é um timestamp with time zone válido. Corrija o campo e reenvie."}`

Veja também