Capacidade de catálogo¶
Visão geral¶
O recurso Catálogo permite que as plataformas pesquisem e naveguem em catálogos de produtos comerciais. Isso permite a descoberta do produto antes da finalização da compra, suportando casos de uso como:
- Pesquisa de produtos em texto livre
- Categoria e navegação baseada em filtros
- Recuperação de produto/variante em lote por identificador
- Comparação de preços entre variantes
Capacidades¶
| Capacidade | Descrição |
|---|---|
br.dev.bcp.shopping.catalog.search |
Pesquise produtos usando texto de consulta e filtros. |
br.dev.bcp.shopping.catalog.lookup |
Recuperar produtos ou variantes por identificador. |
Conceitos-chave¶
- Produto: um item de catálogo com título, descrição, mídia e um ou mais variantes.
- Variante: um item comprável com seleções de opções específicas (por exemplo, "Azul / Grande"), preço e disponibilidade.
- Preço: os valores de preço incluem o valor (em unidades monetárias menores) e código de moeda, permitindo catálogos em várias moedas.
Relacionamento com Checkout¶
As operações de catálogo retornam IDs de produtos e variantes que podem ser usados diretamente no
checkout, em line_items[].item.id. O ID da variante retornado pelo catálogo deve corresponder
ao ID do item esperado pela finalização da compra.
As respostas do catálogo (preço, disponibilidade, etc.) refletem os termos atuais do negócio para a solicitação fornecida, mas não são compromissos transacionais — o checkout é a fonte da verdade. As respostas podem ser específicas da sessão e NÃO DEVEM ser reutilizadas em sessões sem revalidação.
Entidades Compartilhadas¶
Contexto¶
Localização e contexto de mercado para operações de catálogo. Todos os campos são dicas opcionais de relevância e localização. As plataformas PODEM detectar o contexto geograficamente a partir dos cabeçalhos da solicitação.
Os sinais de contexto são dados provisórios e não oficiais. As empresas DEVEM usar esses valores quando as entradas verificadas (por exemplo, endereço de entrega) estiverem ausentes e PODEM ignorá-los ou rebaixá-los quando forem inconsistentes com sinais de maior confiança (conta autenticada, detecção de risco) ou com restrições regulatórias (controles de exportação). A elegibilidade e a aplicação da política DEVEM ocorrer no momento da finalização da compra, usando dados vinculantes da transação.
As empresas determinam a atribuição de mercado – incluindo a moeda – com base nos sinais de
contexto. Os valores do filtro de preços são denominados em context.currency; quando
a moeda de apresentação é diferente, as empresas DEVEM converter antes de aplicar
(veja Filtro de Preço). Os preços de resposta incluem
códigos de moeda explícitos que confirmam a resolução.
Quando as reivindicações context.eligibility estão presentes, as empresas que as aceitam
PODEM ajustar price / list_price diretamente para exibição tachada e
PODEM usar messages com code: "eligibility_benefit" para atribuir o
ajuste a uma reivindicação específica.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| address_country | string | Não | O país. Recomendado no formato ISO 3166-1 alpha-2 de 2 letras, por exemplo "BR". Para compatibilidade retroativa, um código de país ISO 3166-1 alpha-3 de 3 letras como "BRA" ou um nome completo de país como "Brasil" também pode ser usado. Dica opcional para contexto de mercado (moeda, disponibilidade, precificação)—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor. |
| address_region | string | Não | A região na qual a localidade está, e que fica no país. Por exemplo, São Paulo ou outra divisão administrativa de primeiro nível apropriada. Dica opcional para localização progressiva—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor. |
| postal_code | string | Não | O código postal. Por exemplo, 01310-100. Dica opcional para refinamento regional—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor. |
| intent | string | Não | Contexto de fundo descrevendo a intenção do buyer (ex.: 'procurando um presente abaixo de R$ 50', 'preciso de algo durável para uso externo'). Informa relevância, recomendações e personalização. |
| language | string | Não | Idioma preferido para o conteúdo. Use tags de idioma IETF BCP 47 (ex.: 'pt-BR', 'en', 'zh-Hans'). Para REST, equivalente ao cabeçalho Accept-Language—as plataformas DEVERIAM recorrer ao Accept-Language quando este campo estiver ausente; quando fornecido, sobrepõe o Accept-Language. Empresas PODEM retornar conteúdo em outro idioma se este estiver indisponível. |
| currency | string | Não | Moeda preferida (ISO 4217, ex.: 'BRL', 'USD'). Empresas determinam a moeda de apresentação a partir do context e de sinais autoritativos; esta dica PODE informar a seleção em mercados multimoeda. Também serve como denominação para os valores de filtro de preço — as plataformas DEVERIAM incluir este campo ao enviar filtros de preço. Os preços na resposta incluem a moeda explícita confirmando a resolução. |
| eligibility | Array[Reverse Domain Name] | Não | Reivindicações do buyer sobre benefícios elegíveis, como participação em programa de fidelidade, vantagens de payment instrument e similares. Reivindicações reconhecidas PODEM informar a resposta da Empresa (ex.: disponibilidade de produto exclusiva para membros, precificação ajustada no catálogo, descontos provisórios no cart ou checkout). Empresas DEVEM ignorar valores não reconhecidos sem erro. Os valores DEVEM usar nomenclatura de domínio reverso (ex.: 'com.example.loyalty_gold', 'org.school.student') e DEVEM ser não identificáveis. |
Sinais¶
Dados ambientais fornecidos pela plataforma para apoiar a autorização e prevenção de abusos. Os valores do sinal NÃO DEVEM ser reivindicações afirmadas pelo comprador. Veja Sinais para detalhes e requisitos de privacidade.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| br.dev.bcp.buyer_ip | string | Não | Endereço IP do cliente (IPv4 ou IPv6). |
| br.dev.bcp.user_agent | string | Não | Cabeçalho HTTP User-Agent do cliente ou equivalente. |
Atribuição¶
Contexto de referência e evento de conversão fornecido pela plataforma – IDs de campanha, identificadores de clique e marcadores de origem/mídia comunicados pela plataforma. Consulte Atribuição para obter detalhes e consentimento requisitos.
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.
Produto¶
Um item de catálogo que representa um item vendável com uma ou mais variantes compráveis.
media e variants são arrays ordenados. As empresas DEVEM retornar primeiro a
variante e a imagem mais relevantes – ordem padrão para consultas de lookup, melhor correspondência
com base na consulta e no contexto para pesquisas (search). As plataformas DEVEM tratar o primeiro
elemento como destaque.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ID Global (GID) que identifica exclusivamente este produto. |
| handle | string | Não | Slug seguro para URL, para URLs amigáveis a SEO (por exemplo, 'blue-runner-pro'). Use id para referências de API estáveis. |
| title | string | Sim | Título do produto. |
| description | Description | Sim | Descrição do produto em um ou mais formatos. |
| url | string | Não | URL canônica da página do produto. |
| categories | Array[Category] | Não | Categorias do produto com identificadores de taxonomia opcionais. |
| price_range | Price Range | Sim | Faixa de preço entre todas as variantes. |
| list_price_range | Price Range | Não | Faixa de preço de tabela antes de descontos (para exibição riscada). |
| media | Array[Media] | Não | Mídia do produto (imagens, vídeos, modelos 3D). O primeiro item é a mídia em destaque para as listagens. |
| options | Array[Product Option] | Não | Opções do produto (Tamanho, Cor, etc.). |
| variants | Array[Variant] | Sim | Variantes deste produto disponíveis para compra. O primeiro item é a variante em destaque para as listagens. |
| rating | Rating | Não | Avaliação agregada do produto. |
| tags | Array[string] | Não | Tags do produto para categorização e busca. |
| metadata | object | Não | Dados personalizados definidos pela empresa que estendem o modelo de produto padrão. |
Variante¶
Um item comprável com seleções de opções específicas, preço e disponibilidade.
Nas respostas de pesquisa, cada variante carrega um array inputs para correlação:
quais identificadores de solicitação foram resolvidos para esta variante e se a correspondência
era exact ou featured (selecionado pelo servidor). Veja
Correlação do cliente para obter detalhes.
media é uma matriz ordenada. As empresas DEVEM retornar a imagem da variante em destaque
como o primeiro elemento. As plataformas DEVEM tratar o primeiro elemento como destaque.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | ID Global (GID) que identifica exclusivamente esta variante. Usado como item.id no checkout. |
| sku | string | Não | Identificador atribuído pela empresa para estoque e fulfillment. |
| barcodes | Array[object] | Não | Identificadores de produto padrão da indústria para referência cruzada e correlação. |
| handle | string | Não | Handle/slug da variante seguro para URL. |
| title | string | Sim | Título de exibição da variante (por exemplo, 'Azul / Grande'). |
| description | Description | Sim | Descrição da variante em um ou mais formatos. |
| url | string | Não | URL canônica da página da variante. |
| categories | Array[Category] | Não | Categorias da variante com identificadores de taxonomia opcionais. |
| price | Price | Sim | Preço de venda atual. |
| list_price | Price | Não | Preço de tabela antes de descontos (para exibição riscada). |
| unit_price | object | Não | Preço por unidade padrão de medida. PODE ser omitido quando a precificação por unidade não se aplica. |
| availability | object | Não | Disponibilidade da variante para compra. |
| options | Array[Selected Option] | Não | Valores de opção que definem esta variante (por exemplo, Cor: Azul, Tamanho: Grande). |
| media | Array[Media] | Não | Mídia da variante (imagens, vídeos, modelos 3D). O primeiro item é a mídia em destaque para as listagens. |
| rating | Rating | Não | Avaliação da variante. |
| tags | Array[string] | Não | Tags da variante para categorização e busca. |
| metadata | object | Não | Dados personalizados definidos pela empresa que estendem o modelo de variante padrão. |
| seller | object | Não | Contexto opcional do vendedor para esta variante. |
Preço¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| amount | Amount | Sim | Valor em unidades menores ISO 4217. Use 0 para itens gratuitos. |
| currency | string | Sim | Código de moeda ISO 4217 (por exemplo, 'BRL', 'USD', 'EUR'). |
Faixa de preço¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| min | Price | Sim | Preço mínimo da faixa. |
| max | Price | Sim | Preço máximo da faixa. |
Mídia¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | Tipo de mídia. Valores conhecidos: image, video, model_3d. |
| url | string | Sim | URL do recurso de mídia. |
| alt_text | string | Não | Texto de acessibilidade que descreve a mídia. |
| width | integer | Não | Largura em pixels (para imagens/vídeo). |
| height | integer | Não | Altura em pixels (para imagens/vídeo). |
Opção de produto¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome da opção (por exemplo, 'Tamanho', 'Cor'). |
| values | Array[Option Value] | Sim | Valores disponíveis para esta opção. |
Valor da opção¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Não | Identificador opcional atribuído pelo servidor para este valor de opção. Quando presente em um selected_option, o servidor DEVERIA usá-lo para correspondência em vez do label. |
| label | string | Sim | Texto de exibição para este valor de opção (ex.: 'Pequeno', 'Azul'). |
Opção selecionada¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome da opção (por exemplo, 'Tamanho'). |
| id | string | Não | Identificador opcional do valor da opção, vindo de option_value.id. Quando presente, o servidor DEVERIA usá-lo para correspondência; name e label continuam obrigatórios para exibição. |
| label | string | Sim | Rótulo da opção selecionada (por exemplo, 'Grande'). |
Avaliação¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| value | number | Sim | Valor médio da avaliação. |
| scale_min | number | Não | Valor mínimo na escala de avaliação (por exemplo, 1 para 1-5 estrelas). |
| scale_max | number | Sim | Valor máximo na escala de avaliação (por exemplo, 5 para 5 estrelas). |
| count | integer | Não | Número de avaliações que contribuem para a nota. |
Mensagens e tratamento de erros¶
Todas as respostas do catálogo incluem um array messages opcional que permite às empresas
fornecer contexto sobre erros, avisos ou mensagens informativas.
Tipos de mensagens¶
As mensagens comunicam os resultados do negócio e fornecem contexto:
| Tipo | Quando usar | Códigos de exemplo |
|---|---|---|
error |
Erros em nível de negócio | NOT_FOUND, OUT_OF_STOCK, REGION_RESTRICTED |
warning |
Condições importantes que afetam a compra | DELAYED_FULFILLMENT, FINAL_SALE |
info |
Contexto adicional sem problemas | PROMOTIONAL_PRICING, LIMITED_AVAILABILITY |
Os avisos com presentation: "disclosure" trazem alertas (por exemplo, declarações
de alérgenos, avisos de segurança) que as plataformas NÃO DEVEM ocultar ou ignorar. Veja
Apresentação de aviso para o contrato completo de
apresentação.
Observação: A maioria dos erros de catálogo usa severity: "recoverable" — os agentes
devem tratá-los programaticamente (tentar novamente, informar o usuário, mostrar alternativas).
get_product retorna severity: "unrecoverable" quando um identificador
não resolve; os agentes NÃO DEVEM tentar novamente o mesmo id. Veja o
exemplo em MCP. Os documentos do serviço REST não são publicados
nesta versão do BCP.
Mensagem (Erro)¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | Constant = error. Discriminador do tipo de mensagem. |
| code | Error Code | Sim | Código de erro que identifica o tipo de erro. Erros padrão são definidos na especificação (ver exemplos) e têm semântica padronizada; códigos de formato livre são permitidos. |
| path | string | Não | JSONPath (RFC 9535) para o componente ao qual a mensagem se refere (ex.: $.items[1]). |
| content_type | string | Não | Formato do conteúdo, default = plain. Enum: plain, markdown |
| content | string | Sim | Mensagem legível por humanos. |
| severity | string | Sim | Reflete o estado do recurso e a ação recomendada. 'recoverable': a plataforma pode resolver modificando as entradas e repetindo via API. 'requires_buyer_input': o lojista exige informação que sua API não suporta coletar de forma programática (checkout incompleto). 'requires_buyer_review': o comprador DEVE autorizar antes da colocação do pedido devido a regras de política, regulatórias ou de elegibilidade. 'unrecoverable': não existe recurso válido sobre o qual agir; repita com novo recurso ou entradas. Erros com severidade 'requires_' contribuem para 'status: requires_escalation'. Enum:* recoverable, requires_buyer_input, requires_buyer_review, unrecoverable |
Mensagem (Aviso)¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | Constant = warning. Discriminador do tipo de mensagem. |
| path | string | Não | JSONPath (RFC 9535) para o campo relacionado (ex.: $.line_items[0]). |
| code | Warning Code | Sim | Código de aviso que identifica o tipo de aviso. Códigos padrão são definidos nas specs de capabilities (veja os exemplos) e têm semântica padronizada; códigos de formato livre são permitidos. |
| content | string | Sim | Mensagem de aviso legível por humanos que DEVE ser exibida. |
| content_type | string | Não | Formato do conteúdo, default = plain. Enum: plain, markdown |
| presentation | string | Não | Contrato de renderização para este aviso. 'notice' (default): a plataforma DEVE exibir, PODE dispensar. 'disclosure': a plataforma DEVE exibir próximo ao componente referenciado pelo path, NÃO DEVE ocultar nem dispensar automaticamente. Ver a especificação para o contrato completo. |
| image_url | string | Não | URL de um elemento visual obrigatório (ex.: símbolo de aviso, etiqueta de classe energética). |
| url | string | Não | URL de referência para mais informações (ex.: site regulatório, entrada de registro, página de política). |
Mensagem (Informações)¶
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| type | string | Sim | Constant = info. Discriminador do tipo de mensagem. |
| path | string | Não | JSONPath (RFC 9535) para o componente ao qual a mensagem se refere. |
| code | Info Code | Não | Código informativo que identifica o tipo de mensagem informativa. Os códigos padrão são definidos nas specs de capability (ver exemplos) e têm semântica padronizada; códigos de forma livre são permitidos. |
| content_type | string | Não | Formato do conteúdo, default = plain. Enum: plain, markdown |
| content | string | Sim | Mensagem legível por humanos. |
Cenários Comuns¶
Pesquisa vazia¶
Quando a pesquisa não encontrar correspondências, retorne um array vazio sem mensagens.
Isto não é um erro – a consulta era válida, mas não retornou resultados.
Aviso de pedido pendente¶
Quando um produto estiver disponível, mas tiver atraso no atendimento, devolva o produto com
uma mensagem de aviso. Use o campo path para segmentar variantes específicas.
{
"ucp": {...},
"products": [
{
"id": "prod_xyz789",
"title": "Professional Chef Knife Set",
"description": { "plain": "Complete professional knife collection." },
"price_range": {
"min": { "amount": 29900, "currency": "BRL" },
"max": { "amount": 29900, "currency": "BRL" }
},
"variants": [
{
"id": "var_abc",
"title": "12-piece Set",
"description": { "plain": "Complete professional knife collection." },
"price": { "amount": 29900, "currency": "BRL" },
"availability": { "available": true }
}
]
}
],
"messages": [
{
"type": "warning",
"code": "delayed_fulfillment",
"path": "$.products[0].variants[0]",
"content": "12-piece set on backorder, ships in 2-3 weeks"
}
]
}
Os agentes podem apresentar a opção e informar o usuário sobre o atraso. O path
campo usa RFC 9535 JSONPath para direcionar componentes específicos.
Identificadores não encontrados¶
Quando os identificadores solicitados não existirem, retorne sucesso com os produtos encontrados (se houver). A resposta PODE incluir mensagens informativas indicando quais identificadores não foram encontrados.
{
"ucp": {...},
"products": [],
"messages": [
{
"type": "info",
"code": "not_found",
"content": "prod_invalid"
}
]
}
Os agentes correlacionam os resultados usando a matriz inputs em cada variante. Veja
Correlação do cliente.
Divulgação do Produto¶
Quando um produto exige uma divulgação (por exemplo, aviso sobre alérgenos, aviso de segurança),
retorne-o como aviso com presentation: "disclosure". O campo path tem como alvo o
componente relevante na resposta – quando se destina a um produto, o
a divulgação se aplica a todas as suas variantes.
{
"ucp": {...},
"products": [
{
"id": "prod_nut_butter",
"title": "Artisan Nut Butter Collection",
"description": { "plain": "Assorted artisan nut butters." },
"price_range": {
"min": { "amount": 1299, "currency": "BRL" },
"max": { "amount": 1499, "currency": "BRL" }
},
"variants": [
{
"id": "var_almond",
"title": "Almond Butter",
"description": { "plain": "Smooth almond butter." },
"price": { "amount": 1299, "currency": "BRL" },
"availability": { "available": true }
},
{
"id": "var_cashew",
"title": "Cashew Butter",
"description": { "plain": "Creamy cashew butter." },
"price": { "amount": 1499, "currency": "BRL" },
"availability": { "available": true }
}
]
}
],
"messages": [
{
"type": "warning",
"code": "allergens",
"path": "$.products[0]",
"content": "**Contains: tree nuts.** Produced in a facility that also processes peanuts, milk, and soy.",
"content_type": "markdown",
"presentation": "disclosure",
"image_url": "https://merchant.com/allergen-tree-nuts.svg",
"url": "https://merchant.com/allergen-info"
}
]
}
Consulte Apresentação de aviso para obter informações contrato de prestação integral.
Escopos¶
Os recursos Pesquisa de Catálogo e Pesquisa de Catálogo definem o seguinte escopos bem conhecidos para acesso autenticado pelo usuário:
| Escopo | Descrição |
|---|---|
br.dev.bcp.shopping.catalog.search:read |
Pesquise em nome do usuário autenticado – resultados personalizados, preços para membros, inventário fechado. |
br.dev.bcp.shopping.catalog.lookup:read |
Pesquisa em nome do usuário autenticado – preços personalizados ou disponibilidade para produtos específicos. |
Declaração de escopo, derivação e regras para estender este conjunto com escopos personalizados são definidos em Vinculação de identidade — Escopos.
Ligações de transporte¶
Os recursos acima estão vinculados a protocolos de transporte específicos:
- REST Binding: não publicado nesta versão do BCP.
- MCP Binding: mapeamento do protocolo de contexto do modelo via JSON-RPC.