For AI agents: the complete documentation index is available at https://docs.clickmax.io/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/features/integrations/shopify.md.
  • Português

      • Integrar Shopify

      Crie um app no Dev Dashboard da sua loja, cole três dados na Clickmax — e os pedidos passam a criar ou atualizar contatos (com a tag shopify), registrar vendas e disparar automações. Você não cadastra webhook nenhum à mão: a Clickmax registra tudo sozinha na sua loja.

      Antes de começar

      • Papel de workspace: Proprietário, Administrador, Editor ou Colaborador. Os papéis Financeiro, Convidado e Atendente não têm acesso a Integrações.
      • Na Shopify você precisa ser proprietário da loja ou ter o papel App developer na organização dela.
      • O endereço da loja precisa ser o .myshopify.com (ex.: sua-loja.myshopify.com). O domínio da sua vitrine (sualoja.com.br) não serve — a API da Shopify só responde no endereço .myshopify.com.
      • O app tem que ser criado na organização da sua própria loja. App criado em outra organização (por exemplo, numa conta de parceiro separada) é recusado pela Shopify com "shop_not_permitted", e a Clickmax mostra esse erro na hora de criar a integração.

      Não procure por "Configurações → Desenvolver apps". A Shopify encerrou a criação de apps por ali, e é por isso que não existe mais um token pronto para copiar. Apps novos nascem no Dev Dashboard, e a Clickmax gera o acesso sozinha a partir do Client ID e do Client secret.

      Passo a passo

      1. Na Clickmax, abra Integrações e selecione o card Shopify.
      2. Em outra aba, acesse o Dev Dashboard e entre com a conta da sua loja.
      3. Clique em Create app e dê um nome (ex.: Clickmax). Não precisa escolher interface nem framework: é um app só de API.
      4. Na aba Versions, informe os escopos read_orders, read_customers e read_products e clique em Release para publicar a versão.
      5. Na página inicial do app, clique em Install app e selecione a sua loja.
      6. Em Settings, copie o Client ID e o Client secret.
      7. Na Clickmax, preencha Domínio da loja (sua-loja.myshopify.com), Client ID do app e Client secret do app.
      8. Informe um Apelido para a integração e clique em Criar integração.

      Pronto. A Clickmax valida as credenciais, registra os webhooks na sua loja e passa a receber os pedidos.

      Precisa mudar os escopos depois? Publique uma nova versão do app com os escopos novos e aprove a atualização na loja. Versões novas não são aplicadas sozinhas às lojas onde o app já está instalado.

      O que passa a chegar

      Cada evento com e-mail cria ou atualiza um contato com a tag shopify, registra uma atividade no histórico do contato e pode disparar automações. Parte deles também registra uma venda.

      Evento na ShopifyRegistra vendaStatus da venda
      Pedido criadosim, se ainda não estiver pagoAguardando
      Pedido pagosimAprovada
      Pedido canceladosimCancelada
      Pedido enviadonão—
      Reembolso criadosimReembolsado
      Contestação criadasimChargeback
      Cliente cadastradonão—

      Pontos que costumam gerar dúvida:

      • Pedido ainda não pago entra como Aguardando. É o caso de pix, boleto, pagamento na entrega e pedido com captura manual. Quando o pagamento é confirmado, a mesma venda passa a Aprovada — não são duas vendas. Pedido que já nasce pago (cartão) entra direto como Aprovada.
      • Venda com status Aguardando não conta como faturamento. Os indicadores de receita, o ticket médio e o LTV do contato somam apenas vendas aprovadas.
      • Reembolso e contestação não mudam o valor da venda. Um reembolso parcial de R$ 10 num pedido de R$ 149,90 marca a venda como Reembolsada mantendo os R$ 149,90 — o valor devolvido aparece na atividade do contato.
      • Uma venda por pedido, não por produto. Um pedido com três produtos gera uma venda com o total do pedido e três atividades no histórico do contato, uma por produto.
      • Pedido pago marca o contato como cliente.
      • Pedidos sem e-mail são ignorados (venda de balcão/PDV ou compra como convidado sem e-mail), porque sem e-mail não é possível identificar o contato.
      • Contestação só existe em lojas com Shopify Payments. Se a sua loja processa cartão por um gateway de terceiro (Mercado Pago, PagBank, Appmax…), é aquele gateway que recebe a contestação, e a Shopify nunca avisa a Clickmax. O gatilho continua disponível, mas não dispara nesse cenário.

      Filtro por produto

      Nos gatilhos você pode filtrar pelo produto: a Clickmax lista os produtos direto da sua loja usando as credenciais do app. O gatilho de cliente cadastrado não tem filtro de produto — não há pedido nesse evento.

      Relacionados

      Se não funcionou

      • Não consigo criar a integração: confira o Domínio da loja (tem de terminar em .myshopify.com) e o par Client ID / Client secret — é fácil trocar um pelo outro. Veja os códigos de erro.
      • Erro dizendo que o app não pertence à mesma organização da loja: o app foi criado numa organização diferente. Crie o app no Dev Dashboard da própria loja e instale nela.
      • A criação falhou falando em webhook: a Clickmax registra os webhooks na sua loja no momento da criação. Se o app não tiver os escopos read_orders, read_customers e read_products, o registro é recusado. Volte ao app, publique uma versão com os escopos certos, aprove na loja e crie a integração de novo.
      • Nenhum evento chega: confira se o campo Client secret do app tem mesmo o Client secret (e não o Client ID). É com ele que a Shopify assina cada webhook; com o valor errado, a Clickmax rejeita toda entrega.
      • Parei de receber depois de trocar as credenciais: trocar o Client ID, o Client secret ou o domínio re-registra os webhooks. Se você desinstalou o app na Shopify, os webhooks somem junto — reinstale e edite a integração com as credenciais atuais.
      • Um pedido específico não chegou: pedidos sem e-mail do comprador são descartados. Confira o pedido na Shopify.