Buscando documents por conteúdo

POST https://api.fbits.net/document/values/by-entity-name/{name}/search

Para localizar os documents de uma entidade pelo conteúdo deles, use a rota de busca. Enquanto a listagem por nome da entidade filtra por metadados do document (externalId e data de cadastro), a busca filtra pelas propriedades do document.

Apesar do verbo POST, a operação é de leitura: o verbo existe apenas para transportar as condições no corpo da requisição.

Parâmetros para consulta:

• name - nome da entidade, na rota (a busca não diferencia maiúsculas de minúsculas);
• filters - lista de condições sobre o conteúdo do document. Obrigatória e com ao menos uma condição;
• after - cursor de avanço: retorna os documents com id maior que o informado (opcional);
• limit - quantidade de itens da página, de 1 a 50. Quando não informado, assume 50.

Somente propriedades filterable podem ser critério

Uma propriedade só pode ser usada em field se a entidade a declarar com filterable: true no schema — veja Inserindo uma entidade de document. Qualquer outro nome de propriedade é recusado com 400, com a mensagem nomeando a propriedade recusada.

Como consequência, uma entidade cujo schema não declara nenhuma propriedade filterable recusa toda condição com 400. O conserto, nesse caso, é declarar filterable no schema da entidade.

Gramática das condições

• O operador precisa ser compatível com o type declarado para a propriedade no schema. Combinações incompatíveis — como range sobre uma propriedade string — retornam 400;
• Quando filters traz mais de uma condição, todas precisam ser satisfeitas pelo mesmo document (AND);
• Cada requisição aceita no máximo 10 condições. Acima disso o retorno é 400.

Request body:

{
  "filters": [
    { "field": "cor", "op": "eq", "value": "azul" },
    { "field": "preco", "op": "range", "gte": 100, "lte": 200 }
  ],
  "limit": 20
}

Exemplo com o operador in:

{
  "filters": [
    { "field": "cor", "op": "in", "values": ["azul", "verde"] }
  ]
}

Response body:

O retorno usa o mesmo envelope paginado da listagem por nome da entidade:

{
  "items": [
    {
      "id": 4501,
      "documentEntityId": 12,
      "externalId": "ERP-0001",
      "value": "{\"sku\":\"ABC-123\",\"cor\":\"azul\",\"preco\":149.9}",
      "createdAt": "2026-07-27T16:20:00.000Z",
      "updatedAt": "2026-07-27T16:20:00.000Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": false,
    "hasPreviousPage": false,
    "startCursor": 4501,
    "endCursor": 4501
  }
}

Para avançar para a próxima página, envie after com o endCursor da página anterior reenviando as mesmas condições enquanto hasNextPage for true.

Respostas de erro