Capacidade do carrinho¶

Nome do recurso: br.dev.bcp.shopping.cart

Visão geral¶

O recurso Carrinho permite a construção de cestas sem a complexidade da finalização da compra. Embora Checkout gerencie manipuladores de pagamento, ciclo de vida de status e finalização do pedido, o carrinho fornece uma interface CRUD leve para o item coleta antes que a intenção de compra seja estabelecida.

Quando usar Carrinho vs Checkout:

Carrinho: O usuário está explorando, comparando e salvando itens para mais tarde. Sem pagamento configuração necessária. A plataforma/agente pode adicionar, remover e atualizar itens livremente.
Checkout: o usuário expressou intenção de compra. Os manipuladores de pagamento são configurado, o ciclo de vida do status começa, a sessão avança para a conclusão.

O fluxo típico: cart session → checkout session → order

Suporte para carrinhos:

Construção incremental: adicione/remova itens entre sessões
Estimativas localizadas: preços baseados no contexto sem sobrecarga total de checkout
Compartilhamento: continue_url permite compartilhamento e recuperação de carrinho

Carrinho vs Check-out¶

Aspecto	Carrinho	Finalizar compra
Objetivo	Exploração pré-compra	Finalização de compra
Pagamento	Nenhum	Obrigatório (manipuladores, instrumentos)
Status	Binário (existe/não encontrado)	Ciclo de Vida (`incomplete` → `completed`)
Operação Completa	Não	Sim
Totais	Estimativas (podem ser parciais)	Preço final

Conversão do carrinho para finalização da compra¶

Quando a capacidade do carrinho é negociada, as plataformas podem converter um carrinho em checkout fornecendo cart_id na solicitação Criar Checkout. O conteúdo do carrinho (line_items, context, buyer) inicializa a sessão de checkout.json { "cart_id": "cart_abc123", "line_items": [] }A empresa DEVE usar o conteúdo do carrinho e DEVE ignorar campos sobrepostos na carga útil do checkout. O parâmetro cart_id só está disponível quando a capacidade do carrinho é anunciada no perfil empresarial.

Conversão idempotente:

Caso já exista um checkout incompleto para o determinado cart_id, a empresa DEVE retornar a sessão de checkout existente em vez de criar uma nova. Isto garante um único checkout ativo por carrinho e evita sessões conflitantes.

Ciclo de vida do carrinho após a conversão:

Quando o checkout é inicializado via cart_id, o carrinho e as sessões de checkout DEVE estar vinculado durante a finalização da compra.

Durante a finalização da compra ativa — A empresa DEVE manter o carrinho e refletir modificações relevantes no checkout (alterações de quantidade, remoções de itens) de volta para o carrinho. Isso oferece suporte aos fluxos de volta à vitrine durante a transição dos compradores entre o checkout e a vitrine.
Após a conclusão da compra — A empresa PODE limpar o carrinho com base no TTL, conclusão da finalização da compra ou outra lógica de negócios. Operações subsequentes em um ID de carrinho liberado, retorne not_found; a plataforma pode iniciar um novo sessão com create_cart.

Escopos¶

O recurso Carrinho define os seguintes escopos conhecidos para acesso autenticado pelo usuário:

Escopo	Descrição
`br.dev.bcp.shopping.cart:manage`	Todas as operações do carrinho em nome do usuário autenticado – criar, ler, atualizar, persistir.

Declaração de escopo, derivação e regras para estender este conjunto com escopos personalizados são definidos em Vinculação de identidade — Escopos.

Diretrizes¶

Plataforma¶

PODE usar carrinhos para exploração pré-compra e persistência de sessão.
DEVE converter o carrinho em finalização da compra quando o usuário expressar intenção de compra.
PODE exibir continue_url para transferência para a UI comercial.
DEVE lidar com not_found normalmente quando o carrinho expira ou é cancelado.

Negócios¶

DEVERIA fornecer continue_url para transferência do carrinho e recuperação da sessão.
TODO: discuta o destino continue_url - carrinho vs checkout.
DEVE fornecer totais estimados quando calculáveis.
PODE omitir os totais de cumprimento até a finalização da compra quando o endereço for desconhecido.
DEVE retornar mensagens informativas para avisos de validação.
MAIO definir a expiração do carrinho via expires_at.
DEVE seguir requisitos de ciclo de vida do carrinho quando o checkout é inicializado via cart_id.

Definição do esquema do carrinho¶

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	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	Attribution	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.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.

Operações¶

O recurso Carrinho define as seguintes operações lógicas.

Operação	Descrição
Criar carrinho	Cria uma nova sessão de carrinho.
Obter carrinho	Recupera o estado atual de uma sessão de carrinho.
Atualizar carrinho	Atualiza uma sessão de carrinho.
Cancelar carrinho	Cancela uma sessão de carrinho.

Criar carrinho¶

Cria uma nova sessão de carrinho com itens de linha e comprador/contexto opcional informações para estimativas de preços localizadas.

Quando todos os itens solicitados estiverem indisponíveis, a empresa PODE devolver um resposta de erro em vez de criar um recurso de carrinho. ucp.status é o discriminador primário; a ausência de id é um sinal secundário consistente indicador:json { "ucp": { "version": "2026-07-14", "status": "error" }, "messages": [ { "type": "error", "code": "out_of_stock", "content": "All requested items are currently out of stock", "severity": "unrecoverable" } ], "continue_url": "https://merchant.com/" }* REST Binding (não incluído nesta versão do BCP) * Vinculação MCP

Obter carrinho¶

Recupera o estado mais recente de uma sessão de carrinho. Retorna not_found se o carrinho não existe, expirou ou foi cancelado.

REST Binding (não incluído nesta versão do BCP)
Vinculação MCP

Atualizar carrinho¶

Executa uma substituição completa da sessão do carrinho. A plataforma DEVE enviar todo o recurso do carrinho. O recurso fornecido substitui o carrinho existente estado do lado empresarial.

REST Binding (não incluído nesta versão do BCP)
Vinculação MCP

Cancelar carrinho¶

Cancela uma sessão de carrinho. A empresa DEVE retornar o estado do carrinho antes da exclusão. As operações subsequentes para este ID do carrinho DEVEM retornar not_found.

REST Binding (não incluído nesta versão do BCP)
Vinculação MCP

Entidades¶

Cart reutiliza os mesmos esquemas de entidade que Checkout. Isso garante estruturas de dados consistentes ao converter um carrinho em uma sessão de checkout.

Carrinho de resposta BCP¶

UCP metadata for cart responses. No payment handlers needed pre-checkout.

Name	Type	Required	Description
version	string	Yes	UCP version in YYYY-MM-DD format.
status	string	No	Application-level status of the UCP operation. Enum: `success`, `error`
services	object	No	Service registry keyed by reverse-domain name.
capabilities	object	No	Capability registry keyed by reverse-domain name.
payment_handlers	object	No	Payment handler registry keyed by reverse-domain name.
capabilities	any	No

Item de linha¶

Solicitação de criação de item de linha¶

Name	Type	Required	Description
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.

Solicitação de atualização de item de linha¶

Name	Type	Required	Description
id	string	No
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.
parent_id	string	No	Parent line item identifier for any nested structures.

Item de linha¶

Name	Type	Required	Description
id	string	Yes
item	Item	Yes
quantity	integer	Yes	Quantity of the item being purchased.
totals	Array[Total]	Yes	Line item totals breakdown.
parent_id	string	No	Parent line item identifier for any nested structures.

Artigo¶

Name	Type	Required	Description
id	string	Yes	The product identifier, often the SKU, required to resolve the product details associated with this line item. Should be recognized by both the Platform, and the Business.
title	string	Yes	Product title.
price	Amount	Yes	Unit price in ISO 4217 minor units.
image_url	string	No	Product image URI.

Comprador¶

Name	Type	Required	Description
first_name	string	No	First name of the buyer.
last_name	string	No	Last name of the buyer.
email	string	No	Email of the buyer.
phone_number	string	No	E.164 standard.

Contexto¶

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 privacidade requisitos.

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.

Total¶

O mesmo contrato de totais se aplica ao carrinho e ao checkout. Veja Checkout Totals para o contrato de renderização, contabilidade identidade, tipos bem conhecidos, tipos repetidos e semântica de sublinhado.

Name	Type	Required	Description
type	string	Yes	Cost category. Well-known values: subtotal, items_discount, discount, fulfillment, tax, fee, total. Businesses MAY use additional values.
display_text	string	No	Text to display against the amount. Should reflect appropriate method (e.g., 'Shipping', 'Delivery').
amount	Signed Amount	Yes	Monetary amount in the currency's minor unit as defined by ISO 4217. Refer to the currency's exponent to determine minor-to-major ratio (e.g., 2 for USD, 0 for JPY, 3 for KWD). May be negative — the sign is intrinsic to the value (e.g., discounts are negative, charges are positive).

Os impostos PODEM ser incluídos quando calculáveis. As plataformas DEVEM assumir os totais do carrinho são estimativas; impostos precisos são calculados na finalização da compra.

Mensagem¶

This object MUST be one of the following types: Message Error, Message Warning, Message Info.

Erro de mensagem¶

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`

Informações da mensagem¶

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.

Aviso de mensagem¶

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).

Ligação¶

Name	Type	Required	Description
type	string	Yes	Type of link. Well-known values: `privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`. Consumers SHOULD handle unknown values gracefully by displaying them using the `title` field or omitting the link.
url	string	Yes	The actual URL pointing to the content to be displayed.
title	string	No	Optional display text for the link. When provided, use this instead of generating from type.