Tutorial do Universal Commerce Protocol: construa seu primeiro servidor UCP

Neste guia, você vai aprender o que é o Universal Commerce Protocol (UCP), para quem ele foi criado, por que um novo padrão de comércio é necessário e como sua arquitetura funciona. 

Você também vai seguir um passo a passo prático para configurar seu próprio servidor de exemplo do UCP, explorar seu perfil de descoberta, criar uma sessão de checkout e executar um fluxo completo localmente. 

Isso vai te dar tanto uma visão clara do protocolo quanto um ponto de partida prático para testar como o UCP funciona em uma implementação real.

Introdução ao Universal Commerce Protocol

O Universal Commerce Protocol é um padrão aberto que ajuda agentes de IA, apps, empresas e provedores de pagamento a trabalharem juntos em um fluxo de compra unificado. Em vez de criar uma integração personalizada para cada novo parceiro, o UCP oferece uma forma comum de comunicação.

O UCP foi pensado para o shopping conduzido por agentes, em que as pessoas descobrem e compram produtos por meio de assistentes de IA e interfaces conversacionais. Ele cobre toda a jornada: da descoberta do que a empresa oferece ao início do checkout e ao gerenciamento da compra de forma estruturada.

Fonte: Google Developers Blog

Em termos simples, o UCP funciona como uma linguagem compartilhada para o comércio. Uma empresa publica o que oferece suporte e um agente consegue ler essas informações e interagir sem precisar de uma integração de API sob medida. A Shopify descreve o UCP como a infraestrutura para viabilizar commerce com agentes em escala.

O UCP também é open source e neutro em relação a fornecedores. Ele foi projetado para funcionar com sistemas de comércio existentes e é compatível com o Agent Payments Protocol (AP2) para pagamentos seguros conduzidos por agentes. Também opera em diferentes meios de transporte, incluindo APIs REST, comunicação agente‑a‑agente e MCP. 

Para quem o Universal Commerce Protocol foi criado?

O UCP foi feito para os principais grupos envolvidos no comércio digital moderno. A ideia é dar a todos uma maneira comum de se comunicar, para que colaborem sem precisar de integrações personalizadas a cada nova conexão.

Ele é voltado principalmente para:

1. Agentes de IA e plataformas de consumo

São os apps, assistentes e superfícies de descoberta que ajudam usuários a encontrar produtos e comprar. O UCP permite entender o que uma empresa oferece e interagir de forma estruturada. O Google descreve isso como conectar as superfícies de consumo aos backends das empresas para uma experiência de compra contínua.

2. Empresas e lojistas

O UCP ajuda empresas a expor seus produtos, fluxos de checkout e recursos suportados em um formato padrão. Assim, fica mais fácil trabalhar com diferentes plataformas e agentes de IA sem precisar construir uma integração separada para cada um.

3. Provedores de pagamento

Os provedores de pagamento também fazem parte do ecossistema UCP. O protocolo foi projetado para acomodar diferentes payment handlers e credenciais de pagamento de forma flexível, garantindo transações seguras entre sistemas.

4. Desenvolvedores e criadores de protocolos

Como é open source, o UCP também é feito para desenvolvedores que querem implementar, estender ou contribuir com o padrão. O projeto UCP convida explicitamente empresas, desenvolvedores e provedores de pagamento a moldarem o futuro do protocolo.

Em outras palavras, o UCP foi criado para quem quer que esteja envolvido em comércio com IA: a plataforma que ajuda o usuário a comprar, a empresa que vende, o sistema de pagamento que processa a transação e os desenvolvedores que criam as conexões entre eles.

Por que um novo padrão de comércio é necessário

Um novo padrão é necessário porque a maioria dos sistemas atuais foi construída para sites e apps móveis tradicionais, e não para assistentes de IA e compras conversacionais. 

Esse modelo antigo depende muito de APIs personalizadas e integrações pontuais, o que torna tudo lento e difícil de escalar entre plataformas. O UCP surgiu para resolver isso, oferecendo uma forma compartilhada de comunicação entre empresas, agentes e plataformas.

À medida que mais pessoas passam a comprar usando ferramentas de IA, o comércio precisa dar suporte a ações em tempo real — como descoberta de produtos, checkout, descontos e atualizações de pedidos — dentro da mesma conversa. 

O UCP foi desenhado para esse novo jeito de comprar, em que a experiência é mais interativa e acontece em diferentes superfícies digitais.

Ele também é necessário porque o ecossistema de comércio atual é fragmentado. Diferentes empresas, provedores de pagamento e plataformas usam sistemas distintos. O UCP ajuda a uni-los por meio de um padrão comum, evitando ter que reconstruir as mesmas integrações repetidas vezes.

Resumindo: as ferramentas antigas não foram feitas para compras lideradas por IA. O UCP dá ao setor uma base mais moderna e flexível para como as pessoas vão descobrir e comprar produtos daqui para frente.

Entendendo a arquitetura do Universal Commerce Protocol

O Universal Commerce Protocol (UCP) é um sistema modular para commerce com agentes. Ele dá a empresas, agentes de IA e provedores de pagamento uma forma comum de conduzir a jornada de compra, da descoberta ao checkout e além. 

Em vez de criar integrações personalizadas para cada plataforma, o UCP permite que a empresa publique o que suporta para que um agente leia essas informações e siga um fluxo padrão. 

O UCP é modular e extensível, suporta transportes como REST, MCP e A2A, e funciona com payment handlers para que os lojistas aproveitem integrações de pagamento já existentes com mais facilidade.

1. A empresa publica um perfil de descoberta

Uma empresa compatível com UCP expõe um perfil em /.well-known/ucp. Esse perfil informa a plataformas e agentes o que a empresa suporta antes de qualquer transação, incluindo capacidades e endpoints disponíveis.

2. O agente lê as capacidades suportadas

Após a descoberta, o agente verifica quais serviços e capacidades a empresa oferece. O lançamento inicial do UCP foca em capacidades centrais como Checkout, Vinculação de identidade e Gestão de pedidos, que funcionam como os blocos básicos do protocolo.

3. Extensões adicionam recursos extras

O UCP mantém o fluxo central simples, mas empresas podem incluir extensões opcionais quando necessário. Essas extensões se baseiam nas capacidades centrais e permitem oferecer recursos mais ricos sem mudar todo o protocolo.

4. O fluxo roda por um transporte compatível

Depois que o agente sabe o que é suportado, ele pode interagir com a empresa usando um transporte como REST, MCP ou A2A. Isso facilita reutilizar a mesma lógica de comércio em APIs, ferramentas de IA e sistemas agente‑a‑agente.

5. O pagamento é tratado por payment handlers

O UCP separa o fluxo de comércio da camada de pagamento. As empresas podem declarar payment handlers suportados, e o protocolo foi desenhado para que os lojistas continuem usando suas integrações de pagamento existentes, sem refazer tudo do zero.

6. Pagamentos seguros conduzidos por agentes podem usar AP2

O UCP é compatível com o Agent Payments Protocol (AP2), que adiciona uma camada segura para pagamentos conduzidos por agentes. Isso ajuda a garantir autorizações mais seguras quando um agente de IA age em nome do usuário.

Passo a passo de ponta a ponta do Universal Commerce Protocol

Este guia mostra um fluxo completo do Universal Commerce Protocol usando a implementação de referência em Python. Você vai configurar o servidor de exemplo do lojista, carregar um catálogo de uma floricultura demo, descobrir as capacidades do negócio, criar uma sessão de checkout, aplicar um desconto e, por fim, encerrar o servidor.

Passo 1: configure o servidor da empresa

Neste passo, você vai instalar o uv para gerenciar dependências Python e, em seguida, clonar o UCP Python SDK e o repositório do servidor de exemplo. O README do servidor segue o mesmo padrão de setup e observa que o caminho relativo para o SDK importa nos exemplos.

Como nosso sistema operacional é Linux, vamos usar o comando abaixo para instalar o uv. O uv é um gerenciador de pacotes e ambientes Python rápido e confiável. Ele cumpre um papel parecido com ferramentas como Anaconda, mas é bem mais leve e ágil.

curl -LsSf https://astral.sh/uv/install.sh | sh

Quando a instalação terminar, recarregue sua sessão do terminal para que o comando uv fique disponível no shell atual.

source ~/.bashrc

Em seguida, crie uma pasta chamada sdk. Ela vai armazenar o Universal Commerce Protocol Python SDK quando o clonarmos do GitHub. 

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python

Agora, entre no diretório sdk/python, onde o repositório do SDK foi clonado.

pushd sdk/python

Dentro do diretório do SDK, instale todas as dependências Python necessárias com uv sync.

uv sync

Após instalar as dependências, volte ao diretório de trabalho anterior.

popd

Agora clone o repositório de exemplos, que contém o servidor de referência em Python usado neste tutorial.

git clone https://github.com/Universal-Commerce-Protocol/samples.git

Em seguida, acesse o exemplo de servidor em Python dentro do repositório de exemplos.

cd samples/rest/python/server

Por fim, instale todas as dependências Python necessárias para executar o servidor de exemplo.

uv sync

Neste ponto, o servidor de exemplo da empresa está pronto no seu ambiente. Ele já implementa as capacidades centrais de compra definidas pelo UCP.

Passo 2: crie um banco de dados de produtos de exemplo

Agora você vai criar uma loja demo local baseada em SQLite para a empresa de exemplo. A empresa usada neste tutorial é uma floricultura, e este comando carrega o catálogo de produtos e o banco de transações que o servidor usará.

Primeiro, crie uma pasta temporária onde os arquivos do banco ficarão armazenados.

mkdir /tmp/ucp_test

Depois, execute o script de importação para criar e popular os bancos de produtos e transações.

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop

Esse comando faz o seguinte:

• --products_db_path cria o banco do catálogo de produtos.
• --transactions_db_path cria o banco de transações usado para o estado do checkout.
• --data_dir=../test_data/flower_shop aponta para os dados de exemplo da floricultura incluídos no repositório.

Concluída esta etapa, os dados da loja de exemplo local estão prontos e o servidor poderá usá‑los.

Passo 3: inicie o servidor da empresa

Agora você vai iniciar o servidor de exemplo UCP da empresa. Ele usará os bancos de produtos e transações criados no passo anterior e exporá as APIs de compra do UCP na porta 8182.

Execute o comando abaixo para iniciar o servidor em background.

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!

Esse comando faz o seguinte:

• uv run server.py inicia o servidor de exemplo em Python.
• --products_db_path conecta o servidor ao banco de produtos.
• --transactions_db_path conecta o servidor ao banco de transações.
• --port=8182 define a porta 8182.
• & executa o processo em segundo plano para você continuar usando o terminal.
• SERVER_PID=$! salva o ID do processo para encerrar o servidor depois.

Pronto: o servidor da empresa está rodando e pronto para receber requisições de um agente.

Passo 4: descubra as capacidades da empresa

Agora você vai consultar o endpoint de discovery do UCP. Toda empresa compatível com UCP publica um documento de descoberta em /.well-known/ucp, permitindo que agentes entendam o que é suportado antes de fazer requisições.

Primeiro, salve a URL do servidor em uma variável para simplificar os próximos comandos.

export SERVER_URL=http://localhost:8182

Agora busque o documento de descoberta do UCP no servidor da empresa.

curl -s $SERVER_URL/.well-known/ucp

Essa resposta informa ao agente:

• qual versão do UCP o servidor suporta,
• quais serviços estão disponíveis,
• quais capacidades estão implementadas, como checkout e descontos,
• e quais payment handlers ou schemas são suportados.

A etapa de discovery é importante porque elimina a necessidade de integrações fixas e personalizadas. O agente inspeciona o servidor antes e decide como interagir com ele.

Passo 5: crie uma sessão de checkout

Agora você vai criar uma nova sessão de checkout usando a capacidade de checkout do UCP. É aqui que o agente envia o produto selecionado, informações do comprador e a estrutura de pagamento para o servidor da empresa.

Antes de enviar a requisição, gere os headers necessários. Eles ajudam em rastreabilidade, idempotência e validação de assinatura.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Isso faz o seguinte:

• REQUEST_ID cria um identificador exclusivo da requisição.
• IDEMPOTENCY_KEY garante que a mesma requisição não seja processada duas vezes em caso de retry.
• REQUEST_SIGNATURE fornece o header de assinatura exigido. Em um demo local, "dev" pode ser usado se a validação estrita não estiver habilitada.

Agora envie a requisição de checkout para o servidor.

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "john.doe@example.com" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'

Essa requisição inclui:

• line_items para definir o que será comprado,
• item.id para identificar o produto,
• item.title para um nome legível,
• quantity para indicar a quantidade,
• buyer com os dados do cliente,
• currency para definir a moeda do checkout,
• e payment para fornecer a estrutura de pagamento exigida.

A resposta retorna um objeto de sessão de checkout, com o novo ID do checkout, IDs dos itens, totais, informações do comprador e o status atual.

Passo 6: aplique descontos usando o UCP

Agora você vai atualizar a sessão de checkout existente e aplicar um cupom de desconto. Descontos no UCP são implementados como uma extensão da capacidade de checkout, então o desconto é incluído na requisição de atualização do checkout.

Primeiro, salve o ID real do checkout e o ID do item retornados na resposta anterior.

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e

Depois, gere um novo request ID e uma nova chave de idempotência para esta atualização.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Agora envie a atualização do checkout com o código de desconto incluído.

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"john.doe@example.com\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"

Essa requisição faz o seguinte:

• atualiza o checkout existente via PUT,
• inclui o ID original do checkout,
• inclui novamente o item,
• adiciona a seção discounts,
• e aplica o código 10OFF.

A resposta deve retornar o objeto de checkout atualizado, com:

• totais recalculados,
• o valor do desconto,
• o total final atualizado,
• e os detalhes do desconto aplicado.

O código de desconto é válido; você deve ver a mudança de preço na resposta.

Passo 7: desligue o servidor

No passo final, você vai encerrar o servidor de exemplo iniciado anteriormente. Como você salvou o ID do processo ao iniciar o servidor, dá para encerrá‑lo facilmente com um comando.

Execute o comando abaixo para parar o servidor.

kill $SERVER_PID

De ponta a ponta, você construiu e testou com sucesso um fluxo UCP completo na sua máquina local.

Você:

• instalou as ferramentas Python necessárias com o uv,
• clonou os repositórios do UCP Python SDK e do servidor de exemplo,
• criou um banco de produtos de uma floricultura de exemplo,
• iniciou o servidor da empresa,
• descobriu as capacidades UCP do servidor pelo endpoint de discovery,
• criou uma sessão de checkout como agente,
• atualizou o checkout aplicando um código de desconto,
• e por fim desligou o servidor.

Resumindo: você configurou uma empresa compatível com UCP, se conectou a ela como um agente, criou um checkout e testou como o UCP lida com atualizações como descontos. Isso te dá um exemplo básico e completo de como uma empresa e um agente podem interagir usando o Universal Commerce Protocol.

Conclusão

O Universal Commerce Protocol oferece ao mercado uma base comum para o comércio liderado por IA. Ele cria uma forma padrão de comunicação entre empresas, agentes de IA e sistemas de pagamento, facilitando discovery, checkout, atualizações e pagamentos — sem precisar reconstruir integrações para cada nova plataforma.

Neste guia, você aprendeu o que é o UCP, por que ele é importante, como sua arquitetura funciona e como executar um exemplo local do início ao fim. Ao configurar o servidor de exemplo, descobrir suas capacidades, criar uma sessão de checkout e aplicar um desconto, você viu como o UCP transforma o comércio em um fluxo estruturado e amigável a agentes.

A grande oportunidade do UCP é clara: reduzir a fragmentação e tornar o comércio mais interoperável num mundo em que as compras acontecem cada vez mais por assistentes de IA e interfaces conversacionais. 

O desafio, por outro lado, será a adoção. As empresas podem continuar escolhendo APIs personalizadas, integrações REST já existentes, ferramentas baseadas em MCP ou outros fluxos com agentes que já usam hoje. Para o UCP prosperar, ele vai precisar de um forte apoio do ecossistema: lojistas, plataformas, desenvolvedores e provedores de pagamento.