Visão Geral
Filtros e includes disponíveis para consulta dos pedidos em /orders
Introdução
Esta página documenta os filtros e os includes disponíveis para as rotas GET /orders.
Esses parâmetros permitem que você refine suas consultas e enriqueça a resposta da API com dados relacionados, otimizando o consumo e reduzindo a quantidade de requisições necessárias.
Você encontrará aqui:
- Descrição de cada filtro suportado (por status, canal, UTM, afiliado, produto etc).
- Parâmetros
includedisponíveis para expandir a resposta com entidades relacionadas (cliente, itens, transações, status etc). - Exemplos práticos de uso combinando filtros e includes.
Esta página é uma introdução às páginas de documentação de consulta no endpoint de pedidos e documentação de consulta em um pedido específico focando exclusivamente na qualidade das requisições.
Dica: Você também pode consultar os IDs, valores disponíveis para filtros como
affiliation_id,product_id,status_id, entre outros, acessando diretamente o endpoint de filtros:
Esse endpoint retorna a estrutura completa de filtros, incluindo rótulos, valores disponíveis e parâmetros, permitindo que você construa consultas dinâmicas e com mais precisão.
Filtros disponíveis para a consulta geral de pedidos (/orders)
| Parâmetro | Tipo | Descrição |
|---|---|---|
affiliation_id[] | array | Afiliações ou gateways associados ao pedido (ex: Appmax, PagSeguro) |
bling | string | Indica se o pedido foi enviado ao Bling (sent ou not_sent) |
freebie_id[] | array | Brindes associados ao pedido |
utm_campaign[] | array | Nome da campanha de marketing (UTM Campaign) |
channel | string | Canal de venda (store, payment_retry) |
promocode_id[] | array | Cupons de desconto aplicados |
date=updated_at | date | Data da última atualização do pedido Ex: ?date=updated_at:2024-06-01|2024-06-30 ou ?date=updated_at:2024-06-30 |
date=cancelled_at | date | Data de cancelamento do pedido Ex: ?date=cancelled_at:2024-06-01|2024-06-30 |
date=created_at | date | Data de criação do pedido Ex: ?date=created_at:2024-06-30|2025-06-30 ou ?date=created_at:2024-06-30 |
date=captured_at | date | Data de pagamento (captura) do pedido Ex: ?date=captured_at:2024-06-01|2024-06-30 |
shipping_date | date | Data de previsão de entrega Ex: ?date=shipping_date:2024-07-01 |
stock_id | int | ID do estoque de origem do pedido |
shipment_service[] | array | Forma de entrega utilizada (ex: Correios, transportadora, retirada) |
payment_method[] | array | Meio de pagamento (ex: pix, billet, credit_card) |
order_bump_id[] | array | Order Bumps adicionados ao pedido |
utm_source[] | array | Origem da campanha (UTM Source) |
product_id[] | array | IDs dos produtos incluídos no pedido |
status_id[] | array | Status atual do pedido (ex: pago, cancelado, entregue, em transporte) |
upsell_id[] | array | Upsells adquiridos após o checkout |
marketplace_accounts[] | array | Lista de IDs de contas de marketplaces conectadas (ex: Mercado Livre). |
q | string | Termo de busca genérico Ex: ?q=termoquebusca |
number | int | Número exato do pedido. |
sync_by_erp | bolean | Indica se o pedido foi sincronizado com ERP (bling, tiny etc). |
gateway_id[] | array | Filtra por gateway específico de pagamento (ex: Appmax, Pagar.me, etc.). |
Notas sobre o uso de datas
- Para buscar pedidos em um intervalo de datas, use:
- Para buscar pedidos de uma única data, use:
Includes disponíveis para nas rotas de pedidos (/orders e /orders{id})
Use o parâmetro include para retornar dados relacionados no mesmo payload da resposta.
Você pode incluir múltiplos valores separados por vírgula, por exemplo:
?include=customer,items,status
| Include | Descrição |
|---|---|
items | Lista de itens do pedido |
customer | Dados completos do cliente |
marketplace | Informações do marketplace, se aplicável |
status | Status atual do pedido |
statuses | Histórico de status do pedido |
shipping_address | Endereço de entrega |
promocode | Cupom de desconto aplicado |
transactions | Transações financeiras vinculadas |
comments | Comentários internos ou visíveis |
files | Arquivos anexados ao pedido |
discounts | Descontos aplicados |
seller | Dados do vendedor (em contexto de marketplace) |
labels | Etiquetas associadas ao pedido |