Capacidade de pesquisa de catálogo

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

Recupera produtos ou variantes por identificador. Use isso quando você já tiver identificadores (por exemplo, de uma lista salva, links diretos, validação de carrinho ou um selecionado produto para renderização de detalhes).

Operações

Operação	Ferramenta / Ponto final	Descrição
Pesquisa em lote	lookup_catalog / POST /catalog/lookup	Recuperar vários produtos por identificador.
Obter produto	get_product / POST /catalog/product	Recuperar todos os detalhes de um único produto.

lookup_catalog resolve identificadores para produtos; get_product busca detalhes completos de um produto conhecido ou ID de variante:

Preocupação	lookup_catalog	get_product
Entrada	ids[] — ID do produto/variante; PODE suportar SKU, identificador, URL, etc.	id — ID do produto ou variante
Objetivo	Resolver identificadores para produtos	Detalhes completos do produto para decisões de compra com seleção de opções interativas
Variantes	Uma variante em destaque por produto	Variante em destaque e subconjunto relevante, filtrado por seleções de opções

Use lookup_catalog quando tiver identificadores para resolver ou exibir em uma lista. Use get_product quando um produto for identificado e o agente precisar detalhes, incluindo seleção interativa de variantes, para uma decisão de compra.

---

Pesquisa em lote (lookup_catalog)

Identificadores Suportados

O parâmetro ids aceita um array de identificadores. As implementações DEVEM apoiar pesquisa por ID do produto e ID da variante. As implementações PODEM apoiar adicionalmente identificadores secundários, como SKU ou identificador, desde que também sejam campos em o objeto do produto retornado.

Identificadores duplicados na solicitação DEVEM ser desduplicados. Quando um identificador corresponde a vários produtos (por exemplo, um SKU compartilhado entre variantes), implementações retornar produtos correspondentes e PODE limitar o conjunto de resultados. Quando vários identificadores resolver para o mesmo produto, DEVE ser devolvido uma vez.

Correlação do cliente

A resposta não garante a ordem. Cada variante carrega um inputs matriz identificando quais identificadores de solicitação foram resolvidos e como.

Name	Type	Required	Description
id	string	Yes	The identifier from the lookup request that resolved to this variant.
match	string	No	How the request identifier resolved to this variant. Well-known values: exact (input directly identifies this variant, e.g., variant ID, SKU), featured (server selected this variant as representative, e.g., product ID resolved to best match). Businesses MAY implement and provide additional resolution strategies.

Vários identificadores de solicitação podem resolver para a mesma variante (por exemplo, um ID do produto e um de seus IDs de variante). Quando isso ocorre, a variante O array inputs contém uma entrada por identificador resolvido, cada um com seu próprio tipo de correspondência. Variantes sem entrada inputs NÃO DEVEM aparecer em respostas de pesquisa.

Tamanho do lote

As implementações DEVEM aceitar pelo menos 10 identificadores por solicitação. Implementações PODE impor um tamanho máximo de lote e DEVE rejeitar solicitações que excedam seu limite com um erro apropriado (HTTP 400 request_too_large para REST, JSON-RPC -32602 para MCP).

Comportamento de resolução

match reflete o nível de resolução do identificador, não o seu tipo:

• exact: Identificador resolvido diretamente para esta variante (por exemplo, ID da variante, SKU, código de barras).
• featured: Identificador resolvido para o produto pai; servidor selecionou esta variante como representativa (por exemplo, ID do produto, identificador).

Filtros

Tanto lookup_catalog quanto get_product aceitam filters opcional para restringir os produtos e variantes devolvidos. Os filtros usam o mesmo esquema e semântica AND como Filtros de pesquisa - para por exemplo, um filtro de preço exclui variantes fora do intervalo especificado.

Os filtros são aplicados após a resolução do identificador (pesquisa) ou a seleção de opções (obter_produto). Um identificador que resolve um produto cujas variantes todos ficarem fora do filtro de preço resulta na exclusão desse produto da resposta.

Solicitação

Request body for catalog lookup.

Name	Type	Required	Description
ids	Array[string]	Yes	Identifiers to lookup. Implementations MUST support product ID and variant ID; MAY support secondary identifiers (SKU, handle, etc.).
filters	object	No	Filter criteria to narrow returned products and variants. All specified filters combine with AND logic.
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.

Resposta| Name | Type | Required | Description |

| :--- | :--- | :--- | :--- | | ucp | any | Yes | UCP metadata for catalog responses. | | products | Array[Product] | Yes | Products matching the requested identifiers. May contain fewer items if some identifiers not found, or more if identifiers match multiple products. | | messages | Array[object] | No | Errors, warnings, or informational messages about the requested items. |

---

Obter produto (get_product)

Recupera o estado atual do produto para um único identificador, com suporte para seleção interativa de variantes e sinais de disponibilidade em tempo real. Este é o fonte confiável para decisões de compra.

Identificadores Suportados

O parâmetro id aceita um único ID de produto ou ID de variante.

Comportamento de resolução

A resposta retorna o produto com contexto completo (título, descrição, mídia, opções) e um subconjunto de variantes correspondentes product.selected:

• ID do produto: variants DEVE conter a variante em destaque e outras variantes correspondentes a product.selected. Quando a solicitação inclui selected opções, isso restringe o subconjunto a variantes que correspondam às escolhas do cliente.
• ID da variante: A variante solicitada DEVE ser o primeiro elemento (destaque). product.selected reflete as opções dessa variante. Variantes restantes corresponder às mesmas seleções efetivas. Quando a solicitação inclui selected opções que entram em conflito com as próprias opções da variante, as opções da variante as opções têm precedência – o ID da variante determina totalmente a seleção estado e selected é ignorado.

Forma de resposta

A resposta contém um objeto product singular (não uma matriz). Isso reflete a semântica de recurso único da operação. Quando o identificador não for encontrado, o servidor retorna ucp.status: "error" com um array messages contendo o detalhe do erro. Este é um resultado do aplicativo — o manipulador executou e reportou seu resultado através do envelope BCP, não um erro de transporte.

Seleção de opções

Os parâmetros selected e preferences permitem variantes interativas estreitamento: a interação principal da página de detalhes do produto, onde um usuário seleciona opções progressivamente (Cor, Tamanho, etc.) e a IU atualiza a disponibilidade em tempo real.

Entrada

• selected: Matriz de seleções de opções (por exemplo, [{"name": "Color", "label": "Red"}]). As seleções parciais são válidas; o cliente envia tudo o que o usuário escolheu até agora. Cada nome de opção DEVE aparecer no máximo uma vez.
• preferences: Nomes de opções em ordem de prioridade de relaxamento (por exemplo, ["Color", "Size"]). Quando nenhuma variante corresponde a todas as seleções, o servidor descarta opções do final desta lista primeiro, mantendo as seleções de maior prioridade intacto. Opcional; se omitido, o servidor usa sua própria heurística de relaxamento.

Saída: Seleções Efetivas

A resposta DEVE incluir product.selected quando o produto tiver opções configuráveis — refletindo as seleções efetivas após qualquer relaxamento quando a solicitação incluir selected, ou o destaque caso contrário, as seleções padrão da variante. Quando o produto não possui opções configuráveis, selected PODE estar vazio ou omitido.

Clientes que enviam selected detectam relaxamento diferenciando sua solicitação contra product.selected:

• Sem relaxamento: A resposta selected corresponde à solicitação — todas seleções resolvidas para pelo menos uma variante.
• Ocorreu relaxamento: A resposta selected é um subconjunto do solicitação - o servidor eliminou opções não resolvíveis por preferences prioridade.

Saída: Sinais de Disponibilidade

Os valores das opções na resposta DEVEM incluir sinais de disponibilidade em relação a product.selected:

available	exists	Significado	Tratamento de IU
true	true	Em estoque — comprável	Selecionável
false	true	Esgotado – variante existe, mas não está disponível	Desativado/tachado
false	false	Nenhuma variante para esta combinação	Oculto ou visualmente distinto
refletem a disponibilidade em relação às seleções efetivas. Mudando um
seleção altera o mapa de disponibilidade.

Solicitação

Request body for single-product retrieval. Supports interactive variant narrowing via selected and preferences.

Name	Type	Required	Description
id	string	Yes	Product or variant identifier. Implementations MUST support product ID and variant ID.
selected	Array[object]	No	Partial or full option selections for interactive variant narrowing. When provided, response option values include availability signals (available, exists) relative to these selections.
preferences	Array[string]	No	Option names in relaxation priority order. When no exact variant matches all selections, the server drops options from the end of this list first. E.g., ['Color', 'Size'] keeps Color and relaxes Size.
filters	object	No	Filter criteria to narrow returned variants. All specified filters combine with AND logic.
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.

Resposta

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for catalog responses.
product	object	Yes	The requested product with full detail. Singular — this is a single-resource operation.
messages	Array[object]	No	Warnings or informational messages about the product (e.g., price recently changed, limited availability).

---

Ligações de transporte

• REST Binding: não publicado nesta versão do BCP.
• MCP Binding: ferramenta lookup_catalog (lote)
• MCP Binding: ferramenta get_product (única)