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
confira line_items[].item.id. O ID da variante da recuperação do catálogo deve corresponder
o ID do item esperado pela finalização da compra.
As respostas do catálogo (preço, disponibilidade, etc.) refletem a situação atual do Negócio termos para a solicitação fornecida, mas não são compromissos transacionais - checkout é autoritário. As respostas podem ser específicas da sessão e NÃO DEVEM ser reutilizados 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 opcionais dicas de relevância e localização. As plataformas PODEM detectar geograficamente o contexto de solicitar cabeçalhos.
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) estão ausentes e PODEM ignore ou rebaixe-os se for inconsistente com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (exportação controles). A elegibilidade e a aplicação da política DEVEM ocorrer no momento da finalização da compra usando dados de transação vinculativos.
As empresas determinam a atribuição do mercado – incluindo a moeda – com base no contexto
sinais. 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
PODE ajustar price / list_price diretamente para exibição tachada e
PODE usar messages com code: "eligibility_benefit" para atribuir o
ajuste a uma reivindicação específica.
| Name | Type | Required | Description |
|---|---|---|---|
| address_country | string | No | The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example "US". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as "SGP" or a full country name such as "Singapore" can also be used. Optional hint for market context (currency, availability, pricing)—higher-resolution data (e.g., shipping address) supersedes this value. |
| address_region | string | No | The region in which the locality is, and which is in the country. For example, California or another appropriate first-level Administrative division. Optional hint for progressive localization—higher-resolution data (e.g., shipping address) supersedes this value. |
| postal_code | string | No | The postal code. For example, 94043. Optional hint for regional refinement—higher-resolution data (e.g., shipping address) supersedes this value. |
| intent | string | No | Background context describing buyer's intent (e.g., 'looking for a gift under $50', 'need something durable for outdoor use'). Informs relevance, recommendations, and personalization. |
| language | string | No | Preferred language for content. Use IETF BCP 47 language tags (e.g., 'en', 'fr-CA', 'zh-Hans'). For REST, equivalent to Accept-Language header—platforms SHOULD fall back to Accept-Language when this field is absent; when provided, overrides Accept-Language. Businesses MAY return content in a different language if unavailable. |
| currency | string | No | Preferred currency (ISO 4217, e.g., 'EUR', 'USD'). Businesses determine presentment currency from context and authoritative signals; this hint MAY inform selection in multi-currency markets. Also serves as the denomination for price filter values — platforms SHOULD include this field when sending price filters. Response prices include explicit currency confirming the resolution. |
| eligibility | Array[Reverse Domain Name] | No | Buyer claims about eligible benefits such as loyalty membership, payment instrument perks, and similar. Recognized claims MAY inform the Business response (e.g., member-only product availability, adjusted pricing in catalog, provisional discounts at cart or checkout). Businesses MUST ignore unrecognized values without error. Values MUST use reverse-domain naming (e.g., 'com.example.loyalty_gold', 'org.school.student') and MUST be non-identifying. |
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.
| Name | Type | Required | Description |
|---|---|---|---|
| br.dev.bcp.buyer_ip | string | No | Client's IP address (IPv4 or IPv6). |
| br.dev.bcp.user_agent | string | No | Client's HTTP User-Agent header or equivalent. |
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.
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.
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 mais
variante e imagem relevantes primeiro – padrão para pesquisas, melhor correspondência com base na consulta
e contexto para pesquisa. As plataformas DEVEM tratar o primeiro elemento como destaque.
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Global ID (GID) uniquely identifying this product. |
| handle | string | No | URL-safe slug for SEO-friendly URLs (e.g., 'blue-runner-pro'). Use id for stable API references. |
| title | string | Yes | Product title. |
| description | Description | Yes | Product description in one or more formats. |
| url | string | No | Canonical product page URL. |
| categories | Array[Category] | No | Product categories with optional taxonomy identifiers. |
| price_range | Price Range | Yes | Price range across all variants. |
| list_price_range | Price Range | No | List price range before discounts (for strikethrough display). |
| media | Array[Media] | No | Product media (images, videos, 3D models). First item is the featured media for listings. |
| options | Array[Product Option] | No | Product options (Size, Color, etc.). |
| variants | Array[Variant] | Yes | Purchasable variants of this product. First item is the featured variant for listings. |
| rating | Rating | No | Aggregate product rating. |
| tags | Array[string] | No | Product tags for categorization and search. |
| metadata | object | No | Business-defined custom data extending the standard product model. |
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.
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Global ID (GID) uniquely identifying this variant. Used as item.id in checkout. |
| sku | string | No | Business-assigned identifier for inventory and fulfillment. |
| barcodes | Array[object] | No | Industry-standard product identifiers for cross-reference and correlation. |
| handle | string | No | URL-safe variant handle/slug. |
| title | string | Yes | Variant display title (e.g., 'Blue / Large'). |
| description | Description | Yes | Variant description in one or more formats. |
| url | string | No | Canonical variant page URL. |
| categories | Array[Category] | No | Variant categories with optional taxonomy identifiers. |
| price | Price | Yes | Current selling price. |
| list_price | Price | No | List price before discounts (for strikethrough display). |
| unit_price | object | No | Price per standard unit of measurement. MAY be omitted when unit pricing does not apply. |
| availability | object | No | Variant availability for purchase. |
| options | Array[Selected Option] | No | Option values that define this variant (e.g., Color: Blue, Size: Large). |
| media | Array[Media] | No | Variant media (images, videos, 3D models). First item is the featured media for listings. |
| rating | Rating | No | Variant rating. |
| tags | Array[string] | No | Variant tags for categorization and search. |
| metadata | object | No | Business-defined custom data extending the standard variant model. |
| seller | object | No | Optional seller context for this variant. |
Preço¶
| Name | Type | Required | Description |
|---|---|---|---|
| amount | Amount | Yes | Amount in ISO 4217 minor units. Use 0 for free items. |
| currency | string | Yes | ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP'). |
Faixa de preço¶
| Name | Type | Required | Description |
|---|---|---|---|
| min | Price | Yes | Minimum price in the range. |
| max | Price | Yes | Maximum price in the range. |
Mídia¶
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Media type. Well-known values: image, video, model_3d. |
| url | string | Yes | URL to the media resource. |
| alt_text | string | No | Accessibility text describing the media. |
| width | integer | No | Width in pixels (for images/video). |
| height | integer | No | Height in pixels (for images/video). |
Opção de produto¶
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Option name (e.g., 'Size', 'Color'). |
| values | Array[Option Value] | Yes | Available values for this option. |
Valor da opção¶
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | No | Optional server-assigned identifier for this option value. When present in a selected_option, the server SHOULD use it for matching instead of label. |
| label | string | Yes | Display text for this option value (e.g., 'Small', 'Blue'). |
Opção selecionada¶
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Option name (e.g., 'Size'). |
| id | string | No | Optional option value identifier from option_value.id. When present, the server SHOULD use it for matching; name and label remain required for display. |
| label | string | Yes | Selected option label (e.g., 'Large'). |
Avaliação¶
| Name | Type | Required | Description |
|---|---|---|---|
| value | number | Yes | Average rating value. |
| scale_min | number | No | Minimum value on the rating scale (e.g., 1 for 1-5 stars). |
| scale_max | number | Yes | Maximum value on the rating scale (e.g., 5 for 5-star). |
| count | integer | No | Number of reviews contributing to the rating. |
Mensagens e tratamento de erros¶
Todas as respostas do catálogo incluem um array messages opcional que permite às empresas
para fornecer contexto sobre erros, avisos ou avisos informativos.
Tipos de mensagens¶
As mensagens comunicam os resultados do negócio e fornecem contexto:
| Tipo | Quando usar | Códigos de exemplo |
|---|---|---|
error |
Erros a nível empresarial | 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 avisos (por exemplo, alérgeno
declarações, avisos de segurança) que as plataformas não devem ocultar ou ignorar. Veja
Apresentação de aviso para ver a versão completa
contrato de prestação.
Observação: A maioria dos erros de catálogo usa severity: "recoverable" - agentes
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
MCP exemplo. Os documentos do serviço REST não são publicados em
este lançamento do BCP.
Mensagem (Erro)¶
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Constant = error. Message type discriminator. |
| code | Error Code | Yes | Error code identifying the type of error. Standard errors are defined in specification (see examples), and have standardized semantics; freeform codes are permitted. |
| path | string | No | RFC 9535 JSONPath to the component the message refers to (e.g., $.items[1]). |
| content_type | string | No | Content format, default = plain. Enum: plain, markdown |
| content | string | Yes | Human-readable message. |
| severity | string | Yes | Reflects the resource state and recommended action. 'recoverable': platform can resolve by modifying inputs and retrying via API. 'requires_buyer_input': merchant requires information their API doesn't support collecting programmatically (checkout incomplete). 'requires_buyer_review': buyer must authorize before order placement due to policy, regulatory, or entitlement rules. 'unrecoverable': no valid resource exists to act on, retry with new resource or inputs. Errors with 'requires_' severity contribute to 'status: requires_escalation'. Enum:* recoverable, requires_buyer_input, requires_buyer_review, unrecoverable |
Mensagem (Aviso)¶
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Constant = warning. Message type discriminator. |
| path | string | No | JSONPath (RFC 9535) to related field (e.g., $.line_items[0]). |
| code | Warning Code | Yes | Warning code identifying the type of warning. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted. |
| content | string | Yes | Human-readable warning message that MUST be displayed. |
| content_type | string | No | Content format, default = plain. Enum: plain, markdown |
| presentation | string | No | Rendering contract for this warning. 'notice' (default): platform MUST display, MAY dismiss. 'disclosure': platform MUST display in proximity to the path-referenced component, MUST NOT hide or auto-dismiss. See specification for full contract. |
| image_url | string | No | URL to a required visual element (e.g., warning symbol, energy class label). |
| url | string | No | Reference URL for more information (e.g., regulatory site, registry entry, policy page). |
Mensagem (Informações)¶
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Constant = info. Message type discriminator. |
| path | string | No | RFC 9535 JSONPath to the component the message refers to. |
| code | Info Code | No | Info code identifying the type of informational message. Standard codes are defined in capability specs (see examples), and have standardized semantics; freeform codes are permitted. |
| content_type | string | No | Content format, default = plain. Enum: plain, markdown |
| content | string | Yes | Human-readable message. |
Cenários Comuns¶
Pesquisa vazia¶
Quando a pesquisa não encontrar correspondências, retorne um array vazio sem mensagens.json
{
"ucp": {...},
"products": []
}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.json
{
"ucp": {...},
"products": [
{
"id": "prod_xyz789",
"title": "Professional Chef Knife Set",
"description": { "plain": "Complete professional knife collection." },
"price_range": {
"min": { "amount": 29900, "currency": "USD" },
"max": { "amount": 29900, "currency": "USD" }
},
"variants": [
{
"id": "var_abc",
"title": "12-piece Set",
"description": { "plain": "Complete professional knife collection." },
"price": { "amount": 29900, "currency": "USD" },
"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.json
{
"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.json
{
"ucp": {...},
"products": [
{
"id": "prod_nut_butter",
"title": "Artisan Nut Butter Collection",
"description": { "plain": "Assorted artisan nut butters." },
"price_range": {
"min": { "amount": 1299, "currency": "USD" },
"max": { "amount": 1499, "currency": "USD" }
},
"variants": [
{
"id": "var_almond",
"title": "Almond Butter",
"description": { "plain": "Smooth almond butter." },
"price": { "amount": 1299, "currency": "USD" },
"availability": { "available": true }
},
{
"id": "var_cashew",
"title": "Cashew Butter",
"description": { "plain": "Creamy cashew butter." },
"price": { "amount": 1499, "currency": "USD" },
"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.