Capacidade de check-out

• Nome do recurso: br.dev.bcp.shopping.checkout

Visão geral

Permite que plataformas facilitem sessões de checkout. A finalização da compra deve ser concluída manualmente pelo usuário por meio de uma UI confiável, a menos que a extensão AP2 seja compatível.

A empresa continua sendo a Merchant of Record (MoR) e não precisa ser compatível com PCI DSS para aceitar pagamentos com cartão por meio deste recurso.

Visão geral do fluxo

Pagamentos

Os manipuladores de pagamento são descobertos no perfil BCP da empresa em /.well-known/bcp e em checkout.ucp.payment_handlers. Os manipuladores definem as especificações de processamento para cobrança de instrumentos de pagamento (por exemplo, Pix via br.dev.bcp.pix ou um gateway de cartão). Quando o comprador envia o pagamento, a plataforma preenche a matriz payment.instruments com os dados do instrumento coletados.

O objeto payment é opcional na criação do checkout e pode ser omitido para casos de uso que não exigem processamento de pagamento (por exemplo, geração de cotação, gestão de carrinho).

Cumprimento

O cumprimento é modelado como uma extensão no BCP para dar conta de diversos casos de uso.

O cumprimento é opcional no objeto checkout. Isso permite que uma plataforma realize o checkout de produtos digitais sem precisar fornecer detalhes de cumprimento mais relevantes para bens físicos.

Ciclo de vida do status do checkout

O campo checkout status indica a fase atual da sessão e determina qual ação será necessária a seguir. A empresa define o status; o plataforma recebe mensagens indicando o que é necessário para progredir.

       +------------+                         +---------------------+
       | incomplete |<----------------------->

| requires_escalation |
       +-----+------+                         |   (buyer handoff    |
             |                                |  via continue_url)  |
             | all info collected             +----------+----------+
             v                                           |
    +------------------+                                 |
    |ready_for_complete|                                 |
    |                  |                                 |
    | (platform can    |                                 | continue_url
    | call Complete    |                                 |
    |   Checkout)      |                                 |
    +--------+---------+                                 |
             |                                           |
             | Complete Checkout                         |
             v                                           |
   +--------------------+                                |
   |complete_in_progress|                                |
   +---------+----------+                                |
             |                                           |
             +-----------------------+-------------------+
                                     v
                               +-------------+
                               |  completed  |
                               +-------------+

                               +-------------+
                               |  canceled   |
                               +-------------+
          (session invalid/expired - can occur from any state)

Valores de status

• incomplete: A sessão de checkout não contém informações obrigatórias ou tem questões que precisam de resolução. A plataforma deve inspecionar a matriz messages para obter contexto e deve tentar resolvê-las por meio de Update Checkout.

• requires_escalation: A sessão de checkout requer informações que não podem ser fornecidas via API ou que exigem a contribuição do comprador. A plataforma deve inspecionar messages para entender o que é necessário (consulte Tratamento de erros abaixo). Se existir algum erro recoverable, resolva-o primeiro. Em seguida, entregue a sessão ao comprador via continue_url.

• ready_for_complete: A sessão de checkout contém todas as informações necessárias e pode ser finalizada programaticamente. A plataforma pode chamar Complete Checkout.

• complete_in_progress: A empresa está processando a solicitação de Complete Checkout.

• completed: Pedido realizado com sucesso.

• canceled: A sessão de checkout é inválida ou expirou. A plataforma deve iniciar uma nova sessão de checkout, se necessário.

Tratamento de erros

A matriz messages contém erros, avisos e mensagens informativas sobre o estado de checkout. ucp.status é o discriminador de forma — "success" significa que a resposta carrega a carga esperada, "error" significa que ela carrega informações de erro. Cada mensagem de erro carrega um type, code, severity, content e um path opcional que identifica o campo ou item de linha específico ao qual a mensagem se refere (consulte O campo path abaixo). O campo severity prescreve a ação recomendada da plataforma:

Gravidade	Significado	Ação da plataforma
recoverable	Plataforma pode resolver modificando inputs via API	Atualizar recurso e tentar novamente
requires_buyer_input	O negócio requer entrada não disponível via API	Transferência via continue_url
requires_buyer_review	É necessária revisão e autorização do comprador	Transferência via continue_url
unrecoverable	Não existe nenhum recurso para agir	Tente novamente com novos recursos ou entradas ou transfira via continue_url

Erros com gravidade requires_* contribuem para status: requires_escalation. Ambos resultam na transferência do comprador, mas representam diferentes estados de checkout.

• requires_buyer_input significa que a finalização da compra está incompleta — a empresa requer informações que a API não é capaz de coletar de forma programática.
• requires_buyer_review significa que a finalização da compra está completa — mas política, regras regulatórias ou de direitos exigem autorização do comprador antes da colocação do pedido (por exemplo, aprovação de pedidos de alto valor, política de primeira compra).

Quando a empresa não consegue criar um novo recurso ou o recurso solicitado não existe mais, a resposta contém ucp.status: "error" com messages descrevendo a falha — nenhum recurso está incluído no corpo de resposta. Quando não existe nenhum recurso para agir, as mensagens DEVEM usar severity: "unrecoverable". Por exemplo, uma empresa pode rejeitar uma solicitação de criação de checkout em que todos itens não estão disponíveis:

{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}

Consulte os exemplos de vinculação REST (não incluído nesta versão do BCP) e MCP.

Algoritmo de processamento de erros

Quando o status for incomplete ou requires_escalation, as plataformas deverão processar erros como uma pilha priorizada. O exemplo abaixo ilustra um checkout com três tipos de erro: um erro recuperável (telefone inválido), um requisito de entrada do comprador (agendamento de entrega) e um requisito de revisão (pedido de alto valor). Os dois últimos exigem transferência e servem como sinais explícitos para a plataforma. As empresas DEVERÃO divulgar essas mensagens o mais cedo possível, e as plataformas DEVEM priorizar a resolução de erros recuperáveis antes de iniciar a transferência.

[
  {
    "type": "error",
    "code": "invalid_phone",
    "severity": "recoverable",
    "path": "$.buyer.phone_number",
    "content": "Phone number format is invalid"
  },
  {
    "type": "error",
    "code": "schedule_delivery",
    "severity": "requires_buyer_input",
    "content": "Select delivery window for your purchase"
  },
  {
    "type": "error",
    "code": "high_value_order",
    "severity": "requires_buyer_review",
    "content": "Orders over $500 require additional verification"
  }
]

Exemplo de algoritmo de processamento de erros:

GIVEN response with messages array

FILTER errors FROM messages WHERE type = "error"

PARTITION errors INTO
  recoverable           WHERE severity = "recoverable"
  requires_buyer_input  WHERE severity = "requires_buyer_input"
  requires_buyer_review WHERE severity = "requires_buyer_review"
  unrecoverable         WHERE severity = "unrecoverable"

IF unrecoverable is not empty
  RETRY with new resource or inputs, or hand off via continue_url
  RETURN

IF recoverable is not empty
  FOR EACH error IN recoverable
    IF error.path is present
      IDENTIFY the field at error.path in the request payload
      ATTEMPT to fix that field (e.g., reformat phone at $.buyer.phone_number)
    ELSE
      ATTEMPT generic fix based on error.code
  CALL Update Checkout
  RETURN and re-evaluate response

IF requires_buyer_input is not empty
  handoff_context = "incomplete, additional input from buyer is required"
ELSE IF requires_buyer_review is not empty
  handoff_context = "ready for final review by the buyer"

Erros padrão

Erros padrão são códigos de erro padronizados que as plataformas devem tratar com uma UX específica e apropriada, em vez de um tratamento de erro genérico.

Código	Descrição
out_of_stock	Item ou variante específica não está disponível
item_unavailable	O item não pode ser comprado (por exemplo, removido da lista)
address_undeliverable	Não é possível entregar no endereço fornecido
payment_failed	Falha no processamento do pagamento
eligibility_invalid	A reivindicação de elegibilidade não pôde ser verificada na conclusão

As empresas DEVERÃO marcar os erros padrão com severity: recoverable para sinalizar que as plataformas devem fornecer UX apropriada (mensagens de falta de estoque, avisos de validação de endereço, alterações na forma de pagamento) em vez de mensagens de erro genéricas ou adiar a conclusão da compra.

Exemplo: out_of_stock requer uma UX inicial específica, enquanto payment_failed pode ser tratado genericamente no momento da submissão.

O Campo path

O campo opcional path em uma mensagem ancora o erro em um componente da carga útil da resposta. As plataformas o usam para associar mensagens de erro ao campo de entrada ou item de linha que as causou — por exemplo, destacando um campo específico do comprador em um formulário ou sinalizando uma linha específica do carrinho.

path DEVE ser uma expressão JSONPath RFC 9535 relativa à raiz do objeto de resposta BCP. Os nomes de propriedades DEVEM usar snake_case correspondente ao esquema de solicitação. Quando path é omitido, a mensagem se aplica à resposta como um todo.

Referência de campo simples:

{ "path": "$.buyer.email" }

Elemento de matriz indexado:

{ "path": "$.line_items[0].quantity" }

Expressão de filtro (opcional, ao referenciar um item específico por ID):

{ "path": "$.line_items[?(@.id=='line-item-uuid')].quantity" }

As expressões de filtro têm sintaxe RFC 9535 válida e PODEM ser usadas quando referenciar um item de linha específico por id é mais claro que seu índice. Os caminhos baseados em índice são igualmente válidos; a empresa retorna índices que são inequívocos na resposta.

Regra de especificidade: um caminho para um campo específico (por exemplo, $.line_items[0].quantity) tem precedência sobre um caminho para seu pai (por exemplo, $.line_items[0]). Quando vários erros se aplicam ao mesmo campo, cada mensagem DEVE conter o caminho mais específico aplicável.

Verificação de elegibilidade na conclusão

As plataformas fornecem context.eligibility — reivindicações do comprador sobre benefícios elegíveis como associação de fidelidade, vantagens de instrumentos de pagamento e similares. Estes são reivindicações, não fatos verificados. As empresas PODEM agir de acordo com reivindicações reconhecidas durante a sessão (ajuste de preços, concessão de acesso ao produto, aplicação de descontos), mas todas as reivindicações aceitas DEVEM ser resolvidas antes que a transação possa ser concluída.

Reivindicações não reconhecidas ou inaplicáveis NÃO DEVEM bloquear a finalização da compra. As empresas DEVERÃO notificar o comprador via messages com type: "warning" quando uma reivindicação não for aceita, e PODEM usar type: "info" para explicar os efeitos das reivindicações aceitas. Na conclusão, as reivindicações aceitas que permanecerem não verificadas DEVEM resultar em type: "error" com code: "eligibility_invalid" (veja abaixo).

Códigos de mensagem de elegibilidade:

Tipo	Código	Quando
warning	eligibility_not_accepted	Alegação não reconhecida ou não aplicável
info	eligibility_accepted	Efeito de uma reclamação aceite
error	eligibility_invalid	A reivindicação aceita não pôde ser verificada na conclusão

Uma reivindicação é resolvida quando é verificada ou rescindida:

• Verificada: A Empresa confirma a reivindicação com base em uma prova fornecida no momento da conclusão. O BCP não prescreve como ocorre a verificação — a prova pode vir da credencial de pagamento, de um recurso de verificação de identidade, ou de qualquer outro mecanismo negociado entre a Plataforma e o Negócio.
• Rescindida: A Plataforma remove a reivindicação de context.eligibility antes da conclusão (por exemplo, o comprador altera a forma de pagamento ou retira uma reivindicação de adesão). Uma vez removida, a Empresa recalcula sem ela.

As empresas NÃO DEVEM concluir uma transação com reivindicações de elegibilidade não resolvidas. Reivindicações não verificadas podem resultar em preços incorretos ou acesso a produtos restritos.

Quando a verificação falha:

A falha na verificação DEVE afetar apenas o array messages. A empresa DEVE retornar um erro em messages com code: "eligibility_invalid" e severity: "recoverable". As mensagens DEVERIAM usar o campo path para identificar quais reivindicações específicas não puderam ser verificadas. A Plataforma PODE fornecer provas válidas e reenviar, reestruturar o checkout (por exemplo, remover itens inelegíveis, atualizar reivindicações) ou abandonar a tentativa.

Por exemplo, a Plataforma reivindica um benefício de cartão de loja por meio de context.eligibility. A Empresa aplica preços para membros durante a sessão. Na conclusão, a credencial de pagamento não corresponde ao instrumento reivindicado:

{
  "ucp": { "version": "2026-01-11", "status": "success", "payment_handlers": { ... } },
  "id": "checkout_abc",
  "status": "ready_for_complete",
  "currency": "...",
  "line_items": [ ... ],
  "totals": [ ... ],
  "links": [ ... ],
  "messages": [
    {
      "type": "error",
      "code": "eligibility_invalid",
      "severity": "recoverable",
      "content": "Payment credential does not match the claimed store card benefit.",
      "path": "$.context.eligibility[0]"
    }
  ]
}

A Plataforma pode resolver isso fazendo com que o comprador mude para o produto qualificado instrumento de pagamento, ou removendo a reclamação de context.eligibility para renegociar o checkout (obter preços atualizados, disponibilidade, etc.) e, em seguida, reenviando para conclusão.

Apresentação de aviso

O campo presentation nas mensagens de aviso controla a renderização contratar a plataforma DEVE seguir. Quando omitido, o padrão é "notice".

	notice (padrão)	disclosure
Exibir conteúdo	DEVE	DEVE
Proximidade de path	PODE	DEVE
Dispensável	PODE	NÃO DEVE
Renderização image_url	PODE	DEVE
Renderização url	PODE	DEVE
Escalar se não puder honrar	—	DEVE via continue_url

notice (padrão)

O contrato de renderização padrão para avisos. Plataformas DEVEM ser exibidas o conteúdo do aviso ao comprador. As plataformas PODEM renderizar avisos em um banner, bandeja ou brinde, e PODE permitir que o comprador os dispense.

disclosure

Avisos com presentation: "disclosure" carregam avisos - segurança avisos, declarações de alérgenos, conteúdo de conformidade, etc. DEVE seguir o contrato de renderização prescrito abaixo.

Requisitos da plataforma:

• DEVE exibir o aviso content ao comprador.
• DEVE exibir o aviso próximo ao componente referenciado por path, preservando a associação entre a divulgação e sua assunto. Quando path for omitido, a divulgação se aplica à resposta como um todo.
• NÃO DEVE ocultar, recolher ou ignorar automaticamente o aviso.
• DEVE renderizar image_url quando presente (por exemplo, símbolo de aviso, etiqueta de classe energética).
• DEVE renderizar url como um link de referência navegável, quando presente.

Avisos com presentation: "disclosure" DEVEM ter prioridade de renderização sobre avisos do tipo notice.

Plataformas que não conseguem honrar o contrato de renderização da divulgação DEVEM escalar para a UI do comerciante via continue_url, em vez de rebaixá-la silenciosamente para um notice.

Requisitos de negócios:

• DEVE definir presentation: "disclosure" quando o conteúdo do aviso deve ser exibido ao lado de um componente específico e não deve ser oculto ou descartado automaticamente.
• DEVE utilizar o campo path para associar as divulgações ao componente relevante na resposta.
• DEVE fornecer um code que identifique a categoria de divulgação (por exemplo, prop65, allergens, energy_label).
• DEVE fornecer image_url quando a divulgação tiver um associado elemento visual (por exemplo, símbolo de advertência, etiqueta de classe energética).
• DEVE fornecer url quando um link de referência estiver disponível para o comprador para saber mais.

Divulgação e Reconhecimento

O campo presentation controla como o aviso é renderizado, não se o checkout pode prosseguir. Quando também for necessário o reconhecimento afirmativo do comprador ou uma autorização, a empresa PODE combinar a divulgação com os mecanismos de escalonamento descritos no Ciclo de vida do status do checkout para garantir que a manifestação apropriada do comprador seja obtida.

Jurisdição e aplicabilidade

É responsabilidade da empresa determinar quais divulgações se aplicam a uma determinada sessão e retornar apenas aquelas que são relevantes. As empresas DEVEM usar dados fornecidos pelo comprador (context e outras informações) e atributos do produto para resolver requisitos específicos da jurisdição. As plataformas não afetam nem resolvem a aplicabilidade da divulgação — elas apenas apresentam o que recebem da empresa.

Exemplo

Uma resposta de checkout contendo um erro recuperável e uma divulgação aviso em um item de linha:

{
  "ucp": { "version": "2026-07-28", "status": "success", "payment_handlers": { ... } },
  "id": "chk_abc123",
  "status": "incomplete",
  "currency": "BRL",
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "item_456", "title": "Artisan Nut Butter Collection", "price": 1299, "image_url": "https://merchant.com/nut-butter.jpg" },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 1299 },
        { "type": "total", "amount": 1299 }
      ]
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 1299 },
    { "type": "total", "amount": 1299 }
  ],
  "messages": [
    {
      "type": "error",
      "code": "field_required",
      "path": "$.buyer.email",
      "content": "Buyer email is required",
      "severity": "recoverable"
    },
    {
      "type": "warning",
      "code": "allergens",
      "path": "$.line_items[0]",
      "content": "**Contains: tree nuts.** Produced in a facility that also processes peanuts, milk, and soy.",
      "content_type": "markdown",
      "presentation": "disclosure",
      "image_url": "https://merchant.com/allergen-tree-nuts.svg",
      "url": "https://merchant.com/allergen-info"
    }
  ],
  "links": []
}

A plataforma resolve o erro recuperável programaticamente enquanto tornando a divulgação do alérgeno próxima à linha referenciada artigo.

Continuar URL

O campo continue_url permite a transferência de checkout da plataforma para a interface de negócios, permitindo que o comprador continue e finalize a sessão de checkout.

Disponibilidade

As empresas DEVEM fornecer continue_url ao retornar status = requires_escalation. Para todos os outros status não terminais (incomplete, ready_for_complete, complete_in_progress), as empresas DEVERÃO fornecer continue_url. Para estados terminais (completed, canceled), continue_url DEVE ser omitido.

Formato

O continue_url DEVE ser um URL HTTPS absoluto e DEVE preservar estado de checkout para transferência perfeita. As empresas PODEM implementar o estado preservação usando qualquer uma das abordagens:

Estado do lado do servidor (recomendado)

Um URL opaco apoiado pelo estado de checkout do lado do servidor:

https://business.example.com/checkout-sessions/{checkout_id}

• Servidor mantém estado de checkout vinculado a checkout_id
• Simples, seguro, recomendado para a maioria das implementações
• Vida útil do URL normalmente vinculada a expires_at

Link permanente de check-out

Uma URL sem estado que codifica diretamente o estado de checkout, permitindo a reconstrução sem persistência do lado do servidor. As empresas DEVERÃO implementar suporte para este formato para facilitar a entrega do checkout e a entrada acelerada — por exemplo, um fluxo de "comprar agora" em que a plataforma preenche previamente o estado de checkout ao iniciá-lo.

Observação: Links permanentes de checkout são uma construção específica do REST que estende a ligação de transporte REST (não incluída nesta versão do BCP). Acessar um link permanente retorna um redirecionamento para a UI de checkout ou renderiza a página de checkout diretamente.

Escopos

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

Escopo	Descrição
br.dev.bcp.shopping.checkout:manage	Todas as operações de checkout em nome do usuário autenticado — criar, atualizar, concluir e cancelar sessões de checkout.

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

Diretrizes

(Além das diretrizes gerais)

Plataforma

• PODE contratar um agente para facilitar a sessão de checkout (por exemplo, adicionar itens à sessão de checkout, selecionar o endereço de cumprimento). No entanto, o agente deve entregar a sessão de checkout a uma UI confiável e determinística para que o usuário revise os detalhes do checkout e faça o pedido.
• PODE enviar o usuário da UI confiável e determinística de volta ao agente a qualquer momento. Por exemplo, quando o usuário decide sair da tela de checkout para continuar adicionando itens ao carrinho.
• PODE fornecer contexto ao agente quando a plataforma indicar que a solicitação foi feita por um agente.
• DEVE usar continue_url quando o status de checkout for requires_escalation.
• PODE usar continue_url para transferir para a UI comercial em outras situações.
• Ao realizar a transferência, DEVE preferir o continue_url fornecido pela empresa em vez de links permanentes de checkout construídos pela plataforma.

Negócios

• DEVE enviar um e-mail de confirmação após a finalização da compra.
• DEVE fornecer mensagens de erro precisas.
• A lógica que trata as sessões de checkout DEVE ser determinística.
• DEVE fornecer continue_url ao retornar status = requires_escalation.
• DEVE incluir pelo menos uma mensagem com severity de requires_buyer_input ou requires_buyer_review no retorno status = requires_escalation.
• DEVE fornecer continue_url em todas as respostas de checkout não terminais.
• Após uma sessão de checkout atingir o status completed, ela é considerada imutável.

Definição do esquema de capacidade

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

Operações

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

Operação	Descrição
Criar check-out	Inicia uma nova sessão de checkout. Chamado assim que um usuário adiciona um item ao carrinho.
Fazer check-out	Recupera o estado atual de uma sessão de checkout.
Atualizar Check-out	Atualiza uma sessão de checkout.
Concluir Check-out	Finaliza o checkout e faz o pedido.
Cancelar check-out	Cancela uma sessão de checkout.

Criar check-out

Deve ser invocada pela plataforma quando o usuário manifestar intenção de compra (por exemplo, ao clicar em "Comprar") para iniciar a sessão de checkout com os detalhes do item.

Recomendação: para minimizar discrepâncias e simplificar a experiência do usuário, os dados do produto (preço, título etc.) fornecidos pela empresa por meio dos feeds DEVEM corresponder aos atributos reais retornados na resposta.

Quando o recurso Cart é negociado, a carga útil da solicitação DEVE aceitar um campo cart_id adicional para conversão do carrinho em checkout. Veja Carrinho → Conversão do carrinho para checkout para o contrato de campo.

Campos de solicitação

Nome	Tipo	Obrigatório	Descrição
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.
payment	Payment	Não	Configuração de pagamento contendo handlers.

Campos de resposta

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

Obter check-out

Fornece o estado mais recente do recurso de checkout. Após o cancelamento ou a conclusão, cabe à empresa decidir o que devolver — ou seja, o estado pode permanecer disponível por um longo período ou expirar após um TTL específico, resultando em um erro not_found. A plataforma não impõe um TTL próprio para o checkout.

A plataforma respeita o TTL fornecido pela empresa via expires_at no momento da criação da sessão de checkout.

Campos de resposta

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

Atualizar check-out

Executa uma substituição completa do recurso de checkout. A plataforma DEVE enviar o recurso de checkout completo, incluindo quaisquer atualizações em campos somente-gravação. O recurso fornecido na solicitação substitui o estado da sessão de checkout existente no lado da empresa.

Campos de solicitação

Nome	Tipo	Obrigatório	Descrição
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.
payment	Payment	Não	Configuração de pagamento contendo handlers.

Campos de resposta

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

Concluir check-out

Esta é a chamada final de finalização do checkout. Deve ser invocada quando o usuário se comprometer a pagar e fazer o pedido dos itens escolhidos. A resposta dessa chamada é o objeto checkout com o campo order preenchido. O order retornado fornece os identificadores necessários, como id e permalink_url, que podem ser usados para referenciar o estado completo do pedido criado. Os campos do Checkout PODEM ser usados no momento da persistência do pedido para construir sua representação (ou seja, informações como line_items e fulfillment são usadas para criar a representação inicial do pedido).

Após essa chamada, outros detalhes são atualizados em eventos subsequentes à medida que o pedido e seus itens associados avançam pela cadeia de suprimentos.

Campos de solicitação

Nome	Tipo	Obrigatório	Descrição
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.
payment	Payment	Sim	Configuração de pagamento contendo handlers.

Campos de resposta

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

Cancelar check-out

Esta operação é usada para cancelar uma sessão de checkout, caso ela possa ser cancelada. Se a sessão de checkout não puder ser cancelada (por exemplo, se já estiver cancelada ou concluída), a empresa DEVERÁ retornar um erro indicando que a operação não é permitida. Qualquer sessão de checkout com status diferente de completed ou canceled DEVE ser cancelável.

Campos de resposta

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

Ligações de transporte

As operações abstratas acima estão vinculadas a protocolos de transporte específicos como definido abaixo:

• REST Binding (não incluído nesta versão do BCP): mapeamento de API RESTful usando verbos HTTP padrão e cargas JSON.
• MCP Binding: Mapeamento do protocolo de contexto do modelo para interação de agente.
• A2A Binding: Mapeamento de protocolo agente para agente para interações de agente.
• Embedded Checkout Binding: JSON-RPC para ativar o checkout incorporado.

Entidades

Comprador

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

Contexto

Os sinais de contexto são dados provisórios e não oficiais. As empresas DEVEM usar esses valores quando as entradas verificadas (por exemplo, endereço de entrega) estão ausentes e PODEM ignore ou rebaixe-os se for inconsistente com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (exportação controles). A elegibilidade e a aplicação da política DEVEM ocorrer no momento da finalização da compra usando dados de transação vinculativos.

Nome	Tipo	Obrigatório	Descrição
address_country	string	Não	O país. Recomendado no formato ISO 3166-1 alpha-2 de 2 letras, por exemplo "BR". Para compatibilidade retroativa, um código de país ISO 3166-1 alpha-3 de 3 letras como "BRA" ou um nome completo de país como "Brasil" também pode ser usado. Dica opcional para contexto de mercado (moeda, disponibilidade, precificação)—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor.
address_region	string	Não	A região na qual a localidade está, e que fica no país. Por exemplo, São Paulo ou outra divisão administrativa de primeiro nível apropriada. Dica opcional para localização progressiva—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor.
postal_code	string	Não	O código postal. Por exemplo, 01310-100. Dica opcional para refinamento regional—dados de maior resolução (ex.: endereço de shipping) têm precedência sobre este valor.
intent	string	Não	Contexto de fundo descrevendo a intenção do buyer (ex.: 'procurando um presente abaixo de R$ 50', 'preciso de algo durável para uso externo'). Informa relevância, recomendações e personalização.
language	string	Não	Idioma preferido para o conteúdo. Use tags de idioma IETF BCP 47 (ex.: 'pt-BR', 'en', 'zh-Hans'). Para REST, equivalente ao cabeçalho Accept-Language—as plataformas DEVERIAM recorrer ao Accept-Language quando este campo estiver ausente; quando fornecido, sobrepõe o Accept-Language. Empresas PODEM retornar conteúdo em outro idioma se este estiver indisponível.
currency	string	Não	Moeda preferida (ISO 4217, ex.: 'BRL', 'USD'). Empresas determinam a moeda de apresentação a partir do context e de sinais autoritativos; esta dica PODE informar a seleção em mercados multimoeda. Também serve como denominação para os valores de filtro de preço — as plataformas DEVERIAM incluir este campo ao enviar filtros de preço. Os preços na resposta incluem a moeda explícita confirmando a resolução.
eligibility	Array[Reverse Domain Name]	Não	Reivindicações do buyer sobre benefícios elegíveis, como participação em programa de fidelidade, vantagens de payment instrument e similares. Reivindicações reconhecidas PODEM informar a resposta da Empresa (ex.: disponibilidade de produto exclusiva para membros, precificação ajustada no catálogo, descontos provisórios no cart ou checkout). Empresas DEVEM ignorar valores não reconhecidos sem erro. Os valores DEVEM usar nomenclatura de domínio reverso (ex.: 'com.example.loyalty_gold', 'org.school.student') e DEVEM ser não identificáveis.

Sinais

Dados ambientais fornecidos pela plataforma para apoiar a autorização e prevenção de abusos. Ao contrário de context (preferências declaradas pelo comprador) e buyer (identidade autodeclarada), os valores de sinal NÃO DEVEM ser declarações afirmadas pelo comprador - plataformas fornecem sinais baseados na observação direta ou na retransmissão atestados de terceiros verificáveis de forma independente. Veja Sinais para detalhes e privacidade requisitos.

Nome	Tipo	Obrigatório	Descrição
br.dev.bcp.buyer_ip	string	Não	Endereço IP do cliente (IPv4 ou IPv6).
br.dev.bcp.user_agent	string	Não	Cabeçalho HTTP User-Agent do cliente ou equivalente.

Atribuição

Contexto de referência e evento de conversão fornecido pela plataforma – IDs de campanha, identificadores de clique e marcadores de origem/mídia comunicados pela plataforma. Consulte Atribuição para obter detalhes e consentimento requisitos.

Contexto de indicação e evento de conversão emitido pela plataforma — identificadores de campanha, IDs de clique, marcadores de source/medium, etc. Os mesmos parâmetros que as plataformas comunicam via parâmetros de consulta de URL em fluxos baseados em navegador.

Artigo

Solicitação de criação de 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.

Solicitação de atualização de 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.

Artigo

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

Item de linha

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

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

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

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

Item de linha

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

Ligação

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

Tipos de links conhecidos

As empresas DEVERÃO fornecer todos os links relevantes para a transação. O a seguir estão os tipos conhecidos recomendados:

Tipo	Descrição
privacy_policy	Link para a política de privacidade da empresa
terms_of_service	Link para os termos de serviço da empresa
refund_policy	Link para a política de reembolso da empresa
shipping_policy	Link para a política de envio da empresa
faq	Link para as perguntas mais frequentes da empresa

As empresas PODEM definir tipos personalizados para necessidades específicas de domínio. Plataformas DEVE lidar com tipos desconhecidos normalmente, exibindo-os usando o title campo ou omitindo-os.

Mensagem

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

Erro de mensagem

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Constant = error. Discriminador do tipo de mensagem.
code	Error Code	Sim	Código de erro que identifica o tipo de erro. Erros padrão são definidos na especificação (ver exemplos) e têm semântica padronizada; códigos de formato livre são permitidos.
path	string	Não	JSONPath (RFC 9535) para o componente ao qual a mensagem se refere (ex.: $.items[1]).
content_type	string	Não	Formato do conteúdo, default = plain. Enum: plain, markdown
content	string	Sim	Mensagem legível por humanos.
severity	string	Sim	Reflete o estado do recurso e a ação recomendada. 'recoverable': a plataforma pode resolver modificando as entradas e repetindo via API. 'requires_buyer_input': o lojista exige informação que sua API não suporta coletar de forma programática (checkout incompleto). 'requires_buyer_review': o comprador DEVE autorizar antes da colocação do pedido devido a regras de política, regulatórias ou de elegibilidade. 'unrecoverable': não existe recurso válido sobre o qual agir; repita com novo recurso ou entradas. Erros com severidade 'requires_' contribuem para 'status: requires_escalation'. Enum:* recoverable, requires_buyer_input, requires_buyer_review, unrecoverable

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.

Informações da mensagem

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Constant = info. Discriminador do tipo de mensagem.
path	string	Não	JSONPath (RFC 9535) para o componente ao qual a mensagem se refere.
code	Info Code	Não	Código informativo que identifica o tipo de mensagem informativa. Os códigos padrão são definidos nas specs de capability (ver exemplos) e têm semântica padronizada; códigos de forma livre são permitidos.
content_type	string	Não	Formato do conteúdo, default = plain. Enum: plain, markdown
content	string	Sim	Mensagem legível por humanos.

Aviso de mensagem

Nome	Tipo	Obrigatório	Descrição
type	string	Sim	Constant = warning. Discriminador do tipo de mensagem.
path	string	Não	JSONPath (RFC 9535) para o campo relacionado (ex.: $.line_items[0]).
code	Warning Code	Sim	Código de aviso que identifica o tipo de aviso. Códigos padrão são definidos nas specs de capabilities (veja os exemplos) e têm semântica padronizada; códigos de formato livre são permitidos.
content	string	Sim	Mensagem de aviso legível por humanos que DEVE ser exibida.
content_type	string	Não	Formato do conteúdo, default = plain. Enum: plain, markdown
presentation	string	Não	Contrato de renderização para este aviso. 'notice' (default): a plataforma DEVE exibir, PODE dispensar. 'disclosure': a plataforma DEVE exibir próximo ao componente referenciado pelo path, NÃO DEVE ocultar nem dispensar automaticamente. Ver a especificação para o contrato completo.
image_url	string	Não	URL de um elemento visual obrigatório (ex.: símbolo de aviso, etiqueta de classe energética).
url	string	Não	URL de referência para mais informações (ex.: site regulatório, entrada de registro, página de política).

Pagamento

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.

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.

Credencial de pagamento

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.

Endereço postal

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.

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.

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

Contrato de Renderização

As empresas são a fonte oficial dos totais apresentados — seu conteúdo e a ordem de exibição — porque a apresentação correta está sujeita a regiões, produtos e requisitos regulatórios que a empresa é obrigada a atender (por exemplo, discriminação de impostos multijurisdicionais, divulgações de taxas obrigatórias).

As plataformas DEVEM renderizar todas as entradas de nível superior na ordem fornecida:

for entry in totals:
    render_line(entry.display_text, entry.amount)

As plataformas PODEM renderizar as sublinhas como detalhes suplementares:

for entry in totals:
    render_line(entry.display_text, entry.amount)
    if entry.lines:
        for sub in entry.lines:
            render_detail_line(sub.display_text, sub.amount)

As plataformas NÃO DEVEM interpretar, filtrar, reordenar, agregar ou aplicar lógica de exibição própria.

Invariantes de totals[]:

• Cada entrada traz um type e um amount. Plataformas DEVEM usar display_text quando fornecido. Tipos conhecidos têm rótulos de exibição padrão como alternativa (ver tabela abaixo); tipos desconhecidos DEVEM incluir display_text.
• Os valores são números inteiros assinados — os valores negativos são subtrativos (por exemplo, descontos), os valores positivos são aditivos. O sinal É a direção.
• Exatamente um type: "subtotal" DEVE estar presente.
• Exatamente um type: "total" DEVE estar presente.

Verificação

As plataformas NÃO DEVEM substituir os totais fornecidos pela empresa por valores calculados por conta própria. As plataformas PODEM verificar os totais fornecidos:

assert sum(e.amount for e in totals if e.type != "total") == total_entry.amount

Caso a soma computada não corresponda à entrada type: "total", a plataforma NÃO DEVE alterar a saída renderizada — os totais apresentados pela empresa são autorizados para exibição. No entanto, as plataformas NÃO DEVEM concluir autonomamente um checkout com totais incompatíveis. As plataformas DEVEM rejeitar o checkout ou encaminhá-lo e solicitar a avaliação do comprador via continue_url.

Tipos bem conhecidos

Tipo	Assinar	Etiqueta padrão	Significado
subtotal	+	Subtotal	Soma dos preços dos itens de linha
discount	−	Desconto	Desconto em nível de pedido ou item de linha
items_discount	−	Descontos em itens	Acúmulo de descontos em itens de linha
fulfillment	+	Envio	Taxas de envio, entrega ou coleta
tax	+	Imposto	Encargos fiscais
fee	+	Taxa	Taxas e sobretaxas
total	=	Total	Total geral oficial (exatamente um)

Quando display_text é fornecido, as plataformas DEVEM utilizá-lo. Quando omitido em um tipo bem conhecido, as plataformas DEVEM usar o rótulo padrão acima. A convenção de sinal para os tipos bem conhecidos é imposta pelo esquema: tipos subtrativos (discount, items_discount) DEVEM ter valores negativos; tipos aditivos (subtotal, fulfillment, tax, fee) DEVEM ter valores não negativos.

O campo type é uma string aberta — as empresas PODEM usar valores além do conjunto bem conhecido. Tipos desconhecidos DEVEM incluir display_text (aplicado por esquema) e o sinal do valor é autodescritivo.

Tipos de repetição

Todos os tipos, exceto subtotal e total, PODEM aparecer várias vezes — por exemplo, linhas fiscais multijurisdicionais ou taxas discriminadas.

Sublinhas (lines)

Cada entrada de nível superior PODE incluir uma matriz lines. As sublinhas compartilham a mesma forma básica das entradas de nível superior — display_text e amount — fornecendo um detalhamento discriminado sob a entrada pai.

Invariante: sum(lines[].amount) DEVE ser igual ao amount da entrada pai.

A empresa controla o que DEVE ser renderizado (entradas de nível superior) e o que PODE ser opcionalmente exposto (sublinhas). As plataformas DEVEM renderizar as sublinhas quando fornecidas.

Exemplos

Imposto dividido, discriminado em nível superior:

[
  { "type": "subtotal",    "display_text": "Subtotal",    "amount": 5750 },
  { "type": "fulfillment", "display_text": "Shipping",    "amount": 899 },
  { "type": "tax",         "display_text": "Federal Tax", "amount": 332 },
  { "type": "tax",         "display_text": "State Tax",   "amount": 465 },
  { "type": "total",       "display_text": "Total",       "amount": 7446 }
]

Taxas recolhidas com detalhamento opcional:

[
  { "type": "subtotal", "display_text": "Subtotal", "amount": 4999 },
  {
    "type": "fee", "display_text": "Fees", "amount": 549,
    "lines": [
      { "display_text": "Service Fee", "amount": 399 },
      { "display_text": "Recycling Fee", "amount": 150 }
    ]
  },
  { "type": "tax",   "display_text": "Tax",   "amount": 444 },
  { "type": "total", "display_text": "Total", "amount": 5992 }
]

Desconto e crédito em conta — valores negativos:

[
  { "type": "subtotal",       "display_text": "Subtotal",       "amount": 10000 },
  { "type": "discount",       "display_text": "Summer Sale",    "amount": -1500 },
  { "type": "tax",            "display_text": "Tax",            "amount": 680 },
  { "type": "account_credit", "display_text": "Account Credit", "amount": -2500 },
  { "type": "total",          "display_text": "Amount Due",     "amount": 6680 }
]

Verificação de resposta BCP

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

Confirmação do pedido

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.

Resposta de erro

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.