Capacidade do carrinho - Encadernação EP¶

Introdução¶

O Embedded Cart Protocol (ECaP) é uma implementação específica do carrinho de Ligação de transporte do Protocolo Incorporado (EP) do BCP que permite um host para incorporar uma interface de carrinho de empresa e receber eventos como o comprador interage com o carrinho. ECaP é uma ligação de transporte (como REST) — ela define como para se comunicar, não quais dados existem.

Terminologia e atores¶

Funções comerciais¶

Negócios: O vendedor que fornece bens/serviços e a construção do carrinho experiência.
Comprador: o usuário final que deseja fazer uma compra por meio do exercício de construção de carrinho.

Componentes Técnicos¶

Host: O aplicativo que incorpora o carrinho (por exemplo, aplicativo AI Agent, Super aplicativo, navegador). Responsável pelo usuário autenticação (incluindo quaisquer pré-requisitos, como vinculação de identidade).
Carrinho incorporado: a interface do carrinho da empresa renderizada em um iframe ou webview. Responsável pelo fluxo de construção do carrinho e potencial transição em construções de funil inferior, como criações de checkout.

Descoberta¶

A disponibilidade do ECaP é sinalizada através da descoberta de serviços. Quando uma empresa anuncia o transporte embedded em seu perfil /.well-known/ucp, todo carrinho Os valores continue_url suportam o protocolo de carrinho incorporado.

Exemplo de descoberta de serviço:json { "services": { "br.dev.bcp.shopping": [ { "version": "2026-07-14", "transport": "rest", "schema": "https://bcp.dev.br/2026-07-14/services/shopping/rest.openapi.json", "endpoint": "https://merchant.example.com/ucp/v1" }, { "version": "2026-07-14", "transport": "mcp", "schema": "https://bcp.dev.br/2026-07-14/services/shopping/mcp.openrpc.json", "endpoint": "https://merchant.example.com/ucp/mcp" }, { "version": "2026-07-14", "transport": "embedded", "schema": "https://bcp.dev.br/2026-07-14/services/shopping/embedded.openrpc.json" } ] } }Quando embedded estiver ausente da definição de serviço, o negócio apenas suporta continuação de carrinho baseada em redirecionamento via continue_url.

Configuração por carrinho¶

A descoberta em nível de serviço declara que uma empresa oferece suporte ao ECaP, mas não garantir que as empresas o habilitarão para todas as sessões do carrinho. As empresas DEVEM incluir uma ligação de serviço incorporada com config.delegate nas respostas do carrinho para indicar a disponibilidade do ECaP e permitir delegações para uma sessão específica.

Exemplo de resposta do carrinho:json { "id": "cart_123", "continue_url": "https://merchant.example.com/cart/cart123", "ucp": { "version": "2026-07-14", "services": { "br.dev.bcp.shopping": [ { "version": "2026-07-14", "transport": "embedded", "config": { "delegate": [] } } ] }, "capabilities": {...}, "payment_handlers": {...} } // ...other cart fields... }### Carregando um URL de carrinho incorporado

Quando um host recebe uma resposta de carrinho com continue_url de uma empresa que anuncia suporte ao ECaP, ele PODE iniciar uma sessão do ECaP carregando o URL em um contexto incorporado.

Exemplo:text https://example.com/cart/cart123?ep_version=2026-01-23...Observação: todos os valores dos parâmetros de consulta devem ser codificados em URL corretamente de acordo com RFC 3986.

Antes de carregar o contexto incorporado, o host DEVE:

Marque config.delegate na resposta para delegações disponíveis
Mecanismos de autenticação opcionalmente completos (ou seja, vinculação de identidade) se exigido pela empresa

Para iniciar a sessão, o host DEVE aumentar o continue_url com suporte Parâmetros de consulta ECap.

Todos os parâmetros ECaP são passados por meio de string de consulta de URL, e não por cabeçalhos HTTP, para garantir compatibilidade máxima em diferentes ambientes de incorporação. Parâmetros DEVERIAM use os prefixos ep ou ep_cart para evitar poluição do namespace e claramente distinguir os parâmetros ECaP dos parâmetros de consulta específicos do negócio:

ep_version (string, REQUIRED): A versão BCP para esta sessão (formato: YYYY-MM-DD). Deve corresponder à versão da descoberta de serviço.
ep_auth (string, OPCIONAL): Token de autenticação em ambiente definido pelo negócio formato.
ep_color_scheme (string, OPCIONAL): A preferência do esquema de cores para a interface do carrinho. Valores válidos: light, dark. Quando não fornecido, o O carrinho incorporado segue a preferência do sistema.
ep_cart_delegate (string, OPCIONAL): lista de delegações delimitada por vírgulas o host deseja lidar. PODE estar vazio se nenhuma delegação for necessária. DEVE ser um subconjunto de config.delegate da ligação de serviço incorporada.

Transporte e mensagens¶

ECaP usa a camada de transporte EP compartilhada. Veja Protocolo incorporado – Transporte e mensagens para formato de mensagem, tipos de mensagem e convenções de tratamento de resposta.

O ucp.version em todas as respostas DEVE ecoar o ep_version negociado durante a inicialização da sessão e confirmado pelo host no ep.cart.ready resposta. A versão está vinculada à sessão — NÃO DEVE ser alterada durante o período da sessão da CEAP.

Canais de Comunicação¶

O ECaP segue o modelo de canal de comunicação EP partilhado. Veja Protocolo Incorporado – Canais de Comunicação para o padrão geral.

Para hosts nativos, os globais específicos do carrinho são:

window.EmbeddedCartProtocolConsumer (preferencial) -window.webkit.messageHandlers.EmbeddedCartProtocolConsumer
window.EmbeddedCartProtocol (Host → Carrinho Incorporado)

Referência da API de mensagens¶

Categorias de mensagens¶

Mensagens principais¶

Mensagens de aperto de mão¶

`ep.cart.ready`¶

Após a renderização, o carrinho incorporado DEVE transmitir a prontidão para o pai contexto usando a mensagem ep.cart.ready. Esta mensagem inicializa um seguro canal de comunicação entre o host e o carrinho incorporado, comunica se ou não, é necessária uma troca de autenticação adicional e permite que o host forneça quaisquer dados de autorização solicitados de volta ao carrinho incorporado.

Direção: Carrinho Incorporado → Host
Tipo: Solicitação
Carga útil:
- delegate (array de strings, REQUIRED): Lista de delegação identificadores aceitos pelo carrinho incorporado. DEVE ser um subconjunto de ambos ep_cart_delegate (o que o host solicitou) e config.delegate da resposta do carrinho (o que o negócio permite). Uma matriz vazia significa que nenhuma delegação foi aceita.
- auth (objeto, OPCIONAL): Quando o parâmetro URL ep_auth não é suficiente nem aplicável devido a considerações adicionais, a empresa pode solicitar autorização durante o handshake inicial especificando a string type dentro deste objeto. Este valor de string type é um espelho do conteúdo da carga útil incluído em ep.cart.auth.

Exemplo de mensagem (nenhuma delegação aceita):json { "jsonrpc": "2.0", "id": "ready_1", "method": "ep.cart.ready", "params": { "delegate": [], "auth": { "type": "oauth" } } }A mensagem ep.cart.ready é uma solicitação, o que significa que o host DEVE responder para completar o aperto de mão.

Direção: Host → Carrinho Incorporado
Tipo: Resposta
Carga útil do resultado:
- ucp (objeto, REQUIRED): metadados do protocolo BCP. O version confirma que os ep_version e status negociados DEVERÃO ser "success".
- upgrade (objeto, OPCIONAL): Um objeto que descreve como o Embedded O carrinho deve atualizar o canal de comunicação que usa para se comunicar com o anfitrião. Quando presente, o host NÃO DEVE incluir credential — o canal será restabelecido e qualquer credencial enviada aqui será descartado.
- credential (string, OPCIONAL): Os dados de autorização solicitados, pode estar na forma de um token OAuth, JWT, chaves de API, etc. DEVE ser definido se auth estiver presente na solicitação. NÃO DEVE ser definido se upgrade está presente.

Exemplo de mensagem:json { "jsonrpc": "2.0", "id": "ready_1", "result": { "ucp": { "version": "2026-07-14", "status": "success" }, "credential": "fake_identity_linking_oauth_token" } }Os hosts PODEM responder com um campo upgrade para atualizar a comunicação canal entre o host e o carrinho incorporado. Atualmente, este objeto suporta apenas um campo port, que DEVE ser um objeto MessagePort e DEVE ser transferido para o contexto do carrinho incorporado (por exemplo, com {transfer: [port2]} na chamada iframe.contentWindow.postMessage() do host):

Exemplo de mensagem:json { "jsonrpc": "2.0", "id": "ready_1", "result": { "ucp": { "version": "2026-07-14", "status": "success" }, "upgrade": { "port": "[Transferable MessagePort]" } } }Quando o host responde com um objeto upgrade, o carrinho incorporado DEVE descartar qualquer outra informação da mensagem, enviar uma nova mensagem ep.cart.ready através do canal de comunicação atualizado e aguarde uma nova resposta. Todos mensagens subsequentes DEVEM ser enviadas somente pela comunicação atualizada canal.

Se o host não puder completar o handshake (por exemplo, falha na validação de origem ou violação do estado do protocolo), ele DEVE responder com um resultado error_response. Quando o host responde com um erro, a sessão não pode prosseguir. O anfitrião DEVE eliminar o contexto incorporado e PODE redirecionar o comprador para continue_url se presente. O carrinho incorporado NÃO DEVE ser enviado posteriormente mensagens após receber um erro de handshake.

Autenticação¶

`ep.cart.auth`¶

ep.cart.auth implementa o padrão de autenticação EP compartilhado — veja Protocolo Incorporado - Autenticação para o contrato de solicitação/resposta, exemplos e fluxo de escalonamento de erros.

Método: ep.cart.auth
Direção: Carrinho Embutido → Host (solicitação); Host → Carrinho Incorporado (resposta)

Quando o escalonamento de erros é necessário, o carrinho incorporado DEVE emitir um Notificação ep.cart.error de acordo com o padrão de erro de sessão.

Mensagens do ciclo de vida¶

As notificações do ciclo de vida seguem o padrão EP compartilhado — consulte Protocolo incorporado - Ciclo de vida. Todo o ciclo de vida notificações carregam o objeto cart completo como carga útil.

`ep.cart.start`¶

Sinaliza que o carrinho está visível e pronto para interação. Enviado após um sucesso Aperto de mão ep.cart.ready.

Direção: Carrinho Incorporado → Host
Tipo: Notificação
Carga útil:
- cart (objeto, REQUIRED): O estado atual completo do carrinho.

Exemplo de mensagem:json { "jsonrpc": "2.0", "method": "ep.cart.start", "params": { "cart": { "id": "cart_123", "currency": "USD", "totals": [ ... ], "line_items": [ ... ], "buyer": { ... } // ...other cart fields... } } }####ep.cart.complete

Indica a conclusão do processo de construção do carrinho e o comprador agora está pronto para ser fizeram a transição para a próxima etapa de sua jornada de compra.

Isso marca a conclusão do carrinho incorporado. Se br.dev.bcp.shopping.checkout for parte dos recursos negociados durante a descoberta de serviço, host PODE prossiga para iniciar uma sessão de checkout com base no carrinho concluído, emitindo um Operação criar checkout.

Direção: Carrinho Incorporado → Host
Tipo: Notificação
Carga útil:
- cart (objeto, REQUIRED): Estado final do carrinho.

Exemplo de mensagem:json { "jsonrpc": "2.0", "method": "ep.cart.complete", "params": { "cart": { "id": "cart_123", "currency": "USD", "totals": [ ... ], "line_items": [ ... ], "buyer": { ... } // ...other cart fields... } } }### Mensagens de mudança de estado

As notificações de mudança de estado seguem o padrão EP compartilhado – consulte Protocolo Incorporado - Mudança de Estado. Todos os estados notificações de alteração são enviadas do carrinho incorporado para o host e carregam o objeto cart completo como sua carga útil.

`ep.cart.line_items.change`¶

Os itens de linha foram modificados (quantidade alterada, itens adicionados/removidos).

Direção: Carrinho Incorporado → Host
Tipo: Notificação
Carga útil:
- cart (objeto, REQUIRED): O estado atual completo do carrinho.

Exemplo de mensagem:json { "jsonrpc": "2.0", "method": "ep.cart.line_items.change", "params": { "cart": { "id": "cart_123", // The entire cart object is provided, including the updated line items and estimated totals "totals": [ ... ], "line_items": [ ... ] // ... } } }####ep.cart.buyer.change

As informações do comprador foram atualizadas (e-mail, telefone, nome).

Direção: Carrinho Incorporado → Host
Tipo: Notificação
Carga útil:
- cart (objeto, REQUIRED): O estado atual completo do carrinho.

Exemplo de mensagem:json { "jsonrpc": "2.0", "method": "ep.cart.buyer.change", "params": { "cart": { "id": "cart_123", // The entire cart object is provided, including the updated buyer information "buyer": { ... } // ... } } }####ep.cart.messages.change

As mensagens do carrinho foram atualizadas. As mensagens incluem erros, avisos e avisos informativos sobre o estado do carrinho.

Direção: Carrinho Incorporado → Host
Tipo: Notificação
Carga útil:
- cart (objeto, REQUIRED): O estado atual completo do carrinho.

Exemplo de mensagem:json { "jsonrpc": "2.0", "method": "ep.cart.messages.change", "params": { "cart": { "id": "cart_123", // The entire cart object is provided, including any updated messages "messages": [ { "type": "error", "code": "invalid_quantity", "path": "$.line_items[0].quantity", "content": "Quantity must be at least 1", "severity": "recoverable" } ] // ... } } }### Mensagens de erro de sessão

`ep.cart.error`¶

ep.cart.error implementa o padrão de erro de sessão EP compartilhada — veja Protocolo incorporado - erro de sessão para o especificação de carga útil e requisitos de manipulação de host.

Segurança e tratamento de erros¶

Códigos de erro¶

ECaP usa o conjunto de códigos de erro EP compartilhado - consulte Protocolo incorporado - códigos de erro.

Segurança para hosts baseados na Web¶

O ECap herda os requisitos de segurança compartilhados do EP para CSP, sandboxing iframe, iframes sem credenciais e validação estrita de origem. Veja Protocolo Incorporado - Segurança para o completo especificação.

Definições de esquema¶

Os esquemas a seguir definem as estruturas de dados usadas no Embedded Protocolo do carrinho.

Carrinho¶

O objeto principal que representa o estado atual do carrinho, incluindo itens de linha, totais e informações do comprador.

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.