POST

`products.search`

Alias funcional de products.list. q é aceito mas não obrigatório na implementação.

Grupo: CatálogoRevisão: 2026-10-02Escopo recomendado: products.search

Exemplos seguros e fictícios. O domínio example.invalid e a credencial demonstrativa abaixo não funcionam. Use o token real somente no servidor da sua integração e nunca o inclua em páginas públicas.

Parâmetros

Parâmetros aceitos por products.search
Campo	Tipo	Obrigatoriedade	Descrição	Exemplo fictício
`q`	string	Opcional	Busca tolerante por nome/SKU. Espaços ou * separam até 10 termos combinados com AND; cada termo e os campos comparados são normalizados para minúsculas e caracteres alfanuméricos, ignorando acentos, espaços e pontuação. Termos brutos formados apenas por dígitos e pontos também procuram idCatalogo sem pontos. products.search e products.list usam a mesma função.	`"produto"`
`marca`	string	Opcional	Nome exato da marca, não seu UUID.	`"Marca exemplo"`
`categoria`	string	Opcional	Nome exato da categoria, não seu UUID.	`"Categoria exemplo"`
`familia`	string	Opcional	Família exata do cadastro.	`"Linha exemplo"`
`tag`	string	Opcional	Texto contido nas tags de origem do cadastro.	`"erp"`
`preco_min`	number	Opcional	Preço mínimo, em reais; valor não numérico é ignorado.	`10`
`preco_max`	number	Opcional	Preço máximo, em reais.	`200`
`order`	string	Opcional	nome (padrão), preco_asc, preco_desc ou estoque. Valor desconhecido usa nome.	`"preco_asc"`
`offset`	integer	Opcional	Deslocamento a partir de zero. Passe aqui o next_cursor convertido em número.	`0`
`limit`	integer	Opcional	Recomendado de 1 a 60; padrão 24 e teto 60. Use valores positivos; números negativos podem retornar INTERNAL_ERROR.	`24`

Exemplos fictícios

Os exemplos documentam o formato; eles não executam nenhuma operação.

Requisição

cURL demonstrativo

curl --request POST \
  'https://example.invalid/api/v1/CREDENCIAL_FICTICIA_SEM_VALOR/products.search' \
  --header 'Content-Type: application/json' \
  --data '{"q":"produto","limit":24}'

Corpo JSON

{
  "q": "produto",
  "limit": 24
}

Resposta HTTP 200

{
  "ok": true,
  "method": "products.search",
  "result": {
    "items": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "nome": "Produto de demonstração",
        "codigo": "DEMO-01",
        "idCatalogo": "100.000001",
        "marca": "Marca exemplo",
        "categoria": "Categoria exemplo",
        "imagemThumb": "https://assets.example.com/produto.png",
        "imagens": [
          "https://assets.example.com/produto.png"
        ],
        "imagensCount": 1,
        "specs": {
          "potencia": "10 W",
          "tensao": "220V"
        },
        "preco_venda": 25,
        "estoque": 12,
        "reservado": 2,
        "disponivel_qtd": 10,
        "disponivel": true,
        "motivo_indisponivel": null
      }
    ],
    "total": 1,
    "next_cursor": null
  }
}

Erros

Condições de erro específicas de products.search
HTTP	Código	Condição
403	`TOKEN_NO_COMPANY`	Token sem empresa associada.

Consulte também os erros globais e limites.

Observações

disponivel é a decisão pronta de compra; estoque é o saldo físico, reservado é o saldo comprometido e disponivel_qtd desconta reservas. Valores de estoque e preço podem ser null.
Indisponibilidade: sem_preco, sem_saldo ou esgotado. Produtos indisponíveis continuam na listagem dentro do recorte de fonte.
Com Tiny conectado, listagem, marcas e categorias consideram fonte tiny. products.get consulta SKU ativo da própria empresa sem esse filtro de fonte.
next_cursor é um deslocamento textual, não um cursor opaco: use como offset da próxima chamada até receber null.
Use o escopo exato do método. Escopos amplos não fazem parte deste perfil público.
O parâmetro herdado favoritos depende de usuário e não é utilizável nesta API por token.
A busca q não consulta descrição, ficha técnica nem specs; cada termo precisa aparecer no nome, SKU ou, quando numérico, em idCatalogo.