Capacidade de consulta 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), as implementações DEVEM retornar os produtos correspondentes e PODEM limitar o conjunto de resultados. Quando vários identificadores resolverem para o mesmo produto, ele 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.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	O identificador da requisição de lookup que foi resolvido para esta variante.
match	string	Não	Como o identificador da requisição foi resolvido para esta variante. Valores conhecidos: exact (a entrada identifica diretamente esta variante, ex.: ID da variante, SKU), featured (o servidor selecionou esta variante como representativa, ex.: ID do produto resolvido para a melhor correspondência). As empresas PODEM implementar e fornecer estratégias adicionais de resolução.

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, o array inputs da variante contém uma entrada por identificador resolvido, cada uma 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. As implementações PODEM impor um tamanho máximo de lote e DEVEM rejeitar solicitações que excedam esse 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 a mesma semântica AND que os Filtros de pesquisa — 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 (lookup_catalog) ou a seleção de opções (get_product). Um identificador que resolve um produto cujas variantes todas ficarem fora do filtro de preço resulta na exclusão desse produto da resposta.

Solicitação

Corpo da requisição para consulta de catálogo.

Nome	Tipo	Obrigatório	Descrição
ids	Array[string]	Sim	Identificadores a consultar. As implementações DEVEM suportar product ID e variant ID; PODEM suportar identificadores secundários (SKU, handle, etc.).
filters	object	Não	Critérios de filtro para restringir os produtos e variantes retornados. Todos os filtros especificados se combinam com lógica AND.
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.

Resposta

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de catálogo.
products	Array[Product]	Sim	Produtos que correspondem aos identificadores solicitados. Pode conter menos itens se alguns identificadores não forem encontrados, ou mais se os identificadores corresponderem a múltiplos produtos.
messages	Array[object]	Não	Erros, avisos ou mensagens informativas sobre os itens solicitados.

---

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 é encontrado, o servidor retorna ucp.status: "error" com um array messages contendo o detalhe do erro. Este é um resultado de aplicação — o manipulador foi executado 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 o estreitamento interativo de variantes: a interação principal da página de detalhes do produto, onde um usuário seleciona opções progressivamente (Cor, Tamanho, etc.) e a interface 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 as seleções padrão da variante em destaque, caso contrário. 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

Esses campos aparecem em cada valor de opção em product.options[].values[]. Eles refletem a disponibilidade em relação às seleções efetivas. Mudando um seleção altera o mapa de disponibilidade.

Solicitação

Corpo da requisição para recuperação de produto único. Suporta o refinamento interativo de variantes por meio de selected e preferences.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador de produto ou variante. As implementações DEVEM suportar product ID e variant ID.
selected	Array[object]	Não	Seleções de opções parciais ou completas para o refinamento interativo de variantes. Quando fornecidas, os valores de opção na resposta incluem sinais de disponibilidade (available, exists) relativos a essas seleções.
preferences	Array[string]	Não	Nomes de opções em ordem de prioridade de relaxamento. Quando nenhuma variante exata corresponde a todas as seleções, o servidor descarta opções a partir do fim desta lista primeiro. Ex.: ['Color', 'Size'] mantém Color e relaxa Size.
filters	object	Não	Critérios de filtro para restringir as variantes retornadas. Todos os filtros especificados se combinam com lógica AND.
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.

Resposta

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de catálogo.
product	object	Sim	O produto solicitado com detalhe completo. Singular — esta é uma operação de recurso único.
messages	Array[object]	Não	Avisos ou mensagens informativas sobre o produto (ex.: preço alterado recentemente, disponibilidade limitada).

---

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)