Conectar WordPress e WooCommerce

Com o plugin Joinotify conectado à sua conta, um site WordPress pode ir além de enviar mensagens: ele sincroniza com a plataforma. Os clientes da loja viram contatos, com o que a loja sabe deles — quantos pedidos fizeram, quanto gastaram, quando compraram pela última vez. E o que acontece no site — um pedido pago, um cadastro, um carrinho abandonado, um formulário enviado — chega aos fluxos como um evento do site, pelo gatilho Evento do site.

A diferença para o gatilho webhook: não há URL para colar nem campo para mapear. O site já diz quem é o cliente e manda cada evento com um nome — wc.order.paid — que qualquer fluxo da conta pode escutar. O que cada evento traz está no catálogo de eventos do site.

Ligar a sincronização

O site precisa estar conectado ao Joinotify. A conexão sozinha não manda nada além do que o envio de mensagens precisa: a sincronização é desligada por padrão, e nada sai do site antes de você ligá-la.

1. No WordPress, vá em Joinotify → Configurações → Aplicativos e clique em Configurar no card Joinotify Cloud sync.
2. Leia o texto do topo da janela: ele diz exatamente o que o site vai enviar.
3. Escolha o que sincronizar (tabela abaixo), ligue o card e salve.

Os rótulos da janela aparecem aqui em inglês, o idioma de origem do plugin:

Opção	Padrão	O que faz
WooCommerce orders and customers	ligada	Eventos de pedido e de assinatura, e cada cliente com o número de pedidos, o total gasto e a última compra
WordPress users	ligada	Cadastros e atualizações de perfil
Form submissions	desligada	Envios do WPForms e do Elementor Pro — com todos os campos do formulário
Abandoned carts	ligada	Contatos capturados e carrinhos abandonados, recuperados ou perdidos do Flexify Checkout
Send the items of each order	ligada	Produtos, quantidades e categorias de cada pedido
Send billing and shipping addresses	desligada	O endereço completo. Cidade, estado e país vão sempre
Tag for contacts from this site	vazio	A tag de todo contato que o site envia. Vazio, vale o nome do site
Ask customers for marketing consent	desligada	A caixa de consentimento no checkout, nos cadastros e em Minha conta (veja abaixo)
Consent checkbox text	vazio	O texto da caixa. Diga o que a pessoa vai receber e por qual canal

Além dos clientes, o site informa o próprio endereço, o nome, a versão do Joinotify, quais plugins de loja, formulário e checkout estão ativos e um exemplo inventado de cada evento — é com ele que o editor de fluxos mostra os campos antes do primeiro pedido chegar.

Nada é enviado durante o checkout. Cada evento é gravado numa fila do próprio site e enviado em lotes, em segundo plano, logo em seguida. Se o Joinotify não responder, o evento espera na fila e é enviado de novo mais tarde. Desligar o card para o envio na hora; o que já chegou fica na sua conta.

O que a plataforma faz com cada contato

A sincronização acrescenta e nunca apaga:

• O contato é encontrado primeiro por quem ele é no site (o usuário do WordPress, o cliente da loja) e depois pelo telefone. Um cliente que troca de número continua sendo um contato só; se o número novo já for de outro contato, nada é juntado e o conflito fica na linha do tempo.
• Sem telefone, nenhum contato é criado — a plataforma é WhatsApp. O evento fica registrado como Sem contato.
• Nome e e-mail só preenchem o que estiver vazio: o que alguém digitou no painel vale mais.
• Tags só entram. Toda pessoa ganha a tag de origem do site, que serve para montar públicos e campanhas só com os clientes daquela loja.
• Os campos da loja — Pedidos, Total gasto, Ticket médio, Primeira compra, Última compra, Status do último pedido, Cidade, Estado, Cadastro no site, Papel no site e, com assinaturas, Status da assinatura e Próximo pagamento — são criados pela plataforma na primeira sincronização e recebem a fotografia que o site calcula: substituem o valor anterior.
• Contato novo conta no limite de contatos do plano. Acima dele, o contato não é criado e o evento fica como Limite de contatos. Quem já é contato segue normalmente.

Na ficha do contato, a origem aparece como Site conectado, e a seção No site mostra quem a pessoa é em cada site conectado — Usuário do WordPress, Cliente WooCommerce, Comprador sem conta ou Lead de formulário ou carrinho — e de quando são os dados.

Consentimento de marketing

Ligando Ask customers for marketing consent, uma caixa desmarcada aparece:

• no checkout — o clássico e o em blocos (WooCommerce 8.9 ou mais novo);
• nos formulários de cadastro do WordPress e do WooCommerce;
• em Minha conta → Detalhes da conta.

Quem já aceitou não vê a caixa de novo no checkout. Quem marca fica com o texto da caixa, onde e quando guardados no pedido ou no usuário, como evidência, e o próximo evento dessa pessoa leva o opt-in para o Joinotify. Quem desmarca a preferência em Minha conta faz opt-out na plataforma — e esse opt-out vale sempre.

Duas regras protegem a base:

• O consentimento só sobe de desconhecido: uma caixa marcada num pedido antigo nunca desfaz um opt-out, nem tira alguém da lista de supressão.
• O caminho de volta também funciona: um opt-out feito no Joinotify — por palavra-chave, pelo painel, por um fluxo — é avisado ao site, e a preferência da pessoa aparece desmarcada lá. Um opt-in feito no Joinotify também volta.

Sem a caixa, os contatos chegam com o consentimento desconhecido: mensagens transacionais continuam possíveis, e as campanhas de marketing seguem as regras de Contatos e consentimento.

Enviar os clientes que já existem

Os eventos só alcançam quem compra ou se cadastra daqui em diante. Para que a primeira campanha chegue aos clientes que a loja já tem, envie-os uma vez:

1. Na janela da sincronização, em Existing customers, clique em Send existing customers.
2. Confira a estimativa: quantos usuários têm telefone e quantos pedidos foram feitos sem conta.
3. Clique em Send them. O envio roda em segundo plano — pode fechar a página. Stop interrompe, e quem já entrou na fila ainda é enviado.

Cada pessoa vai uma vez: primeiro os usuários, depois os compradores sem conta, um por e-mail (quem tem conta vai como a conta). Nenhum fluxo começa para quem chega assim. Quem não tem telefone fica de fora e é contado, e o limite de contatos do plano é respeitado. No fim, a janela mostra quantos foram enviados, quantos esperam, quantos foram desistidos e o que a plataforma fez com alguns deles — sem telefone, telefone inválido, acima do limite do plano, mantido em opt-out.

Acompanhar pelo WordPress

O topo da janela mostra se a sincronização está ligada (Sync on), desligada (Sync off) ou pausada (Sync paused), a última entrega e o último erro, e três contadores: o que espera (Waiting), o que foi enviado nos últimos 7 dias (Sent (7 days)) e o que foi desistido (Given up).

Um envio que falha é tentado de novo com intervalos crescentes — de 1 minuto a 1 hora. Depois de 12 tentativas, ou quando a plataforma recusa o evento pelo que ele é, ele é desistido e aparece na lista com o motivo. Corrigido o problema, Send again manda de novo; Discard apaga. Os desistidos ficam 30 dias no site.

A sincronização pausa quando não adianta tentar:

Motivo	O que fazer
A chave do site foi revogada ou não pode enviar os dados	Conecte o site de novo; a sincronização volta sozinha
O site foi removido da sua conta	Conecte o site de novo
O site está em outro endereço que o da chave	Se é uma cópia de staging, deixe pausado. Se o site mudou de endereço, conecte-o de novo

Pausada, a sincronização continua guardando os eventos na fila do site, e nada se perde. Try again tenta na hora. Um site pausado no painel (abaixo) não pausa o plugin: os eventos esperam e são pedidos de novo a cada 15 minutos, até você retomar.

Cópias de staging

Uma cópia do site em outro endereço — staging, clone, ambiente de testes — que levou a chave da produção é recusada pelo Joinotify e fica pausada: os pedidos de teste nunca chegam aos clientes de verdade. No painel, o site mostra que uma cópia tentou usar a chave dele. Para testar a sincronização numa cópia, conecte a cópia por conta própria: ela vira um site separado em Integrações.

No painel: Integrações

A página Integrações lista os sites conectados, com as integrações ativas de cada um, o último evento, os eventos e os problemas das últimas 24 horas. Por ela você pode:

• Pausar um site: o que ele enviar é recusado até você Retomar — o plugin guarda e manda depois;
• Desconectar: a chave do site é revogada na hora. Os contatos e o histórico ficam, e conectar o mesmo site de novo retoma de onde parou;
• Ver eventos: cada evento que o site enviou, o contato e o resultado.

Resultado	O que quer dizer
Na fila	Chegou e ainda vai ser processado
Processado	Foi entregue aos fluxos que escutam este evento
Entregue a uma espera	Nenhum fluxo começou, mas uma execução em Aguardar evento seguiu
Nenhum fluxo escuta	Nenhum fluxo ativo usa este evento
Sem contato	O evento não trouxe um contato que dê para encontrar ou criar
Limite de contatos	O contato seria novo, e a conta está no limite do plano
Conta bloqueada	A conta está sem acesso ao envio
Erro	Algo falhou ao processar

Só problemas filtra o que precisa de atenção. O detalhe de cada evento mostra os dados, o contato enviado pelo site e o que cada fluxo fez com ele — Iniciou, Filtrado, Repetido, Em intervalo, Outro site, Sem próxima etapa. Reprocessar manda o evento de novo aos fluxos; Reprocessar mesmo se já foi tratado ignora o Agir uma vez por do gatilho. Os dados de um evento ficam guardados por 30 dias, ou pelo prazo de retenção de mensagens do seu plano, se for menor.

Montar um fluxo com o gatilho Evento do site

1. No editor, adicione um gatilho e escolha Evento do site.
2. Em Evento, escolha o evento na lista, agrupada por origem. Ela mostra os eventos que os seus sites conectados informaram; para um evento do seu próprio código, use Evento personalizado.
3. Em Sites, marque de quais sites o evento vale. Nenhum marcado: qualquer site da conta.
4. O Exemplo do evento mostra os campos — clique num campo para usá-lo nas mensagens.
5. Ligue o gatilho ao primeiro passo, publique e ative o fluxo.

Não há contato para mapear: ele vem no próprio evento. O gatilho tem as mesmas opções do webhook — Filtro, Guardar no contato, Linha do tempo do contato, Com outras automações do contato (o padrão é Rodar junto) e Intervalo mínimo por contato — e mais uma: Agir uma vez por. Com order.id, o mesmo pedido não inicia o fluxo duas vezes em 24 horas, mesmo em wc.order.status_changed, que sai a cada mudança de status. Um mesmo evento entregue duas vezes pelo site nunca inicia o fluxo duas vezes.

Os dados do evento ficam em {{trigger.…}} — {{trigger.order.number}}, {{trigger.order.total:money}}, {{trigger.links.payment_url}} — e o fluxo tem ainda {{trigger.$event.name}} e {{trigger.$site.name}}. Os caminhos de cada evento estão no catálogo.

Aguardar um evento do site

O passo Aguardar evento para a execução até um site conectado enviar um evento que combine com ela. Em Esperar por, escolha Um evento de site e preencha:

• Evento do site — o que se espera, como wc.order.paid;
• Valor desta execução — uma variável desta execução, como {{trigger.order.id}};
• Onde o mesmo valor está no evento esperado — o caminho no evento que vai chegar, como order.id;
• o tempo máximo de espera, obrigatório (até 30 dias).

Os valores são comparados como texto, sem diferenciar maiúsculas. Se o evento chega, a execução segue pela saída Chegou; se o tempo acaba, pela saída Não chegou. Com Guardar como variável, o evento que chegou fica em {{flow.<nome>.…}}.

Receitas

Pix pendente

Quem gerou o Pix e não pagou recebe um lembrete 30 minutos depois — e quem pagou, não.

1. Gatilho Evento do site: wc.order.created. Filtro: order.status igual a pending e order.payment_method igual ao id do seu meio de pagamento Pix (confira no Exemplo do evento).
2. Aguardar evento: wc.order.paid, valor {{trigger.order.id}}, caminho order.id, até 30 minutos.
3. Pela saída Não chegou, mande o lembrete com {{trigger.order.total:money}} e o link {{trigger.links.payment_url}}. Pela saída Chegou, encerre — ou agradeça.

O cliente provavelmente não falou com a loja nas últimas 24 horas: o lembrete precisa ser um template.

Carrinho abandonado

1. Gatilho Evento do site: fcrc.cart.abandoned, com Agir uma vez por cart.id.
2. Um template com o link de volta ao carrinho, {{trigger.cart.recovery_url}}.
3. Aguardar evento: fcrc.cart.recovered, valor {{trigger.cart.id}}, caminho cart.id, até 1 dia.
4. Pela saída Não chegou, o segundo lembrete. Pela saída Chegou, encerre.

Avaliação depois da compra

1. Gatilho Evento do site: wc.order.completed, com Agir uma vez por order.id.
2. Esperar 7 dias.
3. Um template pedindo a avaliação de {{trigger.order.line_items[0].name}}, com o link {{trigger.links.review_urls[0]}}.

Uma condição com customer.is_first_order separa a primeira compra das seguintes — para um agradecimento diferente a quem acabou de conhecer a loja.

Fluxos do WordPress e da plataforma

Os fluxos do construtor do plugin, no WordPress, e os fluxos da plataforma rodam de forma independente: o mesmo pedido pode disparar os dois, e nada avisa nem impede. Evitar mensagens repetidas é responsabilidade de quem opera a loja — ao passar uma automação para a plataforma, desative a do WordPress (e vice-versa).

Eventos personalizados

Com a sincronização ligada, o seu código pode mandar eventos próprios pela função joinotify_track():

functions.php ou um plugin próprio

joinotify_track(
    'custom.quote.requested',
    array( 'quote' => array( 'id' => 991, 'total' => '1290.00' ) ),
    array(
        'ref'        => array( 'kind' => 'wp_user', 'id' => (string) $user_id ),
        'phone'      => '+5511987654321',
        'email'      => '[email protected]',
        'first_name' => 'Ana',
    )
);

• O nome começa com custom. e tem de uma a três partes de letras minúsculas, números e _.
• O segundo argumento é o data do evento: no fluxo, {{trigger.quote.total}}.
• O terceiro diz de quem é o evento e precisa de um ref; sem ele, o evento fica registrado mas não chega a nenhum contato. Para wc_guest e lead, o id é um hash, nunca o e-mail em texto.
• A função devolve o id do evento, ou false com a sincronização desligada ou um nome fora de custom..

Para o editor oferecer o evento com os campos, descreva-o com um exemplo inventado no filtro Joinotify/Cloud_Sync/Catalog:

add_filter( 'Joinotify/Cloud_Sync/Catalog', function( $entries ) {
    $entries[] = array(
        'name'          => 'custom.quote.requested',
        'schemaVersion' => 1,
        'sample'        => array( 'quote' => array( 'id' => 1, 'total' => '100.00' ) ),
    );

    return $entries;
} );

A ação Send webhook no construtor do WordPress

O construtor de fluxos do plugin tem a ação Send webhook, que manda os dados para qualquer URL — o n8n, o Zapier, o Make, o seu ERP ou o gatilho webhook de um fluxo da plataforma:

• o corpo é o dado do gatilho, no mesmo formato dos eventos do site (pedido, cliente, links, usuário, carrinho), ou um JSON seu, com os placeholders do plugin;
• método POST, PUT ou PATCH, e cabeçalhos no formato Nome: valor, um por linha;
• com um segredo, cada chamada leva X-Joinotify-Timestamp e X-Joinotify-Signature-256 (sha256= e o HMAC-SHA256 de timestamp.corpo), para quem recebe conferir a origem.

Só endereços públicos são aceitos. A chamada sai na hora em que o fluxo chega à ação, espera até 10 segundos e não segue redirecionamentos; uma falha vai para o log do plugin. A ação não depende da sincronização.

Privacidade

As ferramentas de privacidade do WordPress (Ferramentas → Exportar dados pessoais e Ferramentas → Apagar dados pessoais) cobrem a sincronização:

• exportar lista o consentimento de marketing da pessoa e o que a fila do site guarda sobre o e-mail dela;
• apagar remove o consentimento e as linhas da fila, e pede ao Joinotify que apague os contatos que este site vinculou à pessoa — encontrados por quem ela é no site, nunca pelo telefone. O contato é apagado inteiro, como no apagamento do painel. Se o Joinotify não puder apagar na hora, o WordPress avisa: apague pelo painel ou rode o pedido de novo.

Desligar a sincronização não apaga o que já chegou: os contatos ficam na conta, onde você pode apagá-los.

Pela API

Os eventos chegam pela rota POST /site-events, e os clientes da carga inicial por POST /contacts/sync, sempre com a chave do site. O formato do envelope está no catálogo de eventos, e as rotas, na referência da API.