# Retornar as vendas por filtro

Retorna as vendas filtradas, podendo fazer uso de parâmetros de consulta como data inicial/final, cliente, situação, tipos de venda, IDs de produtos, IDs de categorias, paginação, entre outros. Use esse endpoint para construir telas de listagem, dashboards ou relatórios de vendas.

Endpoint: GET /v1/venda/busca
Version: v1
Security: BearerAuth

## Query parameters:

  - `pagina` (integer)
    Página
    Example: 1

  - `tamanho_pagina` (integer)
    Tamanho da página
    Enum: 10, 20, 50, 100, 200, 500, 1000

  - `campo_ordenado_ascendente` (string)
    Campo para ordenação ascendente. Se informado ele desconsidera o valor do  campo_ordenado_descendente. É possível ordenar por numero da venda (NUMERO),  pelo nome do cliente (CLIENTE) ou pela data da venda (DATA)
    Enum: "NUMERO", "CLIENTE", "DATA"

  - `campo_ordenado_descendente` (string)
    Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente  não deverá ser informado. É possível ordenar por numero da venda (NUMERO), pelo nome do  cliente (CLIENTE) ou pela data da venda (DATA)
    Enum: same as `campo_ordenado_ascendente` (3 values)

  - `termo_busca` (string)
    Termo para busca das vendas por nome, email do cliente ou número da venda

  - `data_inicio` (string)
    Data de início da emissão da venda
    Example: "2023-12-30"

  - `data_fim` (string)
    Data final da emissão da venda
    Example: "2023-12-30"

  - `data_criacao_de` (string)
    Data de início da criação da venda
    Example: "2023-12-30"

  - `data_criacao_ate` (string)
    Data final da criação da venda
    Example: "2023-12-31"

  - `data_alteracao_de` (string)
    Data de alteração de (ISO 8601, São Paulo/GMT-3)
    Example: "2025-10-20T07:59:59"

  - `data_alteracao_ate` (string)
    Data de alteração até (ISO 8601, São Paulo/GMT-3)
    Example: "2025-10-29T07:59:59"

  - `ids_vendedores` (array)
    ids dos vendedores

  - `ids_clientes` (array)
    ids dos clientes

  - `ids_natureza_operacao` (array)
    ids da natureza da operação

  - `situacoes` (array)
    Situações das vendas

  - `tipos` (array)
    Tipos de vendas

  - `origens` (array)
    Origens das vendas

  - `numeros` (array)
    Números das vendas

  - `ids_categorias` (array)
    ids das categorias

  - `ids_produtos` (array)
    ids dos produtos

  - `pendente` (boolean)
    Indica se a venda está pendente

  - `totais` (string)
    Tipo de total de venda. Possiveis valores WAITING_APPROVED, APPROVED, CANCELED, ALL

  - `ids_legado_donos` (array)
    ids legados dos donos

  - `ids_legado_clientes` (array)
    ids legados dos clientes

  - `ids_legado_produtos` (array)
    ids legados dos produtos

  - `ids_legado_categorias` (array)
    ids legados das categorias

## Response 200 fields (application/json):

  - `totais` (object)
    Valores das de vendas com status Aprovado, Cancelado, Esperando aprovação e Total

  - `totais.total` (number)
    Valor total obtido de todas as vendas
    Example: 1000

  - `totais.aprovado` (number)
    Valor obtido das vendas aprovadas
    Example: 500

  - `totais.cancelado` (number)
    Valor obtido das vendas canceladas
    Example: 200

  - `totais.esperando_aprovacao` (number)
    Valor obtido das vendas esperando aprovação
    Example: 300

  - `quantidades` (object)
    Quantidades de vendas com status Aprovado, Cancelado, Esperando aprovação e Total

  - `quantidades.total` (number)
    Quantidade total de vendas realizadas
    Example: 10

  - `quantidades.aprovado` (number)
    Quantidade de vendas aprovadas
    Example: 5

  - `quantidades.cancelado` (number)
    Quantidade de vendas canceladas
    Example: 3

  - `quantidades.esperando_aprovacao` (number)
    Quantidade de vendas esperando aprovação
    Example: 2

  - `total_itens` (integer)
    Total de itens
    Example: 10

  - `itens` (array)

  - `itens.id` (string)
    id da venda
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `itens.total` (number)
    Total da venda
    Example: 1000

  - `itens.id_legado` (integer)
    id legado da venda
    Example: 123456

  - `itens.data` (string)
    Data da venda
    Example: "2023-12-31"

  - `itens.criado_em` (any)
    Data de criação da venda
    Example: "2025-05-16T17:51:04.63"

  - `itens.data_alteracao` (string)
    Data de alteração da venda (ISO 8601, São Paulo/GMT-3)
    Example: "2025-10-17T02:00:08.841"

  - `itens.tipo` (string)
    Tipo da venda
    Example: "PRODUTO"

  - `itens.itens` (string)
    Tipo de itens
    Example: "PRODUTO"

  - `itens.condicao_pagamento` (boolean)
    Condição de pagamento
    Example: true

  - `itens.numero` (integer)
    Número da venda
    Example: 1001

  - `itens.cliente` (object)

  - `itens.cliente.id` (string)
    id do cliente
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `itens.cliente.nome` (string)
    Nome do cliente
    Example: "João da Silva"

  - `itens.cliente.email` (string)
    Email do cliente
    Example: "exemplo@email.com"

  - `itens.cliente.telefone` (string)
    Telefone do cliente
    Example: "11912345678"

  - `itens.cliente.endereco` (string)
    Endereço do cliente
    Example: "Rua das Flores, 123"

  - `itens.cliente.cidade` (string)
    Cidade do cliente
    Example: "São Paulo"

  - `itens.cliente.estado` (string)
    Estado do cliente
    Example: "SP"

  - `itens.cliente.pais` (string)
    País do cliente
    Example: "Brasil"

  - `itens.cliente.cep` (string)
    CEP do cliente
    Example: "12345-678"

  - `itens.situacao` (object)

  - `itens.situacao.nome` (string)
    Nome da situação
    Example: "Aprovado"

  - `itens.situacao.descricao` (string)
    Descrição da situação
    Example: "Venda aprovada e processada"

  - `itens.versao` (integer)
    Versão da venda
    Example: 1

  - `itens.status_email` (object)

  - `itens.status_email.status` (string)
    Status
    Example: "ENVIADO"

  - `itens.status_email.enviado_em` (string)
    Data de envio
    Example: "2023-12-31"

  - `itens.id_contrato` (string)
    id do contrato
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `itens.origem` (string)
    Origem da venda
    Example: "API"


## Response 400 fields

## Response 401 fields

## Response 429 fields

## Response 500 fields