Referência de esquema¶

Esta página fornece uma referência para todos os modelos e tipos de dados de capacidade usados dentro do BCP.

Esquemas de capacidade¶

Cart¶

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

Catalog Lookup¶

Consulta de produto/variante por identificador. Suporta recuperação em lote (lookup_catalog) e detalhe de produto único (get_product).

Catalog Search¶

Capability de busca no catálogo de produtos.

Checkout¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[Line Item]	Sim	Lista de itens de linha em checkout.
buyer	Buyer	Não	Representação do comprador.
context	Context	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	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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Totals	Sim	Diferentes totais do carrinho.
messages	Array[Message]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[Link]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	Payment	Não	Configuração de pagamento contendo handlers.
order	Order Confirmation	Não	Detalhes sobre um pedido criado para esta sessão de checkout.

Order¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[Order Line Item]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[Adjustment]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Totals	Sim	Diferentes totais do pedido.
messages	Array[Message]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	Attribution	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.

Payment¶

Nome	Tipo	Obrigatório	Descrição
instruments	Array[Payment Instrument Selected Payment Instrument]	Não	Os instrumentos de pagamento disponíveis para este pagamento. Cada instrumento é associado a um handler específico por meio do campo handler_id. Os handlers podem estender o schema base payment_instrument para adicionar campos específicos do handler.

Esquemas de tipo¶

Payment Account Info¶

Nome	Tipo	Obrigatório	Descrição
payment_account_reference	string	Não	EMVCo PAR. Um identificador único que vincula um cartão de pagamento a uma conta específica, permitindo o rastreamento entre tokens (Apple Pay, cartão físico, etc).

Adjustment¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do evento de ajuste.
type	string	Sim	Tipo de ajuste (string aberta). Normalmente relacionado a dinheiro, como: refund, return, credit, price_adjustment, dispute, cancellation. Pode ser qualquer valor que faça sentido para a empresa do merchant.
occurred_at	string	Sim	Timestamp RFC 3339 de quando este ajuste ocorreu.
status	string	Sim	Status do ajuste. Enum: `pending`, `completed`, `failed`
line_items	Array[object]	Não	Quais itens de linha e quantidades são afetados (opcional).
totals	Array[Total]	Não	Detalhamento dos totais do ajuste. Valores com sinal - negativos para dinheiro devolvido ao buyer (reembolsos, créditos), positivos para cobranças adicionais (trocas).
description	string	Não	Motivo ou descrição legível por humanos (ex.: 'Item defeituoso', 'Solicitado pelo cliente').

Amount¶

Valor monetário na menor unidade da moeda, conforme definido pela ISO 4217. Consulte o expoente da moeda para determinar a razão entre a menor e a maior unidade (ex.: 2 para BRL, 0 para JPY, 3 para KWD).

Attribution¶

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.

Available Payment Instrument¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	O identificador do tipo de instrumento (ex.: 'card', 'gift_card'). Referencia a constante type de um schema de instrumento.
constraints	object	Não	Restrições sobre este tipo de instrumento. A estrutura depende do tipo de instrumento e das capabilities ativas.

Binding¶

Nome	Tipo	Obrigatório	Descrição
checkout_id	string	Sim	O identificador da sessão de checkout à qual este token está vinculado.
identity	Payment Identity	Não	O participante ao qual este token está vinculado. Obrigatório ao agir em nome de outro participante (ex.: agente tokenizando para o merchant). Omita quando o chamador autenticado for o alvo da vinculação.

Business Fulfillment Config¶

Nome	Tipo	Obrigatório	Descrição
allows_multi_destination	object	Não	Permite múltiplos destinos por tipo de método.
allows_method_combinations	Array[array]	Não	Combinações de tipos de método permitidas.

Buyer¶

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.

Card Credential¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	O discriminador do tipo de credencial. Schemas específicos restringirão isto a um valor constante.
type	any	Sim	Constant = card. O identificador do tipo de credencial para credenciais de cartão.
card_number_type	string	Sim	O tipo do número do cartão. Network tokens são preferidos, com fallback para FPAN. Consulte PCI Scope para mais detalhes. Enum: `fpan`, `network_token`, `dpan`
number	string	Não	Número do cartão.
expiry_month	integer	Não	O mês da data de expiração do cartão (1-12).
expiry_year	integer	Não	O ano da data de expiração do cartão.
name	string	Não	Nome do titular do cartão.
cvc	string	Não	Número CVC do cartão.
cryptogram	string	Não	Criptograma fornecido com network tokens.
eci_value	string	Não	Electronic Commerce Indicator / Security Level Indicator fornecido com network tokens.

Card Payment Instrument¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Um identificador único para esta instância de instrumento, atribuído pela plataforma.
handler_id	string	Sim	O identificador único da instância de handler que produziu este instrumento. Corresponde ao campo 'id' na definição do Payment Handler.
type	string	Sim	A categoria ampla do instrumento (ex.: 'card', 'tokenized_card'). Schemas específicos restringirão isto a um valor constante.
billing_address	Postal Address	Não	O endereço de cobrança associado a este método de pagamento.
credential	Payment Credential	Não	A definição base para qualquer credencial de pagamento. Os handlers definem tipos específicos de credencial.
display	object	Não	Informações de exibição para este instrumento de pagamento. Cada schema de instrumento de pagamento define suas propriedades de exibição específicas, conforme delineado pelo payment handler.
type	string	Sim	Constant = card. Indica que este é um payment instrument de cartão.
display	object	Não	Informações de exibição para este payment instrument de cartão.

Category¶

Nome	Tipo	Obrigatório	Descrição
value	string	Sim	Valor ou caminho da categoria (ex.: 'Apparel > Shirts', '1604').
taxonomy	string	Não	Taxonomia de origem. Valores conhecidos: `google_product_category`, `shopify`, `merchant`.

Context¶

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.

Description¶

Nome	Tipo	Obrigatório	Descrição
plain	string	Não	Conteúdo em texto puro.
html	string	Não	Conteúdo formatado em HTML. Segurança: As plataformas DEVEM sanitizar antes de renderizar—remover scripts, event handlers e elementos não confiáveis. Trate todo rich text como entrada não confiável.
markdown	string	Não	Conteúdo formatado em Markdown.

Detail Option Value¶

Nome	Tipo	Obrigatório	Descrição
available	boolean	Não	Se uma variante que corresponde a este valor e às seleções de opção atuais pode ser comprada.
exists	boolean	Não	Se uma variante que corresponde a este valor e às seleções de opção atuais existe no catálogo.

Error Code¶

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.

Error Response¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados do protocolo BCP. O status DEVE ser 'error' para uma resposta de erro.
messages	Array[Message]	Sim	Array de mensagens descrevendo por que a operação falhou.
continue_url	string	Não	URL para handoff do buyer ou recuperação da sessão.

Expectation¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da expectativa.
line_items	Array[object]	Sim	Quais itens de linha e quantidades estão nesta expectativa.
method_type	string	Sim	Tipo de método de entrega (shipping, pickup, digital). Enum: `shipping`, `pickup`, `digital`
destination	Postal Address	Sim	Endereço de destino da entrega.
description	string	Não	Descrição de entrega legível por humanos (ex.: 'Chega em 5-8 dias úteis').
fulfillable_on	string	Não	Quando esta expectativa pode ser cumprida: 'now' ou timestamp ISO 8601 para data futura (backorder, pré-venda).

Fulfillment¶

Nome	Tipo	Obrigatório	Descrição
methods	Array[Fulfillment Method]	Não	Métodos de fulfillment para os itens do cart.
available_methods	Array[Fulfillment Available Method]	Não	Dicas de disponibilidade de estoque.

Fulfillment Available Method¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de método de fulfillment ao qual esta disponibilidade se aplica. Enum: `shipping`, `pickup`
line_item_ids	Array[string]	Sim	Itens de linha disponíveis para este método de fulfillment.
fulfillable_on	['string', 'null']	Não	'now' para disponibilidade imediata, ou data ISO 8601 para o futuro (pré-vendas, transferências).
description	string	Não	Informação de disponibilidade legível por humanos (ex.: 'Disponível para pickup na Loja Centro hoje').

Fulfillment Destination¶

This object MUST be one of the following types: Shipping Destination, Retail Location.

Fulfillment Event¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do evento de fulfillment.
occurred_at	string	Sim	Timestamp RFC 3339 de quando este evento de fulfillment ocorreu.
type	string	Sim	Tipo de evento de fulfillment. Valores comuns incluem: processing (preparando para envio), shipped (entregue à transportadora), in_transit (na rede de entrega), delivered (recebido pelo buyer), failed_attempt (tentativa de entrega falhou), canceled (fulfillment cancelado), undeliverable (não pode ser entregue), returned_to_sender (devolvido ao merchant).
line_items	Array[object]	Sim	Quais itens de linha e quantidades são cumpridos neste evento.
tracking_number	string	Não	Número de rastreamento da transportadora (obrigatório se type != processing).
tracking_url	string	Não	URL para rastrear este envio (obrigatório se type != processing).
carrier	string	Não	Nome da transportadora (ex.: 'Correios', 'Jadlog').
description	string	Não	Descrição legível por humanos do status do envio ou informação de entrega (ex.: 'Entregue na porta da frente', 'Saiu para entrega').

Fulfillment Group¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do grupo para referenciar grupos gerados pelo lojista em atualizações.
line_item_ids	Array[string]	Sim	IDs dos itens de linha incluídos neste grupo/pacote.
options	Array[Fulfillment Option]	Não	Opções de fulfillment disponíveis para este grupo.
selected_option_id	['string', 'null']	Não	ID da opção de fulfillment selecionada para este grupo.

Fulfillment Method¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do método de fulfillment.
type	string	Sim	Tipo do método de fulfillment. Enum: `shipping`, `pickup`
line_item_ids	Array[string]	Sim	IDs dos itens de linha atendidos por este método.
destinations	Array[Fulfillment Destination]	Não	Destinos disponíveis. Para shipping: endereços. Para pickup: locais de retirada.
selected_destination_id	['string', 'null']	Não	ID do destino selecionado.
groups	Array[Fulfillment Group]	Não	Grupos de fulfillment para selecionar opções. O agente define selected_option_id nos grupos para escolher o método de shipping.

Fulfillment Option¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único da opção de fulfillment.
title	string	Sim	Rótulo curto (ex.: 'Frete Expresso', 'Retirada no Balcão').
description	string	Não	Contexto completo para a decisão do comprador (ex.: 'Chega entre 12 e 15 de dez via FedEx').
carrier	string	Não	Nome da transportadora (para shipping).
earliest_fulfillment_time	string	Não	Data mais próxima de fulfillment.
latest_fulfillment_time	string	Não	Data mais distante de fulfillment.
totals	Array[Total]	Sim	Detalhamento dos totais da opção de fulfillment.

Info Code¶

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.

Input Correlation¶

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.

Item¶

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.

Line Item¶

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.

Link¶

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.

Media¶

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

Merchant Fulfillment Config¶

Nome	Tipo	Obrigatório	Descrição
allows_multi_destination	object	Não	Permite múltiplos destinos por tipo de método.
allows_method_combinations	Array[array]	Não	Combinações de tipos de método permitidas.

Message¶

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

Message Error¶

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`

Message Info¶

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.

Message Warning¶

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

NCM¶

Classificação fiscal Nomenclatura Comum do Mercosul (NCM) de um produto, 8 dígitos. Orienta o cálculo de tributos, a marcação de categoria do Imposto Seletivo e a emissão de NF-e (ex.: '33049910').

Padrão: ^[0-9]{8}$

Option Value¶

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

Order Confirmation¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.

Order Line Item¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do item de linha.
item	Item	Sim	Dados do produto (id, title, price, image_url).
quantity	object	Sim	Rastreamento de quantidade para o item de linha.
totals	Array[Total]	Sim	Detalhamento dos totais do item de linha.
status	string	Sim	Status derivado: removed se quantity.total == 0, fulfilled se quantity.total > 0 e quantity.fulfilled == quantity.total, partial se quantity.total > 0 e quantity.fulfilled > 0, caso contrário processing. Enum: `processing`, `partial`, `fulfilled`, `removed`
parent_id	string	Não	Identificador do item de linha pai para quaisquer estruturas aninhadas.

Pagination¶

Paginação baseada em cursor para operações de listagem.

Payment Credential¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	O discriminador do tipo de credencial. Schemas específicos restringirão isto a um valor constante.

Payment Identity¶

Nome	Tipo	Obrigatório	Descrição
access_token	string	Sim	Identificador único deste participante, obtido durante o onboarding com o tokenizer.

Payment Instrument¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Um identificador único para esta instância de instrumento, atribuído pela plataforma.
handler_id	string	Sim	O identificador único da instância de handler que produziu este instrumento. Corresponde ao campo 'id' na definição do Payment Handler.
type	string	Sim	A categoria ampla do instrumento (ex.: 'card', 'tokenized_card'). Schemas específicos restringirão isto a um valor constante.
billing_address	Postal Address	Não	O endereço de cobrança associado a este método de pagamento.
credential	Payment Credential	Não	A definição base para qualquer credencial de pagamento. Os handlers definem tipos específicos de credencial.
display	object	Não	Informações de exibição para este instrumento de pagamento. Cada schema de instrumento de pagamento define suas propriedades de exibição específicas, conforme delineado pelo payment handler.

Platform Fulfillment Config¶

Nome	Tipo	Obrigatório	Descrição
supports_multi_group	boolean	Não	Habilita múltiplos grupos por método.

Postal Address¶

Nome	Tipo	Obrigatório	Descrição
extended_address	string	Não	Um complemento de endereço, como número de apartamento, A/C ou nome alternativo.
street_address	string	Não	O logradouro.
address_locality	string	Não	A localidade em que o logradouro está, e que está na região. Por exemplo, São Paulo.
address_region	string	Não	A região em que a localidade está, e que está no país. Obrigatório para países aplicáveis (por exemplo, estado no BR, província no CA). Por exemplo, São Paulo ou outra divisão administrativa de primeiro nível apropriada.
address_country	string	Não	O país. RECOMENDADO estar no formato ISO 3166-1 alpha-2 de 2 letras, por exemplo "BR". Para compatibilidade retroativa, também PODE ser usado um código de país ISO 3166-1 alpha-3 de 3 letras, como "BRA", ou o nome completo do país, como "Brasil".
postal_code	string	Não	O código postal (CEP). Por exemplo, 01310-100.
first_name	string	Não	Opcional. Nome do contato associado ao endereço.
last_name	string	Não	Opcional. Sobrenome do contato associado ao endereço.
phone_number	string	Não	Opcional. Número de telefone do contato associado ao endereço.

Price¶

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

Nome	Tipo	Obrigatório	Descrição
min	Amount	Não	Preço mínimo em unidades menores ISO 4217.
max	Amount	Não	Preço máximo em unidades menores ISO 4217.

Price Range¶

Nome	Tipo	Obrigatório	Descrição
min	Price	Sim	Preço mínimo da faixa.
max	Price	Sim	Preço máximo da faixa.

Product¶

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.

Product Option¶

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.

Rating¶

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.

Retail Location¶

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do local.
name	string	Sim	Nome do local (por exemplo, nome da loja).
address	Postal Address	Não	Endereço físico do local.

Business Returns Config¶

Nome	Tipo	Obrigatório	Descrição
withdrawal_period_days	integer	Não	Prazo de desistência em dias corridos a partir da entrega confirmada (o evento de fulfillment `delivered`). Os vendedores PODEM oferecer mais que o mínimo.
request_channel	string	Não	Canal onde o consumidor exerce a devolução; DEVE incluir o mesmo canal usado para a compra. Formato livre: URL, e-mail ou identificador de canal.

Reverse Domain Name¶

Identificador em domínio reverso usado para namespacing seguro contra colisões de capabilities, serviços, handlers, declarações de elegibilidade e chaves contribuídas por extensões. Deve conter pelo menos dois segmentos separados por ponto (por exemplo, 'br.dev.bcp.shopping.checkout', 'com.example.loyalty_gold').

Padrão: ^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_]*)+$

Nome	Tipo	Obrigatório	Descrição
categories	Array[string]	Não	Filtra por categorias de produto (lógica OR — corresponde a produtos em qualquer das categorias listadas). Os valores correspondem ao campo value nas entradas de categoria do produto. Valores válidos podem ser descobertos a partir do campo categories nos resultados de busca, da documentação do lojista ou de taxonomias padrão às quais as empresas podem se alinhar.
price	Price Filter	Não	Filtro de faixa de preço denominado em context.currency. Quando context.currency corresponde à moeda de apresentação, as empresas aplicam o filtro diretamente. Quando difere, as empresas DEVERIAM converter os valores do filtro para a moeda de apresentação antes de aplicar; se a conversão não for suportada, as empresas PODEM ignorar o filtro e DEVERIAM indicar isso por meio de uma mensagem. Quando context.currency está ausente, a denominação do filtro é ambígua e as empresas PODEM ignorá-lo.

Selected Option¶

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

Shipping Destination¶

Nome	Tipo	Obrigatório	Descrição
extended_address	string	Não	Um complemento de endereço, como número de apartamento, A/C ou nome alternativo.
street_address	string	Não	O logradouro.
address_locality	string	Não	A localidade em que o logradouro está, e que está na região. Por exemplo, São Paulo.
address_region	string	Não	A região em que a localidade está, e que está no país. Obrigatório para países aplicáveis (por exemplo, estado no BR, província no CA). Por exemplo, São Paulo ou outra divisão administrativa de primeiro nível apropriada.
address_country	string	Não	O país. RECOMENDADO estar no formato ISO 3166-1 alpha-2 de 2 letras, por exemplo "BR". Para compatibilidade retroativa, também PODE ser usado um código de país ISO 3166-1 alpha-3 de 3 letras, como "BRA", ou o nome completo do país, como "Brasil".
postal_code	string	Não	O código postal (CEP). Por exemplo, 01310-100.
first_name	string	Não	Opcional. Nome do contato associado ao endereço.
last_name	string	Não	Opcional. Sobrenome do contato associado ao endereço.
phone_number	string	Não	Opcional. Número de telefone do contato associado ao endereço.
id	string	Sim	ID específico deste destino de envio.

Signals¶

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.

Signed Amount¶

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

Token Credential¶

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	O discriminador do tipo de credencial. Schemas específicos restringirão isto a um valor constante.
type	string	Sim	O tipo específico de token produzido pelo handler (por exemplo, 'stripe_token').
token	string	Sim	O valor do token.

Total¶

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

Totals¶

Detalhamento de preços fornecido pela empresa. DEVE conter exatamente uma entrada subtotal e uma entrada total. Tipos de detalhe (tax, fee, discount, fulfillment) podem aparecer várias vezes para itemização. As plataformas DEVEM renderizar todas as entradas em ordem usando display_text e amount.

Variant¶

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.

Warning Code¶

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.

Instrumento de pagamento selecionado¶

Um instrumento de pagamento com estado de seleção.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Um identificador único para esta instância de instrumento, atribuído pela plataforma.
handler_id	string	Sim	O identificador único da instância de handler que produziu este instrumento. Corresponde ao campo 'id' na definição do Payment Handler.
type	string	Sim	A categoria ampla do instrumento (ex.: 'card', 'tokenized_card'). Schemas específicos restringirão isto a um valor constante.
billing_address	object	Não	O endereço de cobrança associado a este método de pagamento.
credential	object	Não	A definição base para qualquer credencial de pagamento. Os handlers definem tipos específicos de credencial.
display	object	Não	Informações de exibição para este instrumento de pagamento. Cada schema de instrumento de pagamento define suas propriedades de exibição específicas, conforme delineado pelo payment handler.
selected	boolean	Não	Se este instrumento está selecionado pelo usuário.

Solicitação de paginação¶

Parâmetros de paginação para requisições.

Nome	Tipo	Obrigatório	Descrição
cursor	string	Não	Cursor opaco da resposta anterior.
limit	integer	Não	Tamanho de página solicitado. As implementações PODEM limitar a um máximo menor.

Resposta de paginação¶

Informações de paginação nas respostas.

Nome	Tipo	Obrigatório	Descrição
cursor	string	Não	Cursor para buscar a próxima página de resultados. DEVE estar presente quando has_next_page for true.
has_next_page	boolean	Sim	Se há mais resultados disponíveis.
total_count	integer	Não	Número total de itens correspondentes, se disponível.

Código de erro¶

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.

Código de aviso¶

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.

Código de informaçã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.

Esquemas de extensão¶

AP2 Mandate Extension¶

Merchant Authorization¶

Assinatura JWS Detached Content (RFC 7515 Appendix F) sobre o corpo da resposta do checkout (excluindo o campo ap2). Formato: <base64url-header>..<base64url-signature>. O cabeçalho DEVE conter as claims 'alg' (ES256/ES384/ES512) e 'kid'. A assinatura cobre tanto o cabeçalho quanto o payload do checkout canonizado por JCS.

Padrão: ^[A-Za-z0-9_-]+\.\.[A-Za-z0-9_-]+$

Checkout Mandate¶

Credencial SD-JWT+kb em ap2.checkout_mandate. Comprova a autorização do usuário para o checkout. Contém o checkout completo, incluindo ap2.merchant_authorization.

Padrão: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+(~[A-Za-z0-9_-]+)*$

Ap2 With Merchant Authorization¶

Dados da extensão AP2, incluindo a autorização do lojista.

Nome	Tipo	Obrigatório	Descrição
merchant_authorization	string	Não	Assinatura do lojista comprovando que os termos do checkout são autênticos.

Ap2 With Checkout Mandate¶

Dados da extensão AP2, incluindo o mandato de checkout.

Nome	Tipo	Obrigatório	Descrição
checkout_mandate	string	Não	SD-JWT+kb comprovando que o usuário autorizou este checkout.

Checkout with AP2 Mandate¶

Checkout estendido com suporte a mandato AP2.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
ap2	any	Não

AP2 Error Code¶

Códigos de erro específicos da verificação de mandato AP2.

Enum: mandate_required, agent_missing_key, mandate_invalid_signature, mandate_expired, mandate_scope_mismatch, merchant_authorization_invalid, merchant_authorization_missing

Estados de consentimento do usuário para o processamento de dados

Nome	Tipo	Obrigatório	Descrição
analytics	boolean	Não	Consentimento para analytics e rastreamento de desempenho.
preferences	boolean	Não	Consentimento para armazenar as preferências do usuário.
marketing	boolean	Não	Consentimento para comunicações de marketing.
sale_of_data	boolean	Não	Consentimento para venda de dados a terceiros (CCPA).

Objeto buyer estendido com rastreamento de consentimento.

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.
consent	object	Não	Campos de rastreamento de consentimento.

Checkout estendido com rastreamento de consentimento por meio do objeto buyer.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
buyer	any	Não	Comprador com rastreamento de consentimento.

Discount Extension¶

Allocation¶

Detalhamento de como um valor de desconto foi alocado a um alvo específico.

Nome	Tipo	Obrigatório	Descrição
path	string	Sim	JSONPath para o alvo da alocação (ex.: '$.line_items[0]', '$.totals.shipping').
amount	integer	Sim	Valor alocado a este alvo em unidades menores ISO 4217.

Applied Discount¶

Um desconto que foi aplicado com sucesso.

Nome	Tipo	Obrigatório	Descrição
code	string	Não	O código de desconto. Omitido para descontos automáticos.
title	string	Sim	Nome do desconto legível por humanos (ex.: 'Summer Sale 20% Off').
amount	integer	Sim	Valor total do desconto em unidades menores ISO 4217.
automatic	boolean	Não	Verdadeiro se aplicado automaticamente por regras do lojista (sem necessidade de código).
method	string	Não	Método de alocação. 'each' = aplicado independentemente por item. 'across' = dividido proporcionalmente por valor. Enum: `each`, `across`
priority	integer	Não	Ordem de empilhamento para o cálculo do desconto. Números menores são aplicados primeiro (1 = primeiro).
provisional	boolean	Não	Verdadeiro se este desconto requer verificação adicional.
eligibility	string	Não	A claim de elegibilidade aceita pela Empresa para este desconto. Corresponde a um valor de context.eligibility. Omitida para descontos baseados em código e automáticos não relacionados a elegibilidade.
allocations	Array[object]	Não	Detalhamento de onde este desconto foi alocado. A soma dos valores de alocação é igual ao valor total.

Discounts Object¶

Entrada de códigos de desconto e saída de descontos aplicados.

Nome	Tipo	Obrigatório	Descrição
codes	Array[string]	Não	Códigos de desconto a aplicar. Não diferencia maiúsculas de minúsculas. Substitui os códigos enviados anteriormente. Envie um array vazio para limpar.
applied	Array[object]	Não	Descontos aplicados com sucesso (baseados em código e automáticos).

Cart with Discount¶

Carrinho estendido com a capability de desconto.

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[object]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	object	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	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.
buyer	object	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	Array[Total]	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[object]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[object]	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.
discounts	object	Não	Entrada de códigos de desconto e saída de descontos aplicados.

Checkout with Discount¶

Checkout estendido com a capability de desconto.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
discounts	object	Não	Entrada de códigos de desconto e saída de descontos aplicados.

Fiscal Identity Extension¶

Taxpayer Id¶

Identificador de contribuinte brasileiro do comprador (o destinatário da NF-e). Obrigatório para a emissão da nota (NF-e).

Nome	Tipo	Obrigatório	Descrição
kind	string	Sim	Tipo de identificador de contribuinte. Conjunto fechado espelhando a identificação do destinatário na NF-e: `cpf` (pessoa física), `cnpj` (pessoa jurídica), `id_estrangeiro` (comprador estrangeiro sem CPF/CNPJ; mapeia para o campo `idEstrangeiro` da NF-e). Enum: `cpf`, `cnpj`, `id_estrangeiro`
value	string	Sim	Valor do identificador, sem pontuação. O formato depende de `kind`: CPF 11 dígitos, CNPJ 14 (alfanumérico a partir de 2026), id_estrangeiro em formato livre.

Seller Identity¶

Identidade da empresa vendedor. DEVE estar presente em toda resposta de checkout e de order para que o consumidor possa identificar e contatar o vendedor.

Nome	Tipo	Obrigatório	Descrição
cnpj	string	Sim	CNPJ do vendedor, 14 caracteres, sem pontuação (alfanumérico a partir de 2026). Emissor da nota.
legal_name	string	Sim	Razão social registrada da empresa.
address	object	Não	Endereço físico da empresa.

Buyer with Taxpayer ID¶

Objeto buyer estendido com o identificador de contribuinte brasileiro.

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.
taxpayer_id	object	Não	Identificador de contribuinte do comprador. Fornecido na conclusão quando uma NF-e for emitida para a venda.

Checkout with Fiscal Identity¶

Checkout estendido com o identificador de contribuinte do comprador e a identidade obrigatória do vendedor.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
buyer	any	Não	Comprador com identificador de contribuinte.
seller_identity	object	Sim	Identidade da empresa vendedor. DEVE estar presente em toda resposta de checkout e de order para que o consumidor possa identificar e contatar o vendedor.

Order with Fiscal Identity¶

Order estendido com a identidade obrigatória do vendedor, congelando a identidade do fornecedor no registro durável da transação.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[object]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[object]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Array[Total]	Sim	Diferentes totais do pedido.
messages	Array[object]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	object	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.
seller_identity	object	Sim	Identidade da empresa vendedor. DEVE estar presente em toda resposta de checkout e de order para que o consumidor possa identificar e contatar o vendedor.

Fulfillment Extension¶

Fulfillment Option¶

Uma opção de fulfillment dentro de um grupo (ex.: Frete Padrão R$ 5, Expresso R$ 15).

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único da opção de fulfillment.
title	string	Sim	Rótulo curto (ex.: 'Frete Expresso', 'Retirada no Balcão').
description	string	Não	Contexto completo para a decisão do comprador (ex.: 'Chega entre 12 e 15 de dez via FedEx').
carrier	string	Não	Nome da transportadora (para shipping).
earliest_fulfillment_time	string	Não	Data mais próxima de fulfillment.
latest_fulfillment_time	string	Não	Data mais distante de fulfillment.
totals	Array[object]	Sim	Detalhamento dos totais da opção de fulfillment.

Fulfillment Group¶

Um pacote/grupo de itens de linha gerado pelo lojista, com opções de fulfillment.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do grupo para referenciar grupos gerados pelo lojista em atualizações.
line_item_ids	Array[string]	Sim	IDs dos itens de linha incluídos neste grupo/pacote.
options	Array[object]	Não	Opções de fulfillment disponíveis para este grupo.
selected_option_id	['string', 'null']	Não	ID da opção de fulfillment selecionada para este grupo.

Fulfillment Method¶

Um método de fulfillment (shipping ou pickup) com destinos e grupos.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do método de fulfillment.
type	string	Sim	Tipo do método de fulfillment. Enum: `shipping`, `pickup`
line_item_ids	Array[string]	Sim	IDs dos itens de linha atendidos por este método.
destinations	Array[object]	Não	Destinos disponíveis. Para shipping: endereços. Para pickup: locais de retirada.
selected_destination_id	['string', 'null']	Não	ID do destino selecionado.
groups	Array[object]	Não	Grupos de fulfillment para selecionar opções. O agente define selected_option_id nos grupos para escolher o método de shipping.

Fulfillment Available Method¶

Dica de disponibilidade de estoque para um tipo de método de fulfillment.

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de método de fulfillment ao qual esta disponibilidade se aplica. Enum: `shipping`, `pickup`
line_item_ids	Array[string]	Sim	Itens de linha disponíveis para este método de fulfillment.
fulfillable_on	['string', 'null']	Não	'now' para disponibilidade imediata, ou data ISO 8601 para o futuro (pré-vendas, transferências).
description	string	Não	Informação de disponibilidade legível por humanos (ex.: 'Disponível para pickup na Loja Centro hoje').

Fulfillment¶

Contêiner para métodos de fulfillment e disponibilidade.

Nome	Tipo	Obrigatório	Descrição
methods	Array[object]	Não	Métodos de fulfillment para os itens do cart.
available_methods	Array[object]	Não	Dicas de disponibilidade de estoque.

Checkout with Fulfillment¶

Checkout estendido com fulfillment hierárquico.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
fulfillment	object	Não	Detalhes de fulfillment.

Br.Dev.Bcp.Shopping.Fulfillment¶

Nenhuma propriedade definida.

NF-e Extension¶

Nfe¶

Referência ao documento fiscal emitido: apenas os identificadores do documento.

Nome	Tipo	Obrigatório	Descrição
access_key	string	Sim	Chave de acesso da NF-e, 44 dígitos. Identifica o documento de forma única na SEFAZ.
danfe_url	string	Não	URL do DANFE (documento auxiliar legível por humanos, PDF).
xml_url	string	Não	URL do documento XML autorizado.
issued_at	string	Não	Timestamp de emissão RFC 3339.

Order with NF-e¶

Order estendido com a referência do documento fiscal.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[object]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[object]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Array[Total]	Sim	Diferentes totais do pedido.
messages	Array[object]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	object	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.
nfe	object	Não	Referência à NF-e emitida para este pedido. Ausente enquanto ainda não emitida, ou quando o vendedor é isento (MEI vendendo a pessoa física).

Returns Extension¶

Return Adjustment¶

Um ajuste pós-pedido do tipo return estendido com os timestamps legais brasileiros e os dados de logística reversa.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do evento de ajuste.
type	string	Sim	Tipo de ajuste (string aberta). Normalmente relacionado a dinheiro, como: refund, return, credit, price_adjustment, dispute, cancellation. Pode ser qualquer valor que faça sentido para a empresa do merchant.
occurred_at	string	Sim	Timestamp RFC 3339 de quando este ajuste ocorreu.
status	string	Sim	Status do ajuste. Enum: `pending`, `completed`, `failed`
line_items	Array[object]	Não	Quais itens de linha e quantidades são afetados (opcional).
totals	Array[object]	Não	Detalhamento dos totais do ajuste. Valores com sinal - negativos para dinheiro devolvido ao buyer (reembolsos, créditos), positivos para cobranças adicionais (trocas).
description	string	Não	Motivo ou descrição legível por humanos (ex.: 'Item defeituoso', 'Solicitado pelo cliente').
type	any	Sim	Constant = return.
reason	string	Não	Motivo da devolução. Valores conhecidos: `withdrawal` (arrependimento, sem necessidade de justificativa), `defect` (defeito do produto), `wrong_product`. Vocabulário aberto.
acknowledged_at	string	Não	Timestamp RFC 3339 de quando o vendedor confirmou o recebimento da solicitação.
reverse_shipping_code	string	Não	Código de postagem da logística reversa (ex.: autorização de postagem reversa dos Correios) para o consumidor devolver o produto.
carrier	string	Não	Transportadora responsável pelo envio reverso.
deadline	string	Não	Prazo para o consumidor entregar o produto à transportadora.

Refund Adjustment¶

Um ajuste pós-pedido do tipo refund. Seus totais são sempre negativos, representando dinheiro devolvido ao comprador.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do evento de ajuste.
type	string	Sim	Tipo de ajuste (string aberta). Normalmente relacionado a dinheiro, como: refund, return, credit, price_adjustment, dispute, cancellation. Pode ser qualquer valor que faça sentido para a empresa do merchant.
occurred_at	string	Sim	Timestamp RFC 3339 de quando este ajuste ocorreu.
status	string	Sim	Status do ajuste. Enum: `pending`, `completed`, `failed`
line_items	Array[object]	Não	Quais itens de linha e quantidades são afetados (opcional).
totals	Array[object]	Não	Detalhamento dos totais do ajuste. Valores com sinal - negativos para dinheiro devolvido ao buyer (reembolsos, créditos), positivos para cobranças adicionais (trocas).
description	string	Não	Motivo ou descrição legível por humanos (ex.: 'Item defeituoso', 'Solicitado pelo cliente').
type	any	Sim	Constant = refund.
totals	any	Não

Order Adjustment with Return Support¶

Ajuste pós-pedido. Ajustes de devolução carregam os campos legais e de logística reversa brasileiros; ajustes de reembolso carregam totais negativos; qualquer ajuste pode referenciar outros relacionados por causalidade.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do evento de ajuste.
type	string	Sim	Tipo de ajuste (string aberta). Normalmente relacionado a dinheiro, como: refund, return, credit, price_adjustment, dispute, cancellation. Pode ser qualquer valor que faça sentido para a empresa do merchant.
occurred_at	string	Sim	Timestamp RFC 3339 de quando este ajuste ocorreu.
status	string	Sim	Status do ajuste. Enum: `pending`, `completed`, `failed`
line_items	Array[object]	Não	Quais itens de linha e quantidades são afetados (opcional).
totals	Array[object]	Não	Detalhamento dos totais do ajuste. Valores com sinal - negativos para dinheiro devolvido ao buyer (reembolsos, créditos), positivos para cobranças adicionais (trocas).
description	string	Não	Motivo ou descrição legível por humanos (ex.: 'Item defeituoso', 'Solicitado pelo cliente').
related_adjustment_ids	Array[string]	Não	Identificadores de ajustes relacionados por causalidade. Um reembolso causado por uma devolução referencia aqui o ajuste de devolução.

Order with Returns¶

Order cujos ajustes pós-pedido carregam os campos brasileiros de devolução.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[object]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[object]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Array[Total]	Sim	Diferentes totais do pedido.
messages	Array[object]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	object	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.
adjustments	Array[Adjustment]	Não	Eventos pós-pedido. Ajustes de devolução carregam os dados legais e de logística reversa; os demais tipos de ajuste mantêm sua forma base.

Br.Dev.Bcp.Shopping.Returns¶

Nenhuma propriedade definida.

Tax Extension¶

Tax Detail¶

Uma única incidência tributária sobre um item de linha.

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de imposto. Valores conhecidos: `icms`, `icms_st`, `difal`, `fcp`, `iss`, `ipi`, `pis`, `cofins` (sistema atual); `ibs`, `cbs`, `is` (reforma tributária de 2026+). Vocabulário aberto: os clientes DEVEM tolerar valores desconhecidos à medida que a transição (2026-2033) altera a composição.
rate	number	Não	Alíquota aplicada como fração decimal (ex.: 0.009 para 0,9%). Indicativa: `amount` é autoritativo, e os clientes NÃO DEVEM recalculá-lo a partir de `base` e `rate`.
base	integer	Não	Base de cálculo para esta incidência. PODE diferir do preço do item de linha, já que um imposto calculado sobre uma base líquida ainda chega ao consumidor dentro de um preço com imposto incluso.
amount	integer	Sim	Valor de imposto devido para esta incidência.
authority	string	Não	Nível federativo que este imposto financia, exposto para que o consumidor veja quanto do preço vai para cada nível. Valores conhecidos: `federal`, `state`, `municipal`. Um imposto compartilhado entre níveis (ex.: IBS) DEVE ser reportado como uma entrada por nível, cada uma com sua própria alíquota e valor. Vocabulário aberto: os clientes DEVEM tolerar valores desconhecidos à medida que a transição de 2026-2033 altera a composição.
behavior	string	Sim	Onde o valor se situa em relação ao preço do item de linha, que é o que permite a um cliente conciliar `totals`. Valores conhecidos: `inclusive` (o valor já está contido no preço, portanto NÃO DEVE ser somado ao subtotal) e `exclusive` (o valor é cobrado sobre o preço). As empresas DEVEM declará-lo em cada entrada: um item de linha pode carregar ambos os comportamentos ao mesmo tempo durante a transição. Vocabulário aberto: os clientes DEVEM tolerar valores desconhecidos.

Line Item with Taxes¶

Item de linha do checkout estendido com classificação fiscal e detalhamento tributário.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim
item	object	Sim
quantity	integer	Sim	Quantidade do item sendo comprado.
totals	Array[object]	Sim	Detalhamento dos totais do item de linha.
parent_id	string	Não	Identificador do item de linha pai para quaisquer estruturas aninhadas.
ncm	string	Não	Classificação fiscal Nomenclatura Comum do Mercosul (NCM) de um produto, 8 dígitos. Orienta o cálculo de tributos, a marcação de categoria do Imposto Seletivo e a emissão de NF-e (ex.: '33049910').
taxes	Array[object]	Não	Detalhamento tributário para este item de linha. Uma entrada por incidência tributária.

Order Line Item with Taxes¶

Item de linha do pedido estendido com classificação fiscal e detalhamento tributário.

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do item de linha.
item	object	Sim	Dados do produto (id, title, price, image_url).
quantity	object	Sim	Rastreamento de quantidade para o item de linha.
totals	Array[object]	Sim	Detalhamento dos totais do item de linha.
status	string	Sim	Status derivado: removed se quantity.total == 0, fulfilled se quantity.total > 0 e quantity.fulfilled == quantity.total, partial se quantity.total > 0 e quantity.fulfilled > 0, caso contrário processing. Enum: `processing`, `partial`, `fulfilled`, `removed`
parent_id	string	Não	Identificador do item de linha pai para quaisquer estruturas aninhadas.
ncm	string	Não	Classificação fiscal Nomenclatura Comum do Mercosul (NCM) de um produto, 8 dígitos. Orienta o cálculo de tributos, a marcação de categoria do Imposto Seletivo e a emissão de NF-e (ex.: '33049910').
taxes	Array[object]	Não	Detalhamento tributário para este item de linha. Uma entrada por incidência tributária.

Checkout with Tax¶

Checkout estendido com o detalhamento tributário brasileiro. Quando esta capability está ativa, as respostas DEVEM incluir ao menos uma entrada tax em totals com o valor total aproximado de imposto.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de checkout.
id	string	Sim	Identificador único da sessão de checkout.
line_items	Array[object]	Sim	Lista de itens de linha em checkout.
buyer	object	Não	Representação do comprador.
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.
status	string	Sim	Estado do checkout indicando a fase atual e a ação requerida. Consulte a documentação do ciclo de vida de Checkout Status para detalhes de transição de estado. Enum: `incomplete`, `requires_escalation`, `ready_for_complete`, `complete_in_progress`, `completed`, `canceled`
currency	string	Sim	Código de moeda ISO 4217 refletindo a determinação de mercado do lojista. Derivado de address, context e geo-IP — os compradores fornecem sinais, os lojistas determinam a moeda.
totals	Array[Total]	Sim	Diferentes totais do carrinho.
messages	Array[object]	Não	Lista de mensagens com erro e informação sobre o estado da sessão de checkout.
links	Array[object]	Sim	Links a serem exibidos pela plataforma (Política de Privacidade, Termos de Uso). Obrigatórios para conformidade legal.
expires_at	string	Não	Timestamp de expiração RFC 3339. O TTL padrão é de 6 horas a partir da criação, se não enviado.
continue_url	string	Não	URL para handoff do checkout e recuperação de sessão. DEVE ser fornecida quando o status for requires_escalation. Consulte a especificação para os requisitos de formato e disponibilidade.
payment	object	Não	Configuração de pagamento contendo handlers.
order	object	Não	Detalhes sobre um pedido criado para esta sessão de checkout.
line_items	Array[Line Item]	Sim

Order with Tax¶

Order estendido com o detalhamento tributário brasileiro, congelando o detalhe de imposto no registro durável da transação. As respostas DEVEM incluir ao menos uma entrada tax em totals.

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[object]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[object]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Array[Total]	Sim	Diferentes totais do pedido.
messages	Array[object]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	object	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.
line_items	Array[Order Line Item]	Sim

Esquemas de manipulador de pagamento¶

Metadados BCP ¶

Os esquemas a seguir definem a estrutura dos metadados BCP usados na descoberta e respostas.

Perfil de descoberta de plataforma¶

A estrutura de nível superior de um documento de perfil de plataforma (hospedado em um URI anunciado pela plataforma).

Metadados BCP completos para configuração em nível de plataforma. Hospedados em uma URI anunciada pela plataforma nos cabeçalhos da requisição.

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	Sim	Registro de serviços indexado por reverse-domain name.
capabilities	object	Não	Registro de capabilities indexado por reverse-domain name.
payment_handlers	object	Sim	Registro de payment handlers indexado por reverse-domain name.
services	any	Sim
capabilities	any	Não
payment_handlers	any	Sim

Perfil de descoberta de negócios¶

A estrutura de nível superior de um documento de descoberta de negócios (/.well-known/bcp).

Metadados BCP para configuração em nível de empresa/lojista. Subconjunto do schema de plataforma com configurações específicas da empresa.

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	Sim	Registro de serviços indexado por reverse-domain name.
capabilities	object	Não	Registro de capabilities indexado por reverse-domain name.
payment_handlers	object	Sim	Registro de payment handlers indexado por reverse-domain name.
supported_versions	object	Não	Versões anteriores de protocolo que esta empresa suporta, mapeadas para URIs de perfil. Empresas que suportam versões de protocolo mais antigas DEVERIAM anunciar cada versão e vincular ao seu perfil. Cada URI aponta para um perfil completo e autocontido daquela versão. Quando omitido, apenas `version` é suportada.
services	any	Sim
capabilities	any	Não
payment_handlers	any	Sim

Metadados de resposta de checkout¶

O objeto ucp incluído nas respostas de checkout.

Metadados BCP para respostas de 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	Sim	Registro de payment handlers indexado por reverse-domain name.
services	any	Não
capabilities	any	Não
payment_handlers	any	Sim

Metadados de resposta do carrinho¶

O objeto ucp incluído nas respostas do carrinho.

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

Metadados de resposta do catálogo¶

O objeto ucp incluído nas respostas do catálogo.

Metadados BCP para respostas de catálogo.

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

Metadados de resposta do pedido¶

O objeto ucp incluído em respostas de pedidos ou eventos.

Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.

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

Capacidade¶

Este objeto descreve um único recurso ou extensão. Aparece na matriz capabilities em perfis de descoberta e respostas, com campos obrigatórios ligeiramente diferentes em cada contexto.

Capacidade (descoberta)¶

Conforme visto nos perfis de descoberta.

Declaração completa de capability para discovery em nível de plataforma. Inclui URLs de spec/schema para busca pelo agente.

Nome	Tipo	Obrigatório	Descrição
version	string	Sim	Versão da entidade no formato YYYY-MM-DD.
spec	string	Sim	URL para o documento de especificação legível por humanos.
schema	string	Sim	URL para o JSON Schema que define a estrutura e os payloads desta entidade.
id	string	Não	Identificador único para esta instância de entidade. Usado para desambiguar quando existem múltiplas instâncias.
config	object	Não	Configuração específica da entidade. Estrutura definida pelo schema de cada entidade.
extends	OneOf[`string`, `array`]	Não	Capability(s) pai que esta estende. Presente para extensões, ausente para capabilities raiz. Use um array para extensões com múltiplos pais.

Capacidade (resposta)¶

Conforme visto nas mensagens de resposta.

Referência de capability em respostas. Apenas name/version são necessários para confirmar as capabilities ativas.

Nome	Tipo	Obrigatório	Descrição
version	string	Sim	Versão da entidade no formato YYYY-MM-DD.
spec	string	Não	URL para o documento de especificação legível por humanos.
schema	string	Não	URL para o JSON Schema que define a estrutura e os payloads desta entidade.
id	string	Não	Identificador único para esta instância de entidade. Usado para desambiguar quando existem múltiplas instâncias.
config	object	Não	Configuração específica da entidade. Estrutura definida pelo schema de cada entidade.
extends	OneOf[`string`, `array`]	Não	Capability(s) pai que esta estende. Presente para extensões, ausente para capabilities raiz. Use um array para extensões com múltiplos pais.

Referência de esquema¶

Esquemas de capacidade¶

Cart¶

Catalog Lookup¶

Catalog Search¶

Checkout¶

Order¶

Payment¶

Esquemas de tipo¶

Payment Account Info¶

Adjustment¶

Amount¶

Attribution¶

Available Payment Instrument¶

Binding¶

Business Fulfillment Config¶

Buyer¶

Card Credential¶

Card Payment Instrument¶

Category¶

Context¶

Description¶

Detail Option Value¶

Error Code¶

Error Response¶

Expectation¶

Fulfillment¶

Fulfillment Available Method¶

Fulfillment Destination¶

Fulfillment Event¶

Fulfillment Group¶

Fulfillment Method¶

Fulfillment Option¶

Info Code¶

Input Correlation¶

Item¶

Line Item¶

Link¶

Media¶

Merchant Fulfillment Config¶

Message¶

Message Error¶

Message Info¶

Message Warning¶

NCM¶

Option Value¶

Order Confirmation¶

Order Line Item¶

Pagination¶

Payment Credential¶

Payment Identity¶

Payment Instrument¶

Platform Fulfillment Config¶

Postal Address¶

Price¶

Price Filter¶

Price Range¶

Product¶

Product Option¶

Rating¶

Retail Location¶

Business Returns Config¶

Reverse Domain Name¶

Search Filters¶

Selected Option¶

Shipping Destination¶

Signals¶

Signed Amount¶

Token Credential¶

Total¶

Totals¶

Variant¶

Warning Code¶

Instrumento de pagamento selecionado¶

Solicitação de paginação¶

Resposta de paginação¶

Código de erro¶

Código de aviso¶

Código de informação¶

Esquemas de extensão¶