O ShopIA sincroniza pedidos da sua plataforma de e-commerce em tempo real (via webhook) e em lotes periódicos (fallback). Esta página descreve quais campos são importados, com que frequência e como a operação afeta automações.
O modelo de sincronização
Há dois mecanismos que coexistem:
1. Webhook em tempo real
Quando um evento ocorre na plataforma (pedido criado, pagamento confirmado, status alterado), a plataforma envia notificação ao ShopIA. Latência típica: 30 segundos a 2 minutos.
2. Fallback batch
Sistema executa sincronização periódica via API (a cada 1 hora para pedidos recentes; a cada 24 horas full sync da última semana). Captura eventos perdidos por webhook silencioso.
A combinação garante que mesmo com falha de webhook, dados não são perdidos.
Campos sincronizados de pedido
| Campo | Origem | Atualização |
|---|---|---|
| Número do pedido | Plataforma | Imutável após criação |
| Status | Plataforma | Em cada mudança |
| Status de pagamento | Plataforma | Em cada mudança |
| Status de envio | Plataforma | Em cada mudança |
| Total bruto | Plataforma | Em cada mudança relevante |
| Total líquido (com descontos) | Plataforma | Idem |
| Itens (produtos, quantidades, preços unitários) | Plataforma | Em criação |
| Cliente vinculado | Plataforma + matching interno | Em criação |
| Endereço de entrega | Plataforma | Em criação ou edição |
| Forma de pagamento | Plataforma | Em criação |
| Cupom usado | Plataforma | Em criação |
| Código de rastreio | Plataforma | Quando informado |
| Notas do cliente | Plataforma | Em criação ou edição |
| Data de criação | Plataforma | Imutável |
| Data de pagamento | Plataforma | Quando confirmado |
| Data de envio | Plataforma | Quando enviado |
| Data de entrega | Plataforma | Quando entregue |
Eventos que disparam atualização
Cada plataforma tem nomenclatura própria, mas o ShopIA mapeia para eventos canônicos:
| Evento canônico | Disparado quando |
|---|---|
order.created | Pedido criado |
order.payment_confirmed | Pagamento confirmado |
order.payment_failed | Pagamento recusado |
order.shipped | Pedido despachado (com rastreio quando disponível) |
order.delivered | Marcado como entregue na plataforma |
order.cancelled | Pedido cancelado |
order.refunded | Pedido reembolsado |
order.updated | Qualquer outra alteração |
Como o ShopIA usa cada evento
order.created
- Cliente é criado se não existir (
upsert) - Pedido entra no histórico
- Carrinho abandonado anterior (se houver) é encerrado
- Automação de Boas-vindas dispara para primeiro pedido
- Automação de Confirmação de pedido dispara
order.payment_confirmed
- Atualiza status financeiro
- Dispara Confirmação de pagamento
- Inicia separação para automação de envio
order.shipped
- Atualiza status logístico
- Dispara Notificação de envio com rastreio (se disponível)
- Agenda Pedido de avaliação para 7 dias após entrega prevista
order.delivered
- Atualiza status final
- Inicia janela de cross-sell e win-back
order.cancelled / order.refunded
- Atualiza status
- Cancela automações futuras vinculadas ao pedido (não enviar avaliação de pedido cancelado)
- Dispara Confirmação de cancelamento (se ativada)
Histórico inicial
Ao conectar a loja, o sistema importa últimos 90 dias de pedidos. Isso permite:
- Cálculo imediato de LTV e ticket médio
- Identificação de clientes recorrentes
- Análise de padrões (top categorias, top produtos)
Para histórico maior, contate suporte. Importação completa pode demorar várias horas.
Pedidos antigos vs recentes
| Idade | Comportamento de automação |
|---|---|
| Pedido novo (após conexão) | Todas as automações disparam normalmente |
| Pedido durante histórico inicial | Apenas dados são importados — automações não disparam retroativamente |
| Pedido editado retroativamente | Atualizações são refletidas, mas automações não disparam de novo |
Esse comportamento evita "spam histórico" — você não quer mandar 90 dias de avaliações para clientes do passado.
O que NÃO é sincronizado
- Notas internas privadas da loja (apenas notas do cliente)
- Logs administrativos da plataforma
- Histórico de visualização da página do pedido
- Comunicações entre lojista e cliente fora do ShopIA
- Devoluções via correio (a não ser que reflitam em status
refundedna plataforma)
Edição de pedido na plataforma
Se você edita um pedido na plataforma de origem (acresce produto, muda endereço, ajusta valor):
- Plataforma envia webhook
order.updated - ShopIA recebe e atualiza no painel
- Latência típica: 1 a 5 minutos
Mudanças retroativas são refletidas, mas automações já enviadas não são revertidas. Se mensagem foi disparada com base em valor antigo, fica como histórico.
Reconciliação periódica
A cada 24 horas, o sistema executa full sync da última semana. Compara:
- Pedidos no ShopIA vs pedidos na plataforma
- Status de cada
- Totais e itens
Discrepâncias são corrigidas automaticamente. O processo aparece em logs internos visíveis para super admin.
Forçando sincronização manual
Se notar discrepância:
- Acesse Configurar > Conexões > [plataforma].
- Clique em Forçar sincronização agora.
- Confirme.
- Sistema importa últimos 7 dias.
Use com moderação — operação consome cota de API da plataforma.