Pular para o conteúdo
jsonW Paper GitHub

Protocolos de comércio com agentes

UCP: o perfil da loja em /.well-known/ucp e onde o carrinho fica guardado

O UCP publica num endereço padrão o que a loja oferece e como ela recebe um pedido. A Wortic publica esse perfil, com a lista de pagamentos vazia de propósito. Veja o formato do perfil, onde ficam o carrinho e o checkout e o que o jsonW não guarda nesse caminho.

· jsonW 1.3.11

O protocolo

O UCP é um protocolo aberto para comércio com agentes. O comerciante publica um perfil em /.well-known/ucp. O perfil diz quais serviços a loja oferece, como catálogo, carrinho e checkout, e quais meios de pagamento aceita. Com esse perfil, o agente sabe quais pedidos pode fazer.

A versão mais recente da especificação é a de 25 de agosto de 2026. A Wortic também aceita a versão de 8 de abril de 2026.

O perfil da Wortic

O perfil está publicado em app.wortic.com/.well-known/ucp. Ele tem as capacidades de catálogo e de checkout. Na parte de pagamentos, a lista de manipuladores chega sem nenhuma entrada:

"payment_handlers": {}

Hoje o campo está vazio. A Wortic não recebe o cartão do agente. O pagamento acontece na página do carrinho, e a pessoa conclui ali.

O que é guardado e onde

O carrinho e o checkout não ficam no jsonW. Eles são feitos pelas funções do banco de checkout da casa. O jsonW guarda o perfil publicado, que é um texto gerado a partir da configuração, e não os itens de uma compra.

Essa divisão tem um motivo. O dinheiro e os preços ficam num lugar só, o banco, onde as regras de preço e de estoque já existem. Um segundo registro de preço seria um risco de divergência.

O que o agente recebe

Quando o agente abre um checkout, a resposta traz um endereço de continuação, o continue_url. Esse endereço leva à página do carrinho. A resposta também traz o estado da sessão, que indica que a pessoa precisa agir.

"continue_url": "[endereço da página do carrinho]"

Versões no código

A versão do protocolo fica gravada no código e aparece na resposta. Assim, quem integra sabe com qual versão a loja falou.

O que o jsonW não guarda aqui

Nenhum dado de pagamento passa pelo perfil. O cartão, o Pix e a confirmação ficam fora do jsonW. Isso mantém o registro de dinheiro em um sistema só.

Como conferir

Para verificar o perfil, abra o endereço /.well-known/ucp do seu domínio e confira se a lista de serviços tem catálogo e checkout. Confira também se a lista de pagamentos está do jeito que você decidiu.

A especificação está no site oficial, em ucp.dev, e o código de referência, no GitHub do UCP.

O que o perfil contém

O perfil é um objeto JSON com uma lista de serviços, uma lista de capacidades e a lista de manipuladores de pagamento. Cada capacidade diz o nome e a versão. Quem lê o perfil confere primeiro se o checkout está na lista e só depois procura o endereço de chamada.

Por que o perfil é gerado

O perfil sai do código que monta a resposta, e não de um arquivo digitado à mão. Assim, uma mudança de versão ou de serviço acontece num lugar só. Quando a configuração muda, o perfil muda junto, sem risco de um arquivo antigo continuar no ar.

Site oficial do UCP (ucp.dev) →