Do zero à primeira chamada bem-sucedida na API do GS Engage, com passo de verificação e a criação do seu primeiro lead.

Quickstart: sua primeira chamada em 5 minutos

Pegue sua chave, confirme que ela funciona e crie seu primeiro lead — sem enrolação.

Oi! Se você nunca tocou na API do GS Engage, este é o lugar certo para começar. A meta aqui é simples: em menos de 5 minutos você vai sair do zero, confirmar que sua credencial funciona e fazer uma chamada de verdade que já entrega valor para o time de vendas.

Um endpoint (o endereço de uma operação da API, tipo uma "porta" para cada ação) sempre mora sob a base https://api.gsengage.com/api/v1. Guarde esse começo de URL — ele se repete em tudo.

O que você precisa

Só uma conta no GS Engage com acesso a Configurações e um terminal (ou Node/Python instalado). Não precisa configurar servidor nem SDK.

Antes de começar: a apiKey é uma senha

A API do GS Engage se autentica por uma apiKey enviada como parâmetro na URL, no formato ?apiKey=SUA_CHAVE. Não é um header — vai direto no endereço da requisição.

Isso é prático, mas exige cuidado.

Importante

Como a apiKey vai na URL, ela pode vazar em lugares que você nem imagina: logs de servidor, histórico do navegador e links copiados e colados. Trate a chave como uma senha. Guarde em variável de ambiente, nunca cole em canais públicos (Slack, e-mail, tickets) e nunca comite no Git.

Toda chamada é real

Não existe ambiente de teste (sandbox) separado. Toda requisição afeta dados de produção. Enquanto estiver experimentando, priorize operações de leitura (GET) — e leia com atenção antes de qualquer escrita (POST/PATCH/DELETE).

Os 3 passos

Pegue sua apiKey na plataforma

Entre no GS Engage e vá em Configurações → Configurações de API. Lá você encontra sua apiKey — uma sequência de cerca de 40 caracteres.

Copie a chave e guarde numa variável de ambiente. Assim ela não fica exposta nos exemplos abaixo:

export GS_API_KEY="sua_chave_de_40_caracteres_aqui"

Dica

Usar $GS_API_KEY no lugar da chave literal já resolve metade do risco de vazamento. Faça isso desde a primeira chamada.

Confirme que a chave funciona

Antes de criar ou alterar qualquer coisa, vamos só verificar se a credencial está válida. Para isso usamos uma chamada leve e somente leitura: listar os campos personalizados do seu projeto, com GET /api/v1/custom-fields.

Escolha a sua linguagem:

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

const apiKey = process.env.GS_API_KEY;

const res = await fetch(
  `https://api.gsengage.com/api/v1/custom-fields?apiKey=${apiKey}`
);

console.log(res.status);
console.log(await res.json());

import os
import requests

api_key = os.environ["GS_API_KEY"]

res = requests.get(
    "https://api.gsengage.com/api/v1/custom-fields",
    params={"apiKey": api_key},
)

print(res.status_code)
print(res.json())

Como saber se deu certo

Você deve receber um HTTP 200 com uma lista (um array). Se o projeto ainda não tem campos personalizados, essa lista pode vir vazia: []. Isso é normal e também confirma que a chave funciona — o que importa é o status 200.

Se vier HTTP 401 (Unauthorized), a apiKey está ausente ou incorreta: volte ao Passo 1, confira se copiou a chave inteira (os ~40 caracteres, sem espaços) e se ela está mesmo na URL como ?apiKey=....

Repare que este endpoint é paginado ({ "data": [...], "meta": {...} }), como a maioria — os campos ficam em data.

Faça sua primeira chamada útil: crie um lead

Verificação passou? Então vamos ao objetivo de negócio de verdade: cadastrar um novo lead para o time trabalhar. Isso é POST /api/v1/leads.

A única regra obrigatória: além do nome (fullName), o lead precisa de pelo menos um contato. Os contatos vão em três listas — emails, phones e mobiles — e cada item tem o formato { "value": "...", "label": "..." }.

curl -X POST "https://api.gsengage.com/api/v1/leads?apiKey=$GS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Maria Oliveira",
    "emails": [
      { "value": "maria.oliveira@empresa.com", "label": "Trabalho" }
    ]
  }'

const apiKey = process.env.GS_API_KEY;

const res = await fetch(
  `https://api.gsengage.com/api/v1/leads?apiKey=${apiKey}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      fullName: "Maria Oliveira",
      emails: [
        { value: "maria.oliveira@empresa.com", label: "Trabalho" },
      ],
    }),
  }
);

console.log(res.status);
console.log(await res.json());

import os
import requests

api_key = os.environ["GS_API_KEY"]

res = requests.post(
    "https://api.gsengage.com/api/v1/leads",
    params={"apiKey": api_key},
    json={
        "fullName": "Maria Oliveira",
        "emails": [
            {"value": "maria.oliveira@empresa.com", "label": "Trabalho"},
        ],
    },
)

print(res.status_code)
print(res.json())

O que acabou de acontecer

Um lead criado via API entra marcado como Levantada de Mão (no jargão técnico, acquisitionType: ACTIVE_INBOUND) e aparece no topo da fila de atividades do vendedor. Ou seja: quem foi cadastrado agora já vira prioridade de contato. Missão cumprida — essa foi sua primeira chamada útil.

Se algo deu errado

As mensagens de erro da API já vêm em português e costumam dizer exatamente o que faltou. Vale reaproveitá-las.

Status	O que significa	Como corrigir
400 Bad Request	Faltou um campo ou o formato está errado (ex.: nenhum contato no lead). O corpo traz `errors` com `field` e `message`.	Leia o `field` apontado e ajuste o JSON. Lembre: pelo menos um contato é obrigatório.
401 Unauthorized	apiKey ausente ou inválida.	Confira se a chave está na URL como `?apiKey=...` e se copiou os ~40 caracteres completos.
404 Not Found	O endereço ou o recurso não existe.	Revise o caminho — tudo mora sob `/api/v1`.
429 Too Many Requests	Você passou do limite: 200 leituras/min ou 100 escritas/min por janela de 60s.	Espere os segundos indicados no header `Retry-After` e tente de novo (backoff exponencial).