Pular para conteúdo

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

Name Type Required Description
query string No Free-text search query.
context object No Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals object No Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution object No Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
filters object No Filter criteria to narrow search results. All specified filters combine with AND logic.
pagination object No Pagination parameters for requests.

Resposta

Name Type Required Description
ucp any Yes UCP metadata for catalog responses.
products Array[object] Yes Products matching the search criteria.
pagination object No Pagination information in responses.
messages Array[object] No Errors, warnings, or informational messages about the search results.

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.

Name Type Required Description
categories Array[string] No Filter by product categories (OR logic — matches products in any listed categories). Values match against the value field in product category entries. Valid values can be discovered from the categories field in search results, merchant documentation, or standard taxonomies that businesses may align with.
price Price Filter No Price range filter denominated in context.currency. When context.currency matches the presentment currency, businesses apply the filter directly. When it differs, businesses SHOULD convert filter values to the presentment currency before applying; if conversion is not supported, businesses MAY ignore the filter and SHOULD indicate this via a message. When context.currency is absent, filter denomination is ambiguous and businesses MAY ignore it.

Filtro de Preço

Name Type Required Description
min Amount No Minimum price in ISO 4217 minor units.
max Amount No Maximum price in ISO 4217 minor units.

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

Pagination parameters for requests.

Name Type Required Description
cursor string No Opaque cursor from previous response.
limit integer No Requested page size. Implementations MAY clamp to a lower maximum.

Resposta de paginação

Pagination information in responses.

Name Type Required Description
cursor string No Cursor to fetch the next page of results. MUST be present when has_next_page is true.
has_next_page boolean Yes Whether more results are available.
total_count integer No Total number of matching items, if available.

Ligações de transporte

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