Capacidade de pesquisa de catálogo

• Nome do recurso: br.dev.bcp.shopping.catalog.search

Executa uma pesquisa no catálogo de produtos da empresa. Suporta texto livre consultas, filtragem por categoria e preço e paginação.

Operação

Operação	Descrição
Pesquisar Catálogo	Pesquise produtos usando entradas e filtros fornecidos.

Solicitação

Nome	Tipo	Obrigatório	Descrição
query	string	Não	Consulta de busca em texto livre.
context	object	Não	Sinais provisórios do buyer para relevância e localização—não são dados autoritativos. Empresas DEVERIAM usar estes valores quando entradas verificadas (ex.: endereço de shipping) estiverem ausentes, e PODEM ignorá-los ou reduzir sua prioridade se inconsistentes com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (controles de exportação). A elegibilidade e a aplicação de políticas DEVEM ocorrer no momento do checkout usando dados vinculantes da transação. O Context DEVERIA ser não identificável e pode ser divulgado progressivamente—sinais grosseiros no início, resolução mais fina à medida que a sessão avança. Dados de maior resolução (endereço de shipping, endereço de cobrança) têm precedência sobre o context.
signals	object	Não	Dados de ambiente fornecidos pela plataforma para apoiar a autorização e a prevenção de abusos. Os valores NÃO DEVEM ser declarações afirmadas pelo comprador — as plataformas fornecem sinais com base em observação direta ou em atestações de terceiros verificáveis de forma independente. Todas as chaves de sinal DEVEM usar nomenclatura em domínio reverso para garantir a proveniência e prevenir colisões quando múltiplas extensões contribuem para o namespace compartilhado.
attribution	object	Não	Contexto de indicação e evento de conversão emitido pela plataforma — identificadores de campanha, IDs de clique, marcadores de source/medium, etc. Os mesmos parâmetros que as plataformas comunicam via parâmetros de consulta de URL em fluxos baseados em navegador.
filters	object	Não	Critérios de filtro para restringir os resultados de busca. Todos os filtros especificados se combinam com lógica AND.
pagination	object	Não	Parâmetros de paginação para requisições.

Resposta

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de catálogo.
products	Array[object]	Sim	Produtos que correspondem aos critérios de busca.
pagination	object	Não	Informações de paginação nas respostas.
messages	Array[object]	Não	Erros, avisos ou mensagens informativas sobre os resultados da busca.

Entradas de pesquisa

Uma solicitação de pesquisa válida DEVE incluir pelo menos um dos seguintes: uma string query, um ou mais filters, ou uma entrada definida por extensão. Quando query é omitido, a solicitação representa uma operação de navegação — o negócio retorna produtos que correspondem aos filtros fornecidos sem classificação de relevância de texto. As extensões PODEM definir entradas adicionais (por exemplo, similaridade visual, referências do produto).

As implementações DEVEM validar se as solicitações recebidas contêm pelo menos um entrada reconhecida e DEVE rejeitar solicitações vazias ou inválidas com um erro apropriado. As implementações definem e aplicam suas próprias regras para presença e conteúdo de entrada - por exemplo, exigindo query, rejeitando strings query vazias ou aceitar solicitações somente de filtro para navegação por categoria.

Filtros de pesquisa

Filtre critérios para restringir os resultados da pesquisa. Os filtros padrão são definidos abaixo; os comerciantes PODEM oferecer suporte a filtros personalizados adicionais via additionalProperties.

Nome	Tipo	Obrigatório	Descrição
categories	Array[string]	Não	Filtra por categorias de produto (lógica OR — corresponde a produtos em qualquer das categorias listadas). Os valores correspondem ao campo value nas entradas de categoria do produto. Valores válidos podem ser descobertos a partir do campo categories nos resultados de busca, da documentação do lojista ou de taxonomias padrão às quais as empresas podem se alinhar.
price	Price Filter	Não	Filtro de faixa de preço denominado em context.currency. Quando context.currency corresponde à moeda de apresentação, as empresas aplicam o filtro diretamente. Quando difere, as empresas DEVERIAM converter os valores do filtro para a moeda de apresentação antes de aplicar; se a conversão não for suportada, as empresas PODEM ignorar o filtro e DEVERIAM indicar isso por meio de uma mensagem. Quando context.currency está ausente, a denominação do filtro é ambígua e as empresas PODEM ignorá-lo.

Filtro de Preço

Nome	Tipo	Obrigatório	Descrição
min	Amount	Não	Preço mínimo em unidades menores ISO 4217.
max	Amount	Não	Preço máximo em unidades menores ISO 4217.

Paginação

Paginação baseada em cursor para operações de lista. Cursores são strings opacas que as implementações PODEM ser codificadas como tokens de conjunto de chaves sem estado.

Tamanho da página

O parâmetro limit é um tamanho de página solicitado, não uma contagem garantida. As implementações DEVEM aceitar um tamanho de página de pelo menos 10. Quando o limite solicitado excede o máximo da implementação, implementações PODEM atingir o máximo silenciosamente - retornando menos resultados sem erro. Os clientes NÃO DEVEM assumir que o tamanho da resposta é igual ao limite solicitado.

Solicitação de paginação

Parâmetros de paginação para requisições.

Nome	Tipo	Obrigatório	Descrição
cursor	string	Não	Cursor opaco da resposta anterior.
limit	integer	Não	Tamanho de página solicitado. As implementações PODEM limitar a um máximo menor.

Resposta de paginação

Informações de paginação nas respostas.

Nome	Tipo	Obrigatório	Descrição
cursor	string	Não	Cursor para buscar a próxima página de resultados. DEVE estar presente quando has_next_page for true.
has_next_page	boolean	Sim	Se há mais resultados disponíveis.
total_count	integer	Não	Número total de itens correspondentes, se disponível.

Ligações de transporte

• REST Binding: não publicado nesta versão do BCP.
• Vinculação MCP: ferramenta search_catalog