O que é o UCP e como verificá-lo

UCP — o Protocolo Universal de Comércio (Universal Commerce Protocol) — é o padrão aberto que permite a um assistente de IA comprar em nome de uma loja. Uma loja publica um pequeno perfil legível por máquina em /.well-known/ucp, e qualquer assistente que fale o protocolo pode lê-lo para saber qual versão a loja fala, como chegar ao seu catálogo e ao seu checkout, e quais processadores de pagamento ela aceita — sem uma integração sob medida por loja, sem raspar telas, sem adivinhar. É o mesmo problema que o llms.txt resolve para o conteúdo, aplicado ao comércio: um humano lê uma vitrine, mas um agente precisa de um manifesto. Você pode colar qualquer loja no Verificador de UCP e ler o perfil dela como um veredicto — acessível, bem-formado, atual, ou nem é UCP — mas este artigo ensina você a ler o documento sozinho, para que da próxima vez que um perfil falhar, você veja o porquê no texto.

O que é o UCP — e por que os assistentes de IA precisam dele

O UCP é um padrão aberto do Google, codesenvolvido com a Shopify, que dá aos assistentes de IA uma linguagem comum para comprar: descobrir uma loja, buscar em seu catálogo, montar um carrinho, pagar e acompanhar o pedido depois. O assistente fala com a loja através do protocolo em vez de através de uma integração sob medida, e o comerciante continua sendo o comerciante de registro — mantendo seus dados de clientes e seus relacionamentos, como diz o próprio guia do Google. O sentido do padrão é colapsar um problema de integração N por N: sem ele, cada assistente precisaria de um acordo distinto com cada comerciante; com ele, cada lado implementa uma vez e interoperam.

A necessidade é nova porque a superfície de compra é nova. Os assistentes já encontram os compradores dentro do AI Mode na Busca do Google e no app Gemini, onde uma pergunta pode virar uma compra sem jamais abrir a aba de uma loja. Uma janela de chat não pode clicar em "adicionar ao carrinho", então o assistente precisa de um jeito de perguntar à loja, em termos de máquina, o que ela vende, como comprar, e o que acontece depois da venda. O UCP é esse jeito: cobre toda a jornada, da descoberta ao checkout e ao pós-venda — pedidos, fulfillment, descontos — e foi desenhado para interoperar com os padrões vizinhos de transporte (MCP, A2A) e de prova de pagamento (AP2), em vez de substituí-los.

O arquivo de descoberta: /.well-known/ucp e seus três campos obrigatórios

Todo o protocolo começa com um arquivo. Uma empresa publica seu perfil — um objeto JSON com um membro ucp obrigatório — em /.well-known/ucp, e uma plataforma o baixa antes de fazer qualquer outra coisa. Dentro de ucp, três campos são obrigatórios: version, a versão do protocolo como data; services, as superfícies de API que a empresa oferece, identificadas por nome de domínio reverso como dev.ucp.shopping, cada entrada emparelhando o serviço com uma vinculação de transporte (REST, MCP, A2A ou embedded) e um endpoint; e payment_handlers, os métodos de pagamento que ela aceita. Os dois últimos devem estar presentes mesmo quando vazios — um objeto vazio é uma afirmação válida ("ainda não oferecemos serviços"), um campo ausente é um perfil quebrado. Um quarto membro, capabilities, é opcional, mas é o que torna um perfil útil: enumera as funcionalidades individuais — checkout, carrinho, pedido, busca de catálogo — cada uma com sua própria versão, spec e URLs de esquema.

O arquivo também tem regras de hospedagem, e elas são rígidas por um motivo. Os perfis publicados devem ser servidos por HTTPS, não devem redirecionar, e devem trazer Cache-Control: public com um max-age de pelo menos 60 segundos — nunca private, no-store nem no-cache. Um perfil é a identidade estável e a lista de capacidades de uma loja, não uma resposta por transação, então ele foi feito para ser cacheado e baixado a baixo custo; um redirecionamento ou uma diretiva no-cache diz a uma plataforma que o editor não configurou o documento como o manifesto estável que o protocolo espera. As plataformas anunciam seu próprio perfil na outra direção, no cabeçalho de requisição UCP-Agent, que é o que torna possível a integração sem permissão: qualquer plataforma com um perfil descobrível pode falar com qualquer empresa que tenha um, sem registro prévio.

Lendo um documento real à mão: Allbirds

As lojas da Shopify publicam um perfil UCP por padrão, então qualquer uma delas é um exemplo ao vivo — tomemos a Allbirds, baixada em 21 de novembro de 2026. Seu ucp.version é "2026-08-25", a versão atual, e um objeto supported_versions mapeia duas versões anteriores — 2026-04-08 e 2026-01-23 — para URLs de perfil versionadas em seu domínio myshopify.com, para que os clientes antigos ainda possam negociar. Em services, dev.ucp.shopping aparece duas vezes: uma com transporte mcp em /api/ucp/mcp e outra com transporte embedded — e repare no que falta: não há entrada rest. Uma loja não precisa oferecer todos os transportes; anuncia os que realmente executa. Um segundo serviço, dev.ucp.common, também é oferecido por MCP.

O objeto capabilities é onde o documento fica específico. A Allbirds anuncia dev.ucp.shopping.checkout, cart, order, catalog.search e catalog.lookup, além de extensões: fulfillment e discount, que declaram estender checkout e cart, e buyer_consent, identity_linking e uma capacidade permalink. Os nomes são de domínio reverso por design: os nomes dev.ucp.* são governados pelo órgão do UCP, enquanto as entradas dev.shopify.* — aqui dev.shopify.catalog e a extensão dev.shopify.shopping.declared_fields — são da Shopify. Em payment_handlers há três processadores: com.google.pay, dev.shopify.card e dev.shopify.shop_pay, cada um com sua versão, spec e esquema. Falta uma coisa, e sua ausência está certa: o documento não traz um array keys de nível superior. As chaves de assinatura são opcionais — um perfil só as publica quando a loja assina requisições — então um perfil sem chaves não é um perfil quebrado.

As versões são datas — e a 2026-08-25 quebrou coisas

As versões do UCP são datas de calendário no formato YYYY-MM-DD, e a especificação é taxativa: uma empresa não deve anunciar uma string de versão que não seja uma data, como "draft", em seu perfil. A versão atual é 2026-08-25; as anteriores sobrevivem através de supported_versions, cada uma apontando para um perfil folha completo e autocontido para aquela data. A compatibilidade é estabelecida por igualdade exata de versão, não por "mais novo é melhor": uma plataforma e uma empresa cruzam as versões que ambas suportam, e se não houver versão compartilhada a empresa deve responder version_unsupported. Há mais uma armadilha que vale conhecer: cada entrada dev.ucp.* de serviço, capacidade e extensão em um perfil deve declarar a mesma versão que o ucp.version do perfil, e uma plataforma que encontre uma entrada com versão diferente deve rejeitá-la de imediato, tratando-a como ausente.

É por isso que uma versão antiga recebe um aviso e não uma aprovação. A versão 2026-08-25 foi a maior mudança estrutural do protocolo: removeu o antigo campo signing_keys[] do esquema do perfil e fez do array keys[] de nível superior — um JWK Set — o único lugar canônico para as chaves de assinatura, de modo que um cliente construído para a nova versão que leia signing_keys não encontrará nada; moveu as extensões de pagamento do namespace dev.ucp.shopping.* para dev.ucp.common.payment.*; reestruturou o consentimento do comprador, de flags booleanas fixas para um mapa dinâmico; e consolidou a configuração de fulfillment. Uma loja que continua na 2026-04-08 segue funcionando para os clientes que falam 2026-04-08, que é exatamente para o que existe o supported_versions — mas um assistente que só fale a nova versão não encontrará versão mutuamente suportada, e qualquer ferramenta que dependa dos nomes ou campos antigos falhará em silêncio. Antigo, no UCP, significa "congelado no tempo", não "quebrado" — e o aviso é a diferença.

UCP vs ACP vs AP2 vs x402

O ACP — o Protocolo de Comércio Agêntico (Agentic Commerce Protocol), codesenvolvido pela OpenAI e pela Stripe — cobre a etapa do checkout dentro de uma superfície de chat como o ChatGPT: o comprador aprova a compra na conversa, e a empresa cobra através do seu próprio provedor de pagamentos. Tem escopo de checkout, não de jornada completa de compra: responde como o comprador paga no chat, e deixa a descoberta do catálogo e o pós-venda para outra coisa. Pense nele como o paralelo do UCP nas superfícies da OpenAI, onde o UCP é o equivalente nas do Google.

O AP2 — o Protocolo de Pagamentos de Agentes (Agent Payments Protocol), publicado pelo Google — responde a outra pergunta: não como o checkout funciona, mas o que o usuário realmente autorizou. Ele produz mandatos assinados e verificáveis — um mandato de checkout para a compra em si e um mandato de pagamento para o lado do pagamento — para que um comerciante, uma rede e um emissor possam conferir a mesma prova em vez de confiar na palavra do agente. Foi desenhado para funcionar junto ao UCP, fornecendo a autorização assinada dentro de um fluxo UCP, e não para competir com ele.

O x402 — criado pela Coinbase — responde a uma terceira pergunta: como um agente paga por uma única coisa, uma vez, sem conta e sem página de checkout? Ele revive o código de status HTTP adormecido 402 Payment Required: o agente pede um recurso pago, o servidor responde 402 com um preço, e o agente tenta de novo com um pagamento assinado, geralmente em stablecoins liquidadas on-chain. É um medidor de pagamento por chamada para APIs, dados e conteúdo — a ferramenta certa quando a compra é uma única requisição, e a forma errada para um carrinho de compras.

Os quatro são complementos, não rivais, e a maioria dos sistemas reais os combina: o UCP executa a jornada de compra, o AP2 pode fornecer a prova assinada dentro dela, o x402 tarifa as chamadas individuais pelo caminho, e o ACP é a rota de checkout nas superfícies da OpenAI. Essa também é a fronteira do verificador deste site: o Verificador de UCP só lê perfis UCP. Ele não baixa nem valida documentos ACP, AP2 ou x402, então uma loja pode estar pronta para UCP e não ter nenhuma presença ACP ou AP2 — os protocolos são independentes, e a falta de um não é uma falha do outro.

O que o verificador de UCP faz — e o que ele não faz

O verificador baixa https://<alvo>/.well-known/ucp através do serviço de verificação no servidor — seu navegador nunca baixa o alvo diretamente, porque as regras de origem cruzada bloqueariam a maioria das lojas — e então percorre o perfil do jeito que a especificação faz. Ele verifica se o documento é acessível por HTTPS sem redirecionamento (um redirecionamento é uma falha, segundo a especificação), lê o cabeçalho Cache-Control e cita seu valor real, analisa o JSON e informa o erro exato de análise se falhar, e verifica se os três campos obrigatórios estão presentes, se a versão é uma data, e se a versão não é anterior a 2026-08-25. Ele lista cada serviço com seu transporte e versão, cada processador de pagamento, e cada capacidade com o serviço a que pertence, e sonda cada endpoint declarado para ver se é acessível. O veredicto é um de três: pronto para UCP, parcial, ou não-UCP — um 404 no perfil é o negativo habitual, e o verificador o diz explicitamente.

O que ele não faz importa tanto quanto. Ele não faz pedidos, não se autentica como comprador, e não valida a criptografia dos processadores de pagamento — a presença de um array keys[] prova procedência (as chaves pertencem ao domínio que as publicou), não confiança, e a especificação o diz com essas mesmas palavras. Ele não verifica documentos ACP, AP2 ou x402. E um resultado limpo não é uma promessa de que o checkout vai funcionar: o perfil é propaganda, não uma transação, e o endpoint por trás dele ainda pode exigir autenticação, uma conta de comprador ou aprovação do comerciante antes de fazer qualquer coisa. Uma verificação limpa significa que a loja se descreve corretamente e pode ser descoberta; que a compra se complete é assunto dos próprios sistemas da loja. Para o panorama mais amplo — se um site está pronto para os agentes em geral, arquivo de descoberta incluído — o Verificador de Prontidão para Agentes confere o arquivo UCP entre seus outros sinais.

Teste você mesmo: um perfil UCP mínimo, anotado pela própria forma

{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-08-25",
          "transport": "rest",
          "endpoint": "https://business.example.com/ucp/v1",
          "spec": "https://ucp.dev/2026-08-25/specification/overview/",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json"
        },
        {
          "version": "2026-08-25",
          "transport": "mcp",
          "endpoint": "https://business.example.com/ucp/mcp",
          "spec": "https://ucp.dev/2026-08-25/specification/overview/",
          "schema": "https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-25",
          "spec": "https://ucp.dev/2026-08-25/specification/shopping/checkout",
          "schema": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
        }
      ]
    },
    "payment_handlers": {
      "com.example.processor_tokenizer": [
        {
          "id": "processor_tokenizer",
          "version": "2026-08-25",
          "spec": "https://example.com/specs/payments/processor_tokenizer",
          "schema": "https://example.com/specs/payments/merchant_tokenizer.json"
        }
      ]
    }
  }
}

Fontes

Perguntas frequentes

Minha loja não tem /.well-known/ucp. Isso significa que os assistentes de IA não podem vender meus produtos?

Não. Um 404 no perfil só significa que a loja não é UCP: os assistentes ainda podem chegar a ela pelo caminho antigo, através de links, feeds e resultados de busca. O UCP é uma porta de entrada opcional e legível por máquina, não um requisito para vender online. As lojas da Shopify publicam o perfil automaticamente; em outras plataformas você o publica sozinho, ou sua plataforma ou provedor de pagamentos o publica por você. O veredicto "não-UCP" do verificador é uma constatação, não uma reprovação: ele diz que a porta não está lá, não que a loja esteja fechada.

O verificador avisa que minha versão do UCP é antiga. Preciso atualizar?

Não imediatamente, e não entre em pânico. As versões antigas continuam funcionando para os clientes que as falam — para isso existe o supported_versions — mas um assistente que só fale a versão atual não encontrará versão mutuamente suportada, e as ferramentas construídas para a nova versão podem procurar nomes e campos que seu perfil já não usa (signing_keys[] é o famoso). Quando atualizar, atualize juntos os esquemas, os nomes de capacidade e a leitura dos campos de chaves, e verifique novamente quais capacidades são realmente negociadas depois; uma mudança de versão só no papel, com identificadores antigos por baixo, é pior do que ficar deliberadamente na versão antiga.

Uma loja passa na verificação — isso garante que o checkout vai funcionar?

Não. O perfil é propaganda, não uma transação: ele diz o que a loja oferece e onde encontrar, e o verificador confirma que o anúncio está bem-formado. Ele nunca faz um pedido, nunca entra como comprador, e nunca valida a criptografia dos processadores de pagamento. O endpoint de checkout por trás do perfil ainda pode exigir autenticação, uma conta de comprador ou aprovação do comerciante, e o processador de pagamento pode recusar o pagamento. Tome uma verificação limpa como "descobrível e descrito corretamente" — que a compra se complete continua sendo trabalho da loja.