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 a coleta de itens 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. Nenhuma configuração de pagamento é 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 configurados, 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.

{
  "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 a sessão de checkout DEVEM permanecer vinculados durante a finalização da compra.

Durante a finalização da compra ativa — A empresa DEVE manter o carrinho e refletir nele as modificações relevantes feitas no checkout (alterações de quantidade, remoções de itens). Isso oferece suporte a fluxos de retorno à vitrine enquanto os compradores transitam entre o checkout e a vitrine.
Após a conclusão da compra — A empresa PODE limpar o carrinho com base no TTL, na conclusão da finalização da compra ou em outra lógica de negócios. Operações subsequentes sobre um ID de carrinho liberado retornam not_found; a plataforma pode iniciar uma nova 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.
PODE 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¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item Response]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.
currency	string	Sim	Código de moeda ISO 4217. Determinado pelo lojista com base no contexto ou em geo-IP.
totals	Totals	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[Message]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[Link]	Não	Links opcionais do lojista (políticas, FAQs).
continue_url	string	Não	URL para handoff do carrinho e recuperação de sessão. Habilita compartilhamento e fluxos com humano no circuito (human-in-the-loop).
expires_at	string	Não	Timestamp de expiração do carrinho (RFC 3339). Opcional.

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 uma resposta de erro em vez de criar um recurso de carrinho. ucp.status é o discriminador primário; a ausência de id é um indicador secundário consistente:

{
  "ucp": { "version": "2026-07-28", "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 estado existente da sessão do carrinho no lado da empresa.

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¶

Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.

Nome	Tipo	Obrigatório	Descrição
version	string	Sim	Versão BCP no formato YYYY-MM-DD.
status	string	Não	Status em nível de aplicação da operação BCP. Enum: `success`, `error`
services	object	Não	Registro de serviços indexado por reverse-domain name.
capabilities	object	Não	Registro de capabilities indexado por reverse-domain name.
payment_handlers	object	Não	Registro de payment handlers indexado por reverse-domain name.
capabilities	any	Não

Item de linha¶

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

Nome	Tipo	Obrigatório	Descrição
item	Item	Sim
quantity	integer	Sim	Quantidade do item sendo comprado.

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

Nome	Tipo	Obrigatório	Descrição
id	string	Não
item	Item	Sim
quantity	integer	Sim	Quantidade do item sendo comprado.
parent_id	string	Não	Identificador do item de linha pai para quaisquer estruturas aninhadas.

Item de linha¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim
item	Item	Sim
quantity	integer	Sim	Quantidade do item sendo comprado.
totals	Array[Total]	Sim	Detalhamento dos totais do item de linha.
parent_id	string	Não	Identificador do item de linha pai para quaisquer estruturas aninhadas.

Artigo¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	O identificador do produto, muitas vezes o SKU, necessário para resolver os detalhes do produto associados a este item de linha. Deveria ser reconhecido tanto pela Plataforma quanto pelo Negócio.
title	string	Sim	Título do produto.
price	Amount	Sim	Preço unitário em unidades menores conforme ISO 4217.
image_url	string	Não	URI da imagem do produto.

Comprador¶

Nome	Tipo	Obrigatório	Descrição
first_name	string	Não	Primeiro nome do buyer.
last_name	string	Não	Sobrenome do buyer.
email	string	Não	E-mail do buyer.
phone_number	string	Não	Padrão E.164.

Contexto¶

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

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.

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.

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Categoria de custo. Valores conhecidos: subtotal, items_discount, discount, fulfillment, tax, fee, total. As empresas PODEM usar valores adicionais.
display_text	string	Não	Texto a exibir junto ao valor. Deveria refletir o método apropriado (por exemplo, 'Frete', 'Entrega').
amount	Signed Amount	Sim	Valor monetário na unidade menor da moeda, conforme definido pela ISO 4217. Consulte o expoente da moeda para determinar a razão entre unidade menor e maior (por exemplo, 2 para BRL, 2 para USD, 0 para JPY, 3 para KWD). Pode ser negativo — o sinal é intrínseco ao valor (por exemplo, descontos são negativos, cobranças são positivas).

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¶

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`

Informações da mensagem¶

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.

Aviso de mensagem¶

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

Ligação¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo do link. Valores conhecidos: `privacy_policy`, `terms_of_service`, `refund_policy`, `shipping_policy`, `faq`. Os consumidores DEVERIAM lidar de forma tolerante com valores desconhecidos, exibindo-os por meio do campo `title` ou omitindo o link.
url	string	Sim	A URL efetiva que aponta para o conteúdo a ser exibido.
title	string	Não	Texto de exibição opcional para o link. Quando fornecido, use-o em vez de gerar a partir do type.