# 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

## Security:

  - `BearerAuth` (unknown)
    http bearer JWT

## Query parameters:

  - `pagina` (integer)
    Página

  - `tamanho_pagina` (integer)
    Tamanho da página. O parâmetro tamanho_pagina aceita somente os valores definidos no enum. Se um valor fora dessa lista for informado, a requisição não é processada e a API retorna 400 Bad Request, com a mensagem indicando quais valores são válidos.

  - `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)

  - `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)

  - `termo_busca` (string)

  - `data_inicio` (string)
    Data de início da emissão da venda

  - `data_fim` (string)
    Data final da emissão da venda

  - `data_criacao_de` (string)
    Data de início da criação da venda

  - `data_criacao_ate` (string)
    Data final da criação da venda

  - `data_alteracao_de` (string)
    Data de alteração de (ISO 8601, São Paulo/GMT-3)

  - `data_alteracao_ate` (string)
    Data de alteração até (ISO 8601, São Paulo/GMT-3)

  - `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:

  - `200` (unknown)
    OK

## 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:

  - `400` (unknown)
    Bad Request

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 429:

  - `429` (unknown)
    Too Many Requests

## Response 500:

  - `500` (unknown)
    Internal Server Error