Busca avançada

A busca avançada filtra e ordena listagens com critérios enviados no corpo de uma requisição POST. Esta página mostra a estrutura dos filtros e das ordenações, os operadores aceitos, como descobrir os campos disponíveis e como tratar os erros. A busca avançada está disponível em três endpoints:

POST /api/management/projects/search
POST /api/management/customers/search
POST /api/management/contacts/search

Para filtros simples enviados na URL, como filter[status]=active, veja Filtros básicos.

Primeira busca

Esta requisição completa, com autenticação, busca os projetos com orçamento maior que 10.000:

curl -X POST "https://api.olie.ai/api/management/projects/search" \
  -H "Authorization: Bearer {{token_de_acesso}}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "budget", "operator": "greater_than", "value": 10000 }
    ]
  }'

A resposta traz a lista em projects e os dados de paginação em meta, como descrito em Paginação.

Estrutura da requisição

O corpo da requisição é um objeto JSON com quatro campos, todos opcionais:

array

Lista de filtros. Cada filtro define o campo, o operador, o valor e como ele se combina com o filtro anterior.

array

Lista de ordenações, na ordem de prioridade. Cada ordenação define o campo e a direção.

integer

default:"1"

Número da página, a partir de 1. Veja Paginação.

integer

default:"30"

Quantidade de itens por página, de 1 a 100. Veja Paginação.

Estrutura de um filtro

Cada item de filters tem estes campos:

string

required

Nome do campo a filtrar. Os campos aceitos variam por endpoint: veja Descobrindo campos disponíveis.

string

required

Operador de comparação. Os valores aceitos estão em Operadores de comparação.

string | number | boolean | array | null

Valor a comparar. O tipo depende do campo e do operador.

string

default:"and"

Como o filtro se combina com o anterior: and ou or.

array

Argumentos extras que alguns campos exigem, como o campo do formulário em um filtro por resposta de formulário. Veja Argumentos adicionais.

Operadores de comparação

O campo operator aceita os valores da tabela. Nem todo campo aceita todos os operadores: a lista de cada campo está em Descobrindo campos disponíveis.

Operador	Significado	Grupo
`equals`	Igual a	Igualdade
`not_equals`	Diferente de	Igualdade
`contains`	Contém o texto (busca parcial)	Texto
`not_contains`	Não contém o texto	Texto
`greater_than`	Maior que	Número e data
`greater_than_or_equals`	Maior ou igual a	Número e data
`less_than`	Menor que	Número e data
`less_than_or_equals`	Menor ou igual a	Número e data
`is_null`	Campo vazio (nulo)	Nulo
`is_not_null`	Campo preenchido (não nulo)	Nulo

Combinar filtros com and e or

O campo logical_operator define como cada filtro se combina com o anterior:

and (padrão): o item precisa atender aos dois filtros.
or: o item precisa atender a pelo menos um dos dois filtros.

O logical_operator vale a partir do segundo filtro. No primeiro filtro, a API ignora o valor.

Use o mesmo operador lógico em todos os filtros da busca, só and ou só or. Misturar os dois na mesma lista pode trazer resultados diferentes do esperado.

Estrutura de uma ordenação

Cada item de sorting tem estes campos:

string

required

Nome do campo usado na ordenação. Os campos aceitos variam por endpoint: veja Descobrindo campos disponíveis.

string

required

Direção da ordenação: asc (crescente) ou desc (decrescente).

array

Argumentos extras que algumas ordenações exigem.

Argumentos adicionais

Alguns campos só funcionam com um contexto a mais. Por exemplo, para filtrar projetos pela resposta de um formulário (campo answer_pool), você precisa dizer qual campo do formulário comparar. Esse contexto vai em arguments. Os argumentos de cada campo aparecem na resposta do endpoint de metadados, descrita em Descobrindo campos disponíveis. arguments é uma lista de objetos, e cada objeto tem três chaves obrigatórias:

Chave	O que enviar
`argument_key`	O `id` do argumento no endpoint de metadados, como `answer_pool_edge`
`argument_value_id`	O valor do argumento, como o id do campo do formulário
`argument_value_type`	O `modelClass` do argumento no endpoint de metadados, como `App\Models\FormEdge`

A API lê os argumentos pela posição na lista: o primeiro objeto é o primeiro argumento do campo, e assim por diante. Este filtro busca os projetos cuja resposta ao campo 30 do formulário é “Indicação”:

{
  "filters": [
    {
      "field": "answer_pool",
      "operator": "equals",
      "value": "Indicação",
      "arguments": [
        {
          "argument_key": "answer_pool_edge",
          "argument_value_id": 30,
          "argument_value_type": "App\\Models\\FormEdge"
        }
      ]
    }
  ]
}

Exemplos

Os exemplos usam a busca de projetos. Na busca de clientes e de contatos, a estrutura é a mesma e só mudam os campos.

Dois filtros com and
Dois filtros com or
Filtros, ordenação e paginação

Busca os projetos em andamento (status igual a 1) cujo nome contém “Implantação”:

POST /api/management/projects/search
Content-Type: application/json

{
  "filters": [
    { "field": "name", "operator": "contains", "value": "Implantação" },
    { "field": "status", "operator": "equals", "value": 1, "logical_operator": "and" }
  ]
}

Busca os projetos criados a partir de 1º de janeiro de 2026 ou com orçamento maior que 10.000:

POST /api/management/projects/search
Content-Type: application/json

{
  "filters": [
    { "field": "created_at", "operator": "greater_than_or_equals", "value": "2026-01-01" },
    { "field": "budget", "operator": "greater_than", "value": 10000, "logical_operator": "or" }
  ]
}

Busca os projetos em andamento com “Implantação” no nome e orçamento maior que 10.500, do mais recente para o mais antigo, 30 por página:

POST /api/management/projects/search
Content-Type: application/json

{
  "filters": [
    { "field": "name", "operator": "contains", "value": "Implantação" },
    { "field": "status", "operator": "equals", "value": 1, "logical_operator": "and" },
    { "field": "budget", "operator": "greater_than", "value": 10500, "logical_operator": "and" }
  ],
  "sorting": [
    { "field": "created_at", "direction": "desc" }
  ],
  "page": 1,
  "perPage": 30
}

Filtrar por data de criação

O campo created_at filtra pela data de criação nas três buscas: projetos, clientes e contatos. Ele aceita os operadores equals, not_equals, greater_than, greater_than_or_equals, less_than e less_than_or_equals. Envie só a data, no formato AAAA-MM-DD, como 2026-09-30. A API lê a data no fuso de Brasília (America/Sao_Paulo) e a trata como o dia inteiro:

Operador	Com `2026-09-30`, traz o que foi criado…
`equals`	em qualquer horário de 30/09
`not_equals`	em qualquer dia, menos 30/09
`greater_than_or_equals`	a partir de 30/09 às 00:00, incluindo a madrugada
`greater_than`	a partir de 01/10
`less_than_or_equals`	até o fim de 30/09
`less_than`	até o fim de 29/09

Para buscar um mês inteiro, combine greater_than_or_equals com o primeiro dia e less_than_or_equals com o último. Esta busca traz os projetos criados em setembro de 2026:

{
  "filters": [
    { "field": "created_at", "operator": "greater_than_or_equals", "value": "2026-09-01" },
    { "field": "created_at", "operator": "less_than_or_equals", "value": "2026-09-30", "logical_operator": "and" }
  ]
}

O valor também pode ser data e hora no formato ISO 8601, com ou sem fuso, como 2026-09-30T14:00:00-03:00. A API converte para o fuso de Brasília. Se o resultado cair à meia-noite em ponto, vale a regra do dia inteiro. Em qualquer outro horário, a comparação é exata com aquele momento.

Descobrindo campos disponíveis

Cada endpoint aceita um conjunto próprio de campos, operadores e argumentos. Para consultar esse conjunto, use o endpoint de metadados:

GET /api/management/system/params/{model_name}

Troque {model_name} pelo objeto da busca: project, customer ou contact. A resposta abaixo, da busca de projetos, mostra três dos filtros e parte das ordenações:

{
  "response": true,
  "params": {
    "filters": [
      {
        "name": "name",
        "input_type": "text",
        "operators": ["equals", "not_equals", "contains", "not_contains"],
        "options": [],
        "arguments": [],
        "hydrate": null
      },
      {
        "name": "status",
        "input_type": "text",
        "operators": ["equals", "not_equals"],
        "options": [
          { "label": "Em andamento", "value": 1 },
          { "label": "Concluído", "value": 2 },
          { "label": "Arquivado", "value": 3 },
          { "label": "Paralisado", "value": 4 }
        ],
        "arguments": [],
        "hydrate": null
      },
      {
        "name": "answer_pool",
        "input_type": "text",
        "operators": [
          "equals", "not_equals", "contains", "not_contains",
          "greater_than", "greater_than_or_equals", "less_than", "less_than_or_equals",
          "is_null", "is_not_null"
        ],
        "options": [],
        "arguments": [
          {
            "id": "answer_pool_edge",
            "label": "Campo",
            "required": true,
            "modelClass": "App\\Models\\FormEdge",
            "hydrate": {
              "route": "/api/management/get-forms",
              "options": "forms",
              "key": "id",
              "label": "label",
              "children_key": "edges",
              "children_label": "title"
            }
          }
        ],
        "hydrate": null
      }
    ],
    "sorting": [
      { "name": "name", "arguments": [] },
      { "name": "impact", "arguments": [] },
      { "name": "created_at", "arguments": [] }
    ]
  }
}

A resposta real traz todos os filtros e todas as ordenações do objeto. Cada item de params.filters descreve um campo que você pode usar em filters[].field:

Campo	O que informa
`name`	O nome a usar em `filters[].field`.
`input_type`	O tipo de valor esperado, como `text`, `number`, `date` ou `datetime-local`.
`operators`	Os operadores aceitos por esse campo.
`options`	Os valores fixos aceitos, com rótulo e valor, quando o campo tem uma lista fechada. Envie o `value` da opção.
`arguments`	Os argumentos que o campo aceita. `required: true` indica argumento obrigatório, e `hydrate` diz em qual endpoint buscar os valores possíveis.
`hydrate`	Onde buscar as opções do próprio campo, ou `null` quando não se aplica.

Os itens de params.sorting trazem o name a usar em sorting[].field.

Tratamento de erros

Quando um filtro não é válido, a API responde com HTTP 422, message: "validation_errors" e o detalhe em validation, como em qualquer erro de validação. Consulte o endpoint de metadados para ver o que o campo aceita.

Campo inválido

A API recusa o filtro quando field não está na lista de campos do endpoint. A mensagem cita o nome enviado e lista os campos disponíveis. No exemplo, a lista de campos está encurtada:

{
  "response": false,
  "message": "validation_errors",
  "error": "O campo [nonExistsFilterField] selecionado é inválido. Campos disponíveis: id, code, name, description, impact, status, budget.",
  "validation": {
    "field": ["O campo [nonExistsFilterField] selecionado é inválido. Campos disponíveis: id, code, name, description, impact, status, budget."]
  }
}

Para resolver, use em field um dos valores de name em params.filters.

Operador inválido

A API recusa o filtro quando operator não é um dos operadores de comparação. A chave em validation começa pela posição do filtro na lista filters, contando a partir de 0. No exemplo, o erro está no primeiro filtro:

{
  "response": false,
  "message": "validation_errors",
  "error": "O campo 0.operator selecionado é inválido.",
  "validation": {
    "0.operator": ["O campo 0.operator selecionado é inválido."]
  }
}

Para resolver, troque o operador por um dos valores de operators do campo.

Argumento obrigatório ausente

A API recusa o filtro quando o campo tem um argumento com required: true e o filtro não traz arguments. No exemplo, o filtro por resposta de formulário (answer_pool) chegou sem o campo do formulário:

{
  "response": false,
  "message": "validation_errors",
  "error": "Argument zero must be id of edge",
  "validation": {
    "answer_pool": ["Argument zero must be id of edge"]
  }
}

Para resolver, envie em arguments os argumentos obrigatórios listados para o campo no endpoint de metadados.

Data inválida

A API recusa um filtro de created_at quando o valor não é uma data válida, como 2026-02-30 ou 30/09/2026. O detalhe fica na chave filters de validation:

{
  "response": false,
  "message": "validation_errors",
  "error": "O campo created_at não é uma data válida.",
  "validation": {
    "filters": ["O campo created_at não é uma data válida."]
  }
}

Para resolver, envie a data no formato AAAA-MM-DD, por exemplo 2026-09-30.

Páginas relacionadas

Estas páginas complementam a busca avançada:

Filtros básicos: filtros simples com filter[campo] na URL.
Paginação: os parâmetros page e perPage e o objeto meta.
Formulários dinâmicos e o pivot: o que são os campos e as respostas de formulário.

Introdução

Geral

Referência da API

Primeira busca

Estrutura da requisição

Estrutura de um filtro

Operadores de comparação

Combinar filtros com and e or

Estrutura de uma ordenação

Argumentos adicionais

Exemplos

Filtrar por data de criação

Descobrindo campos disponíveis

Tratamento de erros

Campo inválido

Operador inválido

Argumento obrigatório ausente

Data inválida

Páginas relacionadas

​Primeira busca

​Estrutura da requisição

​Estrutura de um filtro

​Operadores de comparação

​Combinar filtros com and e or

​Estrutura de uma ordenação

​Argumentos adicionais

​Exemplos

​Filtrar por data de criação

​Descobrindo campos disponíveis

​Tratamento de erros

​Campo inválido

​Operador inválido

​Argumento obrigatório ausente

​Data inválida

​Páginas relacionadas

Primeira busca

Estrutura da requisição

Estrutura de um filtro

Operadores de comparação

Combinar filtros com and e or

Estrutura de uma ordenação

Argumentos adicionais

Exemplos

Filtrar por data de criação

Descobrindo campos disponíveis

Tratamento de erros

Campo inválido

Operador inválido

Argumento obrigatório ausente

Data inválida

Páginas relacionadas