WooCommerce

Conecte sua loja WooCommerce auto-hospedada para que seu agent de IA possa responder perguntas sobre produtos, consultar o pedido de um comprador, recomendar itens em estoque e enviar atualizações de status do pedido — tudo a partir dos seus dados sincronizados de catálogo e pedidos.

O WooCommerce está incluído para todo mundo, avaliação gratuita incluída. Não há nada para comprar ou fazer upgrade antes de conectar uma loja.

O que você ganha

Catálogo (perguntas e respostas) — respostas a partir dos seus produtos, variações, preços e disponibilidade atual reais
Consulta de pedidos (WISMO) — compradores checam “cadê meu pedido?” com o número do pedido mais o e-mail ou telefone do pedido
Recomendações — sugestões limitadas a produtos que realmente estão em estoque
Atualizações de status do pedido — atualizações de envio na mesma conversa, para compradores que optam por receber
Estoque atual — preços e estoque do seu catálogo sincronizado, mantido em dia pelos webhooks
Handoff para o checkout — leve um comprador pronto para comprar ao seu próprio checkout do WooCommerce

Pré-requisitos

Uma loja WooCommerce auto-hospedada que você administra
A URL da sua loja (por exemplo, https://sua-loja.com)
Uma conta de Owner ou Admin no seu workspace do Cuneiform Chat — conectar uma loja é uma ação de administração
Pelo menos um agent, ou espaço para criar um (veja Seu agent de loja)

Você não precisa instalar nenhum plugin nem escrever código.

A URL da sua loja, do jeito que você digitar

Digite a URL como preferir — nós normalizamos. O esquema, um www. no início, uma barra no final e as maiúsculas do host são todos ignorados. Uma instalação em subdiretório (exemplo.com/loja) e uma porta não padrão são preservadas e ambas são suportadas.

Conectando

Há dois caminhos, no mesmo card. Use o fluxo guiado, a menos que algo o impeça.

Caminho A — a autorização guiada (recomendado)

Vá em Commerce → WooCommerce.
Informe a URL da sua loja e clique em Connect.
Seu navegador vai até a tela de aprovação do WooCommerce da sua própria loja. Aprove.
O WooCommerce devolve as chaves e você chega em Commerce.

É isso. O fluxo guiado faz três coisas que o caminho manual não faz: ele solicita a permissão certa por você, registra os webhooks que mantêm seus dados atualizados em tempo real e dispara a importação inicial do catálogo.

A tela de aprovação vai dizer read/write, e isso é intencional. O WooCommerce não deixa nada registrar webhooks com uma chave somente leitura — ele recusa o pedido na hora. Sem webhooks não há atualizações de catálogo, estoque ou pedidos em tempo real. A integração continua nunca escrevendo no seu catálogo, no seu estoque ou nos seus pedidos existentes; a permissão de escrita existe para que possamos registrar webhooks e, se você usar o checkout dentro do chat, criar o pedido pendente que o comprador está prestes a pagar.

Caminho B — colar chaves de API manualmente

Se sua loja está atrás de um firewall que bloqueia o redirecionamento, expanda Enter API keys manually e cole uma consumer key e um secret gerados em WooCommerce → Settings → Advanced → REST API.

Gere-as com permissão Read/Write e selecione Read/Write no nosso formulário também. Uma chave somente leitura deixa você permanentemente sem webhooks — veja abaixo.

Fazemos uma verificação de saúde da loja antes de salvar. Uma falha grave bloqueia a conexão; um aviso leve (uma loja lenta ou parcialmente acessível) conecta mesmo assim, para que você possa corrigir depois.

Depois de uma conexão manual

O caminho de chaves manuais pula duas coisas que o fluxo guiado faz ao conectar: ele não registra webhooks e não inicia a importação inicial do catálogo. As duas se recuperam em prazos diferentes — e uma delas só se recupera se sua chave carregar a permissão certa. Leia as duas metades abaixo.

Seu catálogo — aperte “Re-sync now”

Nada é importado ao conectar. Um job em segundo plano reconcilia catálogos diariamente, mas essa passada diária só busca os produtos alterados desde a última rodada dela mesma — e uma loja que nunca importou não tem acúmulo para buscar, só edições novas. A importação completa chega com a varredura semanal, que pode estar a até sete dias de distância.

Não espere por isso. Abra Commerce → WooCommerce → Catalog & Data e clique em Re-sync now. Isso roda a mesma importação que o fluxo guiado teria rodado ao conectar, e termina em minutos.

Seus webhooks — só se sua chave for Read/Write

Os webhooks também não são registrados ao conectar, mas esse ponto é reparado automaticamente sob uma condição. Um job de hora em hora tenta registrar os webhooks de novo em todas as lojas conectadas, então:

Uma loja Read/Write se recupera sozinha, normalmente dentro de uma hora. Você não precisa fazer nada.
Uma loja somente leitura nunca se recupera. O WooCommerce recusa toda tentativa de registro vinda de uma chave somente leitura. O job tenta de hora em hora e é recusado de hora em hora, indefinidamente.

Dá para ver isso em vez de ter que deduzir: Commerce → WooCommerce → Connection tem um painel Webhook health, que vai mostrar “Subscriptions drifted” com “No events received yet.” O outro sintoma é comportamental — mudanças de catálogo, estoque e pedidos só aparecem na próxima sincronização agendada, em vez de chegarem no momento em que acontecem.

A permissão é a que você nos disse que era

Nós registramos a permissão que você seleciona; não testamos a chave para descobrir. Se você colar uma chave Read/Write mas deixar o campo de permissão em branco, registramos como somente leitura — e tanto os webhooks quanto o checkout de várias linhas se degradam silenciosamente. Se você selecionar Read/Write mas colar uma chave somente leitura, sua loja recusa os webhooks toda vez.

Se as atualizações em tempo real ou o checkout de várias linhas estiverem faltando, esse único campo é a primeira coisa a conferir. A correção é fazer Reconnect pelo fluxo guiado, que sempre solicita a permissão certa.

O que a integração faz e o que não faz

A integração é somente leitura no que diz respeito aos dados da sua loja. Ela nunca edita nem exclui um produto, nunca ajusta estoque, nunca modifica nem cancela um pedido existente e nunca captura um pagamento. O pagamento sempre acontece no seu próprio checkout do WooCommerce.

A única coisa que uma conexão Read/Write escreve é um pedido pendente, e só quando um comprador faz checkout de dentro de uma conversa: em vez de repassar um produto por vez, o carrinho inteiro vira um pedido pendente na sua loja e o comprador é enviado para pagá-lo. Nada é cobrado, nada é preparado, e o pedido fica atribuído à conversa de onde veio, para que você possa ver onde a venda começou. Veja Checkout.

Uma conexão somente leitura não consegue criar esse pedido pendente, então ela repassa uma linha por vez. Essa é a diferença prática entre as duas permissões, e a razão pela qual o fluxo guiado sempre pede Read/Write.

Recursos

Uma loja, um agent de loja

Você conecta uma loja WooCommerce por workspace — e pode ter uma loja Shopify conectada ao mesmo tempo (veja Commerce).

Na hora de conectar, um agent vira seu agent de loja — escolhido por nós, e não por você. Se você já conectou essa mesma loja antes, o agent de loja antigo dela é retomado, com os ajustes e o histórico de versões intactos; caso contrário, um novo é criado. Esse agent carrega as ferramentas do WooCommerce; seus outros agents não são afetados. Não há chave por agent para caçar — a própria página do agent mostra um painel somente leitura dizendo que ele é gerenciado pela sua loja.

Versões anteriores desta página diziam para habilitar o comércio para mais agents em Commerce → Settings. Aquela página não existe mais, e a chave por agent foi junto. O comércio fica ligado ao agent de loja escolhido na hora de conectar.

Consulta de pedidos verificada

Compradores veem detalhes do pedido só depois de informar o número exato do pedido e o e-mail ou telefone do pedido. Um contato errado e um pedido inexistente devolvem a mesma resposta de “não encontrei”, sem nenhum detalhe — um endurecimento antienumeração que protege seus clientes. Veja Pedidos.

Catálogo e estoque atuais

Preços e estoque vêm do seu catálogo sincronizado, então as recomendações ficam limitadas ao que está realmente disponível. O WooCommerce envia mudanças de estoque junto com as atualizações de produto, em vez de como eventos de estoque separados, então uma mudança só de estoque chega com a próxima atualização do produto ou com a próxima sincronização. Veja Catálogo e Conhecimento.

Atualizações de status do pedido por opção

Depois que um comprador verifica o pedido dele na conversa, ele pode optar por receber atualizações de envio em um canal suportado. A opção do comprador é a única porta — os tipos de atualização já vêm ligados por padrão na conexão do WooCommerce, então não há nada para ligar antes. Veja Pedidos.

Reconnect

Diferente da Shopify, o WooCommerce tem um botão Reconnect. Use quando você rotacionar ou revogar as chaves de API da sua loja, ou quando tiver conectado manualmente com a permissão errada e quiser mudar para o fluxo guiado. Ele roda a aprovação de novo na sua loja e substitui as chaves salvas no lugar.

O que sincroniza da sua loja

O WooCommerce tem quatro tipos de produto nativos. Os quatro sincronizam, mas eles não se comportam do mesmo jeito dentro de uma conversa.

Tipo	O que o agent consegue fazer com ele
`simple`	Tudo. É catalogado, tem preço e pode ir para um carrinho — comprável enquanto sua loja o marcar como comprável e em estoque.
`variable`	Tudo. Cada variação sincroniza com preço e estoque próprios. O preço do produto vem das variações, e ele conta como em estoque enquanto qualquer variação estiver. O que entra no carrinho é a variação que o comprador escolheu, não o produto pai.
`grouped`	É catalogado e o agent consegue responder sobre ele. Um produto agrupado não tem preço próprio, e o estoque dele é o que o próprio WooCommerce deriva dos produtos filhos. Quem é realmente vendido são os filhos.
`external`	É catalogado e o agent consegue responder sobre ele, mas nunca dá para comprar pelo carrinho. O agent responde perguntas sobre um produto de afiliado como sobre qualquer outro — nome, descrição, preço — mas nunca entrega ao comprador seu link externo nem o texto do seu botão: esses campos sincronizam junto com o produto e ficam guardados, e nada os mostra numa conversa. Além disso, um produto de afiliado é sempre tratado como indisponível para venda, então nunca pode ser adicionado a um carrinho. Os compradores chegam até ele do jeito de sempre, pela sua própria loja.

Qualquer outro tipo é tratado como `simple`

Tipos de produto criados por uma extensão não são modelados. Assinaturas, agendamentos, kits, produtos compostos — qualquer coisa que não seja um dos quatro acima — cai no tratamento de simple.

Não é rejeitado. Ele sincroniza, é catalogado, e o agent consegue responder sobre ele e recomendá-lo, carregando o preço e o estoque que a linha do produto pai por acaso tiver. Para esses tipos esse preço costuma estar errado, e muitas vezes nem existe.

Se você depende de um tipo de produto de extensão, mantenha esses produtos fora do catálogo sincronizado em vez de deixar o agent cotá-los, e conte pra gente o que você usa — support@cuneiform.chat. Recomendar uma assinatura pelo preço da linha pai é pior do que não mencioná-la.

Os preços e a moeda da sua loja

Os preços sincronizam com os valores que sua loja guarda, na moeda da sua própria loja. A gente lê essa moeda nas configurações do WooCommerce — nunca do comprador — e os compradores a veem como o código de três letras ao lado do valor: USD 19,99, EUR 19,99, BDT 1900.

Ser um código e não um símbolo é proposital. $ sozinho é o dólar de quatro países diferentes, e um símbolo errado dito com convicção num preço é pior do que um código inconfundível.

A moeda é relida na reconciliação noturna do catálogo, então se você mudá-la no WooCommerce o código citado acompanha em um dia. Até essa primeira passada noturna, uma loja conectada antes de a gente começar a ler a configuração cita valores sem código — o preço continua certo, só ainda não está rotulado.

Um plugin de multimoeda não é refletido. As extensões que mostram uma moeda diferente para cada comprador conforme a região fazem isso dentro da sua loja. A gente guarda uma moeda por loja — a moeda base que suas configurações nomeiam — então o agent cita essa mesma para todo comprador, esteja ele onde estiver.

Os valores continuam certos na moeda com que estão rotulados; eles só não são os números convertidos que esse mesmo comprador veria no seu site. O checkout não é afetado: o comprador termina na sua própria loja, onde seu plugin faz o que sempre faz.

Plugins de rastreamento de envio

Transportadora e código de rastreio são lidos de um único lugar: o registro gravado pelo plugin oficial WooCommerce Shipment Tracking, no qual o Advanced Shipment Tracking (AST) também grava. Esses dois chegam. Qualquer outro plugin de rastreamento guarda os dados em outro lugar e não é lido de jeito nenhum, então o pedido parece sem rastreio mesmo que sua loja mostre um código. Veja Pedidos.

Lojas traduzidas

Nada na sincronização entende idioma. Se você usa WPML ou Polylang, cada versão traduzida de um produto sincroniza como um produto separado comum, e não como a tradução de um, e o agent pode mostrar qualquer uma delas.

Segurança

Nenhuma escrita no seu catálogo, estoque ou pedidos existentes — a integração lê produtos, estoque e pedidos, e nunca os modifica
As chaves são criptografadas em repouso — sua consumer key e seu secret nunca são guardados em texto puro
Isolamento por tenant — seu catálogo e seus pedidos ficam restritos ao seu workspace e nunca são visíveis para ninguém mais
Consulta de pedidos verificada — detalhes do pedido exigem o número exato mais um e-mail ou telefone que confira
Notificações por opção — atualizações de envio exigem uma opção explícita do comprador na conversa
Checkout seguro — o pagamento é concluído no seu próprio checkout do WooCommerce; nenhum dado de cartão passa pelo agent

Solução de problemas

A conexão trava ou falha

O fluxo guiado precisa que seu navegador alcance a tela de aprovação da sua loja e que sua loja nos alcance com as chaves. Se travar, normalmente é um problema de rede ou firewall, não das suas credenciais. Loja atrás de firewall? Use o caminho de chaves manuais — e depois leia Depois de uma conexão manual, porque ele deixa duas coisas por fazer.

O catálogo está vazio logo depois de conectar

Se você conectou manualmente, isso é esperado — nada foi importado. Clique em Re-sync now na aba Catalog & Data.

Se você usou o fluxo guiado, a primeira importação traz o catálogo inteiro e pode levar alguns minutos em uma loja grande.

Mudanças de produto ou estoque demoram horas para aparecer

Seus webhooks não estão registrados. Quase sempre isso significa que a loja foi conectada manualmente com uma chave somente leitura. Confira a permissão registrada na conexão e depois faça Reconnect pelo fluxo guiado.

”Esta loja já está conectada a outra conta”

A mesma loja está conectada a outro workspace. Desconecte lá primeiro e depois conecte aqui. Nós recusamos a tomada em vez de mover a loja silenciosamente.

O agent não responde perguntas sobre produtos

Confira se você está falando com o agent de loja — o que foi escolhido na hora de conectar. A página dele mostra um painel somente leitura dizendo “gerenciado pela sua loja”. Os outros agents não carregam as ferramentas de comércio.

A consulta de pedidos não encontra um pedido

A consulta é deliberadamente rígida: ela devolve detalhes só quando o comprador informa o número exato do pedido e um e-mail ou telefone que confere com o pedido.

Nenhuma atualização de status do pedido é enviada

O comprador tem que optar por receber, na conversa, em um canal suportado. Se ele optou, confira as chaves de notificação da conexão do WooCommerce — elas vêm ligadas por padrão, mas se o tipo de atualização correspondente foi desligado em algum momento, a opção do comprador sozinha não vai produzir mensagem.

Desconectando

Desconecte em Commerce → WooCommerce → Disconnect. Ao desconectar:

A conexão salva e as credenciais são removidas, junto com o catálogo sincronizado
O conhecimento de produto construído a partir desse catálogo é apagado
Os webhooks que ela registrou na sua loja são removidos
A permissão de comércio do agent de loja é redefinida, a persona de comércio dele volta ao original se você nunca a editou, e o próprio agent é arquivado — reconectar a mesma loja o retoma com os ajustes e o histórico de versões intactos
Qualquer Loja vinculada ao catálogo dessa loja WooCommerce é excluída em definitivo, junto com o histórico de analíticas dela. Lojas que você montou à mão não são tocadas
Os Agent Forms de comércio que vieram com a loja são arquivados
As sugestões de quiz de IA são excluídas de vez, para que uma futura reconexão comece do zero

Se você ainda tiver uma loja Shopify conectada, só os passos que afetam o workspace inteiro — arquivar os Agent Forms de comércio e excluir as sugestões de quiz — são pulados. O catálogo, o conhecimento de produto, as Lojas, as analíticas e o agent de loja da própria loja WooCommerce são sempre desmontados.

Perguntas frequentes

Preciso de algo específico para conectar o WooCommerce?

Não. O WooCommerce está incluído para todo mundo, avaliação gratuita incluída — catálogo, consulta de pedidos, recomendações e atualizações de status do pedido, tudo junto.

Preciso instalar um plugin?

Nenhum plugin. O fluxo guiado é uma aprovação única na sua própria loja. Você só cola chaves de API se o seu firewall bloquear o redirecionamento.

Por que a tela de aprovação pede acesso de escrita?

Porque o WooCommerce se recusa a registrar webhooks para uma chave somente leitura, e sem webhooks nada é atualizado em tempo real. A integração continua nunca mudando seu catálogo, seu estoque ou seus pedidos existentes. O que ela escreve se limita aos próprios webhooks e a um pedido pendente para um comprador fazendo checkout de dentro de uma conversa — veja Checkout.

Posso conectar com uma chave somente leitura mesmo assim?

Pode, e catálogo, consulta de pedidos, recomendações e notificações funcionam todos. O que você abre mão são as atualizações em tempo real (os webhooks nunca vão conseguir se registrar) e o checkout de várias linhas dentro da conversa. Se depois você quiser isso, faça Reconnect pelo fluxo guiado.

Todos os meus agents podem usar o WooCommerce, ou apenas um?

Um — o agent de loja escolhido na hora de conectar. Esse agent recebe as ferramentas do WooCommerce; os outros não são afetados.

O agent alguma vez altera minha loja?

Ele nunca edita produtos, nunca ajusta estoque, nunca modifica nem cancela pedidos existentes e nunca cobra. Em uma conexão Read/Write ele pode criar uma única coisa: um pedido pendente para um comprador que está fazendo checkout de dentro de uma conversa, que ele então paga no seu próprio checkout.

Relacionado

Visão geral do Commerce — o que conectar uma loja te dá
Shopify — a outra plataforma suportada
Catálogo e Conhecimento — como o catálogo sincroniza e se mantém atualizado
Pedidos — consulta de pedidos e atualizações de status
Checkout — incluindo a diferença que depende da permissão