Pular para o conteúdo
UCP
Menu

WooCommerce · Guia Técnico

WooCommerce + UCP: guia completo de integração

O WooCommerce impulsiona aproximadamente 30% de todas as lojas online, tornando-o a plataforma não-Shopify mais importante para a adoção do UCP. Ao contrário do Shopify, o WooCommerce não possui suporte UCP nativo integrado. Mas sua REST API extensível e seu ecossistema de plugins ativos tornam a integração alcançável para a maioria dos comerciantes sem um pesado desenvolvimento personalizado.

Atualizado : Abril de 2026 · Consulta principal : Implementação UCP WooCommerce

Opção 1: Plugin UCP (recomendado para a maioria dos comerciantes)

O caminho mais simples para os comerciantes WooCommerce é um plugin UCP dedicado. Vários foram publicados no repositório de plugins do WordPress no primeiro trimestre de 2026. Esses plugins expõem automaticamente endpoints REST compatíveis com UCP usando seus dados de produto, inventário e gerenciamento de pedidos existentes do WooCommerce, sem necessidade de código personalizado.

O que um plugin UCP geralmente lida: geração de endpoint de catálogo a partir do catálogo de produtos WooCommerce, sincronização de inventário do gerenciamento de estoque WooCommerce, roteamento de checkout para seu gateway de pagamento existente via wrapper AP2 e criação de pedidos no admin do WooCommerce a partir de compras de agentes.

Antes de instalar, verifique se o plugin: tem manutenção ativa, é compatível com sua versão do WooCommerce, suporta o fluxo de pagamento AP2 para seu processador de pagamento e, idealmente, tem testes de certificação UCP integrados.

Opção 2: Implementação de REST API personalizada

Comerciantes com recursos de desenvolvedor que desejam controle total podem construir endpoints UCP diretamente usando a REST API do WooCommerce como backend. O WooCommerce expõe sua própria REST API em /wp-json/wc/v3/, sua camada UCP traduz entre o formato da API do WooCommerce e a especificação UCP.

Endpoint de catálogo

Seu endpoint GET /ucp/v1/catalog deve consultar a API de produtos do WooCommerce e transformar a resposta para o formato UCP. O mapeamento de campos chave:

  • WooCommerce id → UCP id
  • WooCommerce name → UCP name
  • WooCommerce description (sem HTML) → UCP description
  • WooCommerce regular_price → UCP price
  • WooCommerce currency → UCP currency
  • WooCommerce stock_status (instock/outofstock) → UCP availability (InStock/OutOfStock)
  • WooCommerce categories[0].name → UCP category (mapeado para taxonomia UCP)

Exemplo de registro de endpoint PHP

add_action('rest_api_init', function() {
  register_rest_route('ucp/v1', '/catalog', array(
    'methods'  => 'GET',
    'callback' => 'ucp_get_catalog',
    'permission_callback' => 'ucp_verify_agent_cert',
  ));
});

function ucp_get_catalog($request) {
  $wc_products = wc_get_products(array(
    'status' => 'publish',
    'limit'  => $request->get_param('limit') ?: 50,
    'page'   => $request->get_param('page') ?: 1,
  ));
  $ucp_products = array_map('map_wc_to_ucp', $wc_products);
  return rest_ensure_response(array(
    'products' => $ucp_products,
    'total'    => wp_count_posts('product')->publish,
  ));
}

Integração de pagamento: conectando AP2

A camada de pagamento exige que seu gateway de pagamento WooCommerce suporte o processamento de tokens AP2. Para Stripe (o processador de pagamento WooCommerce mais comum): instale a extensão Stripe AP2 para WooCommerce (disponível na biblioteca de plugins do Stripe), configure seu token de comerciante AP2 no Stripe Dashboard → Agentic Commerce e atualize seu endpoint de checkout UCP para passar tokens AP2 para a API de intenção de pagamento AP2 do Stripe.

Para outros processadores (Adyen, PayPal, Square): entre em contato com seu processador para obter o guia de integração WooCommerce + AP2. Todos os processadores de pagamento da coalizão UCP publicaram documentação de integração WooCommerce.

Sincronização de inventário: mantendo os dados atualizados

Um problema comum com as implementações UCP do WooCommerce são dados de inventário desatualizados. O WooCommerce não envia nativamente as alterações de estoque para APIs externas, seus endpoints UCP devem buscar o estoque atual em cada solicitação. Para lojas de alto tráfego, adicione uma camada de cache (Redis ou WordPress Transients API) com um TTL máximo de 15 minutos. Para lojas de baixo tráfego, consulte o estoque do WooCommerce diretamente em cada solicitação UCP, a sobrecarga é geralmente aceitável.

Testando sua implementação

Antes de registrar seu endpoint, valide com estas etapas:

  1. Teste o endpoint de catálogo: curl -H "Authorization: Bearer [test-token]" https://yourstore.com/ucp/v1/catalog, verifique se a resposta corresponde ao esquema UCP
  2. Teste o endpoint de disponibilidade para um ID de produto específico, verifique o reflexo do estoque em tempo real
  3. Execute um checkout de teste com o modo sandbox UCP, verifique se o pedido aparece no admin do WooCommerce
  4. Execute o pacote de testes oficial do UCP (ucp.dev/testing) em seu site de staging
  5. Verifique os tempos de resposta, todos os endpoints devem responder em 3 segundos

Registrando sua loja WooCommerce

Uma vez testado, registre seu endpoint UCP em ucp.dev/merchant-registry. Você precisará de: o URL da sua loja, o URL base do seu endpoint UCP, seu token de comerciante AP2 e os resultados do seu teste de certificação UCP. Após o registro, envie o URL do seu endpoint para o Google Merchant Center nas configurações de Comércio Agentivo para habilitar a descoberta do Gemini.

Leitura adicional