Growth Station
DocumentaçãoAPI (Desenvolvedores)Guias por caso de usoEnviar leads do CRM ou planilha para o GS Engage

Enviar leads do CRM ou planilha para o GS Engage

Sincronize leads vindos de formulário, CRM ou planilha criando cada um via API, sem gerar duplicados e respeitando o limite de requisições.

Enviar leads do CRM ou planilha para o GS Engage

Traga cada novo lead da sua origem externa para dentro do GS Engage, prontinho no topo da fila do vendedor.

Você já captura leads em algum lugar: um formulário do site, o seu CRM, uma planilha que o time de marketing atualiza. O que você quer é simples: cada lead novo aparecer automaticamente no GS Engage, na frente do vendedor certo, sem digitação manual e sem cadastro repetido.

Este guia mostra como fazer isso de duas formas: com código (chamando a API) ou sem código (usando o Zapier). Se a ideia de "chamar a API" ainda soa técnica, relaxa: um endpoint é só um endereço na internet que recebe seus dados. Vamos passar por cada parte.

O que você ganha com isso

Todo lead criado pela API entra marcado como Levantada de Mão e aparece no topo da fila de atividades do vendedor. Ou seja: o lead quente que acabou de chegar não fica esperando.

Antes de qualquer código, vale entender o caminho que cada lead percorre. A regra de ouro é: primeiro procure, depois crie — assim você nunca cadastra a mesma pessoa duas vezes.

graph TD
A["Lead novo na origem<br/>(formulário / CRM / planilha)"] --> B["Busca no GS Engage<br/>GET /api/v1/leads?search="]
B --> C{"Já existe?"}
C -->|"Sim"| D["Atualiza o existente<br/>PATCH /api/v1/leads/{leadId}"]
C -->|"Não"| E["Cria o lead<br/>POST /api/v1/leads"]
E --> F["Lead entra como<br/>Levantada de Mão"]
F --> G["Aparece no topo da<br/>fila do vendedor"]

Você vai precisar de duas coisas.

Sua chave de API (apiKey)obrigatório

Crie na plataforma em Configurações → Configurações de API. É um texto de cerca de 40 caracteres. Trate como senha.

Os campos personalizados já criadosopcional

Se você quer preencher campos além dos padrão (ex.: "Origem da campanha"), eles precisam já existir no projeto. Veja o alerta abaixo.

A apiKey vai na URL — cuide dela como senha

A autenticação é feita por query param na URL, no formato ?apiKey=SUA_CHAVE (não é um header). Como ela aparece na URL, ela também aparece em logs de servidor, no histórico do navegador e em links compartilhados. Guarde em variável de ambiente e nunca cole em canais públicos.

Toda chamada é real — não existe ambiente de teste

O GS Engage não tem sandbox separado. Qualquer POST cria um lead de verdade, em produção. Ao experimentar, comece pelas leituras (GET) e só rode a criação quando tiver certeza dos dados.

1

Valide sua chave

Faça uma leitura leve para confirmar que a chave funciona. Um 200 com uma lista (mesmo vazia, []) já confirma tudo.

curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=SUA_CHAVE"

Essa mesma chamada te devolve os campos personalizados do projeto — guarde-a, porque você vai precisar dos identificadores deles mais adiante.

2

Procure antes de criar (evite duplicados)

Use o filtro search para descobrir se o lead já existe. Ele busca por nome, empresa, e-mail ou telefone.

curl "https://api.gsengage.com/api/v1/leads?search=maria@empresa.com&apiKey=SUA_CHAVE"

Se a resposta trouxer resultados em data, o lead já existe — atualize com PATCH /api/v1/leads/{leadId} em vez de criar de novo. Se vier vazio, siga para a criação.

3

Crie o lead

Envie os dados com POST. O único requisito obrigatório é ao menos um contato (um e-mail, telefone ou celular).

curl -X POST "https://api.gsengage.com/api/v1/leads?apiKey=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "company": "Empresa Exemplo Ltda",
    "role": "Gerente de Compras",
    "emails": [{ "value": "maria@empresa.com", "label": "Trabalho" }],
    "mobiles": [{ "value": "+5511999998888", "label": "WhatsApp" }]
  }'

A resposta traz o lead criado com seu identificador. Pronto: ele já está na fila do vendedor como Levantada de Mão.

Cada lead do seu CRM ou planilha precisa ser "traduzido" para o formato do GS Engage. A parte que mais confunde são os contatos: eles não são um texto simples, mas listas de objetos no formato value / label.

Campo na sua origemCampo no GS EngageFormato
Nomenametexto
Empresacompanytexto
Cargoroletexto
E-mail(s)emailslista de { "value", "label" }
Telefone(s) fixo(s)phoneslista de { "value", "label" }
Celular(es) / WhatsAppmobileslista de { "value", "label" }
Campos extrascustomFieldsver seção abaixo

O value é o dado em si (o número, o e-mail). O label é um rótulo livre que ajuda o vendedor a saber do que se trata (ex.: "Trabalho", "Pessoal", "WhatsApp"). Você pode enviar vários contatos em cada lista.

{
  "name": "João Pereira",
  "company": "Comércio ABC",
  "role": "Diretor",
  "emails": [
    { "value": "joao@abc.com", "label": "Trabalho" },
    { "value": "joao.pessoal@gmail.com", "label": "Pessoal" }
  ],
  "phones": [
    { "value": "+551133334444", "label": "Escritório" }
  ],
  "mobiles": [
    { "value": "+5511988887777", "label": "WhatsApp" }
  ]
}

Lembre-se: pelo menos um contato

A criação exige ao menos um contato — um item em emails, phones ou mobiles. Um lead sem nenhuma forma de contato é recusado com erro 400.

Campos personalizados (customFields)

Se a sua planilha tem colunas como "Origem da campanha" ou "Faturamento estimado", você as envia dentro de customFields.

O campo personalizado precisa existir antes no projeto

Você não cria campos personalizados pela API de leads. Eles precisam já estar cadastrados no projeto. Liste os que existem com GET /api/v1/custom-fields e use o identificador de cada um. Enviar um campo que não existe resulta em erro de validação.

# 1) Descubra os campos que existem e seus identificadores
curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=SUA_CHAVE"

O resultado é uma lista (um array puro, sem paginação). Use o identificador de cada campo ao montar o customFields do seu lead, casando com o valor que veio da sua origem.

Ao importar uma planilha inteira, você vai fazer muitas chamadas seguidas. Aqui entra o rate limit (limite de requisições): você pode fazer até 100 escritas por minuto (POST/PATCH) em uma janela de 60 segundos. Se passar disso, a API responde 429 com o header Retry-After dizendo quantos segundos esperar.

A boa prática é: para cada lead, buscar antes (evitar duplicado), criar e, se levar um 429, esperar e tentar de novo (backoff).

const BASE = "https://api.gsengage.com/api/v1";
const apiKey = process.env.GS_ENGAGE_API_KEY; // nunca deixe a chave no código

const leads = [
  { name: "Maria Silva", company: "Empresa Exemplo", role: "Gerente",
    emails: [{ value: "maria@empresa.com", label: "Trabalho" }] },
  { name: "João Pereira", company: "Comércio ABC", role: "Diretor",
    mobiles: [{ value: "+5511988887777", label: "WhatsApp" }] },
];

async function callWithBackoff(url, options = {}) {
  while (true) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 5);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue; // tenta de novo respeitando o Retry-After
    }
    return res;
  }
}

async function upsertLead(lead) {
  const email = lead.emails?.[0]?.value ?? lead.mobiles?.[0]?.value;

  // 1) Procura antes de criar
  const search = await callWithBackoff(
    `${BASE}/leads?search=${encodeURIComponent(email)}&apiKey=${apiKey}`
  );
  const found = (await search.json()).data ?? [];
  if (found.length > 0) {
    console.log(`Já existe: ${lead.name} — pulando`);
    return;
  }

  // 2) Cria
  const res = await callWithBackoff(`${BASE}/leads?apiKey=${apiKey}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(lead),
  });
  if (!res.ok) {
    const { error } = await res.json(); // erros vêm dentro de "error"
    console.error(`Falha em ${lead.name}: ${error?.message}`);
    return;
  }
  console.log(`Criado: ${lead.name}`);
}

for (const lead of leads) {
  await upsertLead(lead); // sequencial, sem estourar o limite
}
import os, time, requests

BASE = "https://api.gsengage.com/api/v1"
api_key = os.environ["GS_ENGAGE_API_KEY"]  # nunca deixe a chave no código

leads = [
    {"name": "Maria Silva", "company": "Empresa Exemplo", "role": "Gerente",
     "emails": [{"value": "maria@empresa.com", "label": "Trabalho"}]},
    {"name": "João Pereira", "company": "Comércio ABC", "role": "Diretor",
     "mobiles": [{"value": "+5511988887777", "label": "WhatsApp"}]},
]

def call_with_backoff(method, url, **kwargs):
    while True:
        res = requests.request(method, url, **kwargs)
        if res.status_code == 429:
            wait = int(res.headers.get("Retry-After", "5"))
            time.sleep(wait)  # respeita o Retry-After e tenta de novo
            continue
        return res

def upsert_lead(lead):
    email = (lead.get("emails") or lead.get("mobiles"))[0]["value"]

    # 1) Procura antes de criar
    search = call_with_backoff(
        "GET", f"{BASE}/leads", params={"search": email, "apiKey": api_key}
    )
    if search.json().get("data"):
        print(f"Já existe: {lead['name']} — pulando")
        return

    # 2) Cria
    res = call_with_backoff(
        "POST", f"{BASE}/leads",
        params={"apiKey": api_key}, json=lead
    )
    if not res.ok:
        print(f"Falha em {lead['name']}: {res.json().get('message')}")
        return
    print(f"Criado: {lead['name']}")

for lead in leads:
    upsert_lead(lead)  # sequencial, sem estourar o limite
Fazer
  • Busque com search antes de cada criação para não duplicar leads.
  • Respeite o Retry-After quando receber 429 — espere e tente de novo.
  • Guarde a apiKey em variável de ambiente.
Não fazer
  • Não dispare centenas de POST em paralelo — você estoura o limite de 100/min.
  • Não envie customFields que ainda não existem no projeto.
  • Não cole a URL com a chave em chats, tickets ou commits.

Se você não quer manter um script rodando, dá para conectar a sua origem (formulário, CRM, planilha) ao GS Engage usando o Zapier, sem código. O GS Engage expõe integração nativa com o Zapier — você monta um fluxo visual "quando chegar um lead novo aqui, crie o lead no GS Engage". Ferramentas como Make e n8n também conseguem consumir a mesma API REST.

O que acontece se eu criar o mesmo lead duas vezes?

Você fica com dois cadastros separados. Por isso o passo da busca com search= é importante: procure por e-mail ou telefone antes de criar e, se já existir, atualize com PATCH /api/v1/leads/{leadId} em vez de criar de novo.

Preciso preencher nome e empresa para criar um lead?

O único requisito obrigatório é ao menos um contato (um item em emails, phones ou mobiles). Nome, empresa e cargo são recomendados para o vendedor, mas o que trava a criação sem contato é o erro 400.

Como envio celular e WhatsApp?

Ambos vão na lista mobiles, cada um como { "value": "número", "label": "rótulo" }. Use o label para diferenciar (ex.: "WhatsApp", "Pessoal").

Recebi um erro 400. O que faço?

O corpo do erro vem dentro de error: error.message e uma lista error.errors com o field (o caminho do campo) e a explicação de cada problema, já em português. Leia o field para saber qual campo corrigir — geralmente é um contato faltando ou um campo personalizado inexistente.

Onde o lead aparece depois de criado?

Todo lead criado via API entra como Levantada de Mão e vai para o topo da fila de atividades do vendedor, sinalizando que é um contato quente e recém-chegado.

Este artigo foi útil?

Nesta página

Última atualização