O catálogo de produtos é importado da sua plataforma e mantido em sincronia para alimentar automações, recomendações e o Turbinador. Esta página descreve campos, frequência e particularidades de cada plataforma.
Campos sincronizados
| Campo | Origem | Atualização |
|---|---|---|
| Identificador (SKU, ID interno) | Plataforma | Imutável |
| Nome do produto | Plataforma | Em cada mudança |
| Descrição | Plataforma | Em cada mudança |
| Preço regular | Plataforma | Em cada mudança |
| Preço promocional | Plataforma | Em cada mudança |
| Estoque (quantidade) | Plataforma | Em cada mudança ou venda |
| Status (ativo/rascunho) | Plataforma | Em cada mudança |
| Categorias | Plataforma | Em cada mudança |
| Tags | Plataforma | Em cada mudança |
| Imagens (URLs) | Plataforma | Em cada mudança |
| Variações (cor, tamanho) | Plataforma | Em cada mudança |
| Peso e dimensões | Plataforma | Em cada mudança |
| Atributos custom | Plataforma | Em cada mudança |
Eventos que disparam atualização
| Evento | Quando |
|---|---|
product.created | Produto criado na plataforma |
product.updated | Qualquer alteração |
product.deleted | Produto removido (raro — geralmente vira inativo) |
inventory.updated | Mudança de estoque |
price.updated | Mudança de preço |
Latência típica
- Webhook: 30 segundos a 5 minutos
- Fallback batch: a cada 1 hora para mudanças incrementais
- Full sync: 1 vez por semana, escalonado por loja
Defesa em profundidade contra gap de webhook
Algumas alterações de produto são feitas em janelas que não disparam webhook:
- Quick Edit no admin do WordPress (WooCommerce)
- Decremento de estoque por venda em alguns plugins de checkout
- Importação CSV via plugin de catálogo
Para esses casos, o ShopIA mantém full sync semanal que recalcula tudo. Detalhes do mecanismo em ADR architecture-product-sync-fallback.md (acesso interno).
Como o ShopIA usa o catálogo
Recomendações automáticas
Em automações de cross-sell, recompra e win-back, o sistema sugere produtos com base em:
- Categoria do produto comprado
- Padrão de quem comprou o mesmo
- Estoque disponível
- Preço dentro da faixa do cliente
Produtos sem estoque ou inativos são automaticamente excluídos das recomendações.
Newsletter
Ao montar newsletter, sistema oferece grade de produtos selecionada por:
- Performance recente (vendas dos últimos 30 dias)
- Aderência à data-chave (Dia das Mães prefere produtos de presente)
- Estoque adequado (não recomendar item esgotado)
Turbinador
O Turbinador acessa o catálogo para:
- Ler título, descrição e atributos atuais
- Escrever versões otimizadas
- Salvar versões geradas para aprovação
Detalhes em Turbinador: o que faz e quando usar.
Memo
O Memo consulta produtos quando você pergunta:
- "Esse produto está em estoque?"
- "Quanto vendi do produto X esta semana?"
- "Qual produto novo cadastrei nesta semana?"
Distinção entre plataformas
WooCommerce
- Suporta webhooks ricos para todas as alterações
- Plugin v3.13+ otimiza envio para
webhooks.shopia.com.br - Quick Edit pode escapar webhook — full sync semanal cobre
Shopify
- Webhooks oficiais cobrem 100% das alterações
- Variações são tratadas como produtos individuais (cada SKU é uma linha)
Nuvemshop
- Webhooks via API REST
- Pequena defasagem em mudanças massivas (cabeçotes não suportados nativamente)
VTEX
- Sincronização mais complexa devido ao modelo de SKU vs Product
- Requer configuração inicial específica
Exclusão de produto
Se você exclui produto na plataforma:
- Webhook
product.deletedé recebido (ou full sync detecta ausência) - ShopIA marca como inativo
- Produto não é apagado do banco — fica como histórico
- Pedidos antigos com aquele produto continuam visíveis
Razão: pedidos passados precisam manter consistência. Apagar quebraria histórico.
Variações: como são tratadas
Variações (cor, tamanho, etc.) são modeladas em três níveis:
- Produto pai — agrupador (ex.: "Camiseta Manga Curta")
- Variação — combinação específica (ex.: "Vermelho M")
- SKU — identificador único da variação
Para fins de campanha, sistema usa o produto pai. Para estoque e recomendação, usa a variação.
Categorias e tags
São sincronizadas como atributos do produto. Você pode usar para:
- Segmentar clientes que compraram categoria X
- Filtrar produtos para newsletter
- Treinar Memo a perguntar dados específicos
Mudanças em categorias da plataforma refletem em até 1 hora.
Imagens
URLs das imagens são sincronizadas, não as imagens em si. Quando o ShopIA exibe imagem de produto (em email, popup, painel), está fazendo proxy ou hotlinking para a URL original.
Implicações:
- Se você muda CDN ou apaga imagem na origem, ShopIA também perde acesso
- Carregamento depende da velocidade do seu servidor
- Otimização de imagem fica por sua conta
Identificação única
Cada produto tem identificador determinístico para deduplicação:
external_id = MD5(plataforma + store_id + product_id_da_plataforma)Garante que mesmo que webhook chegue duplicado, produto não é replicado.