Integração Shopify + Leavo

Integração via Webhook – Shopify + Leavo

1. Visão Geral

A Shopify é uma das principais plataformas de e-commerce do mundo, permitindo que empreendedores criem e gerenciem lojas virtuais. A integração com o Leavo permite automatizar qualificação de compradores e sincronizar dados de vendas em tempo real.

Casos de uso principais:

• Qualificar compradores no Leavo quando pedido é criado
• Enviar leads qualificados do Leavo para criar clientes na Shopify
• Sincronizar dados de pedidos com status de leads
• Automatizar follow-up pós-compra

Fluxos disponíveis:

• ✅ Leavo → Shopify: Via Admin API REST (criar clientes, pedidos)
• ✅ Shopify → Leavo: Webhooks notificam eventos da loja
• ✅ Shopify Flow: Automações internas para HTTP requests

Diferencial: E-commerce robusto, HMAC validation, Shopify Flow para automações no-code, GraphQL Admin API.

2. Documentação Oficial

Shopify:

• Webhooks Reference
• About Webhooks
• REST Admin API
• Shopify Flow

Leavo:

• Painel de Webhooks

3. Recursos disponíveis via Webhook

3.1 Eventos do Shopify

Principais eventos para integração com Leavo:

Eventos mais relevantes: orders/create, customers/create, orders/fulfilled

4. Como configurar webhooks

4.1 FLUXO 1: Shopify → Leavo (Notificar Pedidos)

Permite que pedidos na Shopify sejam qualificados no Leavo.

Passo 1: Criar Webhook de Entrada no Leavo

1. No Leavo, vá em Webhooks → Entrada
2. Clique em "+ Criar Webhook"

Configurar:

• Nome: Receber de Shopify - Pedidos
• Descrição: Qualifica compradores da loja
• Webhook ativo: LIGADO

Passo 2: Copiar URL do Leavo

Passo 3: Configurar Webhook no Painel Shopify

Via Painel Admin:

1. No Admin Shopify, vá em Configurações
2. Clique em Notificações
3. Role até a seção Webhooks
4. Clique em "Criar webhook"

Configurar:

1. Clique em "Salvar"

Passo 4: Estrutura do Payload do Shopify

Exemplo de orders/create:

{
  "id": 1234567890,
  "email": "joao@example.com",
  "created_at": "2025-12-11T18:00:00-03:00",
  "total_price": "299.90",
  "currency": "BRL",
  "financial_status": "paid",
  "customer": {
    "id": 987654321,
    "email": "joao@example.com",
    "first_name": "João",
    "last_name": "Silva",
    "phone": "+5511999999999",
    "orders_count": 1,
    "total_spent": "299.90"
  },
  "billing_address": {
    "first_name": "João",
    "last_name": "Silva",
    "company": "Empresa ABC",
    "city": "São Paulo",
    "province": "SP",
    "country": "Brazil"
  },
  "line_items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "price": "299.90",
      "sku": "PROD-001"
    }
  ]
}

Passo 5: Headers de Segurança do Shopify

Headers enviados:

Passo 6: Mapear Campos no Leavo

4.2 FLUXO 2: Leavo → Shopify (Criar Clientes)

Permite que leads qualificados no Leavo virem clientes na Shopify.

Passo 1: Obter Access Token da Shopify

1.1 Criar App Customizado:

1. No Admin Shopify, vá em Configurações → Apps e canais de vendas
2. Clique em "Desenvolver apps"
3. Clique em "Criar um app"
4. Nomeie: Leavo Integration

1.2 Configurar Permissões:

Em Admin API access scopes, selecione:

• read_customers
• write_customers
• read_orders

1.3 Instalar App:

1. Clique em "Instalar app"
2. Copie o Admin API access token

Passo 2: Configurar Middleware (n8n)

2.1 Nó Function:

// Transformar payload do Leavo para Shopify
const leavo = $json.body.data;

const nameParts = leavo.nome.split(' ');
const firstName = nameParts[0];
const lastName = nameParts.slice(1).join(' ') || firstName;

return {
  json: {
    customer: {
      first_name: firstName,
      last_name: lastName,
      email: leavo.email,
      phone: leavo.telefone,
      tags: "Leavo, Qualificado",
      note: `Lead qualificado via Leavo. Status: ${leavo.status}`
    }
  }
};

2.2 Nó HTTP Request:

4.3 FLUXO 3: Shopify Flow (Automações Internas)

Shopify Flow permite criar automações no-code dentro da Shopify.

Passo 1: Acessar Shopify Flow

1. No Admin Shopify, vá em Apps
2. Abra Shopify Flow
3. Clique em "Create workflow"

Passo 2: Configurar HTTP Request

Body JSON:

{
  "name": "{{order.customer.firstName}} {{order.customer.lastName}}",
  "email": "{{order.customer.email}}",
  "phone": "{{order.customer.phone}}",
  "order_value": "{{order.totalPrice}}",
  "source": "Shopify"
}

5. Testando a integração

✅ Checklist - Shopify → Leavo

Leavo:

• Webhook de entrada criado
• URL copiada

Shopify:

• Webhook configurado no Admin
• Evento selecionado
• URL do Leavo configurada

Teste:

• Criar pedido de teste na Shopify
• Webhook disparou
• Lead criado no Leavo

✅ Checklist - Leavo → Shopify

Shopify:

• App customizado criado
• Access Token obtido
• Permissões configuradas

Middleware (n8n):

• Workflow criado
• Transformation implementada
• HTTP Request configurado

6. Estrutura de Payloads

6.1 Shopify → Leavo

{
  "id": 1234567890,
  "email": "maria@example.com",
  "total_price": "499.90",
  "customer": {
    "email": "maria@example.com",
    "first_name": "Maria",
    "last_name": "Santos",
    "phone": "+5511988887777"
  },
  "billing_address": {
    "company": "Tech Solutions"
  }
}

6.2 Leavo → Shopify

curl -X POST 'https://loja.myshopify.com/admin/api/2025-10/customers.json' \
-H 'X-Shopify-Access-Token: YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "customer": {
    "first_name": "Pedro",
    "last_name": "Oliveira",
    "email": "pedro@example.com",
    "phone": "5511977776666",
    "tags": "Leavo, Qualificado"
  }
}'

7. Observações e Limitações

7.1 Limitações do Shopify

8. Boas Práticas

8.1 Validar HMAC

✅ Valide autenticidade dos webhooks:

const crypto = require('crypto');

function validateShopifyWebhook(body, hmacHeader, sharedSecret) {
  const hash = crypto
    .createHmac('sha256', sharedSecret)
    .update(body, 'utf8')
    .digest('base64');
    
  return hash === hmacHeader;
}

8.2 Use Tags para Segmentação

✅ Adicione tags aos clientes:

• Leavo - Origem
• Qualificado - Status
• Hot-Lead - Prioridade

9. Troubleshooting

9.1 Webhook não dispara

9.2 Cliente não cria

10. Casos de Uso

10.1 Follow-up Pós-Compra

Objetivo: Compradores recebem follow-up

Fluxo:

10.2 Lead para Cliente

Objetivo: Lead qualificado vira cliente

Fluxo:

Referências

• Shopify Webhooks Reference
• Shopify REST Admin API
• Painel de Webhooks Leavo