Pular para o conteúdo
jsonW Paper GitHub

Protocolos de comércio com agentes

ACP: a sessão de checkout e o feed de produtos, do formato do protocolo ao banco

O ACP organiza o feed de produtos e as sessões de checkout em formato comum. A Wortic traduz essas sessões para as funções do banco de checkout. Veja os campos que o protocolo define, o que é guardado no banco e por que o jsonW não entra nessa venda.

· jsonW 1.3.11

O protocolo

O ACP é um protocolo aberto da OpenAI e da Stripe para comércio dentro de assistentes. Ele tem duas partes. A primeira é o feed de produtos, pelo qual a loja envia o catálogo. A segunda é a sessão de checkout, com as ações de criar, atualizar, completar e cancelar.

A sessão é um objeto com estado. O estado diz se a compra está pronta, se foi cancelada ou se precisa de uma pessoa. Quando a loja não pode concluir sozinha, o estado indica a escalada, e o comprador segue na página.

Como a Wortic traduz a sessão

As rotas de sessão da Wortic são uma ponte. Elas recebem o pedido no formato do ACP e chamam as funções do banco de checkout. A resposta sai de volta no formato do protocolo. O código não tem regra de preço própria: o preço vem da oferta publicada no banco.

Essa regra existe para uma razão simples. Uma oferta tem um preço só. Se o protocolo tivesse um preço próprio, a loja teria dois preços para o mesmo produto.

O que é guardado no banco

A sessão, o carrinho e os itens ficam no banco de checkout. O banco também guarda o vencimento do carrinho. Esse vencimento aparece no protocolo como o momento até o qual a sessão vale.

O que o jsonW guarda nesse caminho

Nada desse fluxo de venda fica no jsonW. O jsonW aparece na descoberta, com os arquivos que descrevem o site para agentes. Não há um registro de pedido em jsonW. Essa separação deixa claro onde a venda é feita.

Um campo que costuma confundir

A sessão pode voltar com um endereço de continuação. Ele leva a pessoa à página do carrinho, onde ela conclui o pagamento. O agente não completa a compra sozinho. Quem lê o registro deve saber que um carrinho aberto e parado não é uma venda.

Erros e versões

O ACP define o formato de erro. Quando a entrada não bate com o formato, a resposta é um erro, com o motivo. A versão do protocolo também vai na resposta. Assim, quem integra sabe com qual versão falou.

Como conferir a sessão

Para conferir uma sessão, crie uma de teste com um item de baixo valor, confira o estado devolvido e siga o endereço de continuação até a página. Depois cancele a sessão. Nada é cobrado sem a pessoa concluir.

O site oficial do protocolo está em agenticcommerce.dev, e o repositório, no GitHub do ACP.

Formato de estado

Cada sessão tem um estado que diz o que acontece em seguida. Um estado de espera pede a ação da pessoa. Um estado de cancelamento encerra a sessão. Quem integra deve tratar cada estado do protocolo, e não só o de sucesso, porque é nos outros que aparecem as dúvidas.

Versão de referência

A versão de referência do ACP é a de 17 de abril de 2026. A versão fica registrada no código e na resposta. Uma resposta sem versão identificada deve ser tratada como erro de integração.

Site oficial do ACP (agenticcommerce.dev) →