Autenticação com apiKey
Aprenda a criar sua apiKey, usá-la na URL das chamadas e proteger essa chave como se fosse uma senha.
Autenticação com apiKey
Toda chamada à API do GS Engage precisa provar quem você é. Isso é feito com uma chave única — a sua apiKey.
Você quer que os seus sistemas conversem com o GS Engage — puxar leads, criar prospecções, receber avisos por webhook. Antes de qualquer coisa, a API precisa ter certeza de que é você mesmo do outro lado. Essa "prova de identidade" é a sua apiKey (chave de API).
Nesta página você vai entender o que é essa chave, onde criá-la, como usá-la nas chamadas e — o mais importante — como protegê-la para que ninguém use o seu acesso indevidamente.
Informação
Um lembrete de vocabulário: quando falamos em endpoint, estamos falando de um endereço da API que executa uma ação (por exemplo, listar leads ou criar uma prospecção). Cada endpoint fica sob a URL base https://api.gsengage.com, no caminho /api/v1.
A apiKey é um texto único (com cerca de 40 caracteres) que representa o seu acesso à API. Pense nela como a senha da sua integração: quem tem a chave consegue fazer, em nome da sua empresa, tudo o que a API permite — inclusive criar e alterar dados de verdade.
Por isso, a regra número um é simples: trate a apiKey como uma senha.
A chave é gerada dentro da própria plataforma do GS Engage. Você não precisa abrir chamado nem falar com o suporte.
Abra as Configurações
No GS Engage, acesse o menu Configurações.
Entre em Configurações de API
Dentro de Configurações, abra a seção Configurações de API. É ali que ficam as suas chaves.
Gere e copie a chave
Gere a apiKey e copie na hora. Guarde em um lugar seguro (veja a seção de segurança abaixo). Ela funciona imediatamente, sem etapa de ativação.
Guarde com carinho
Copie a chave para um cofre de senhas ou uma variável de ambiente assim que criá-la. É muito mais fácil guardar bem desde o início do que ter que revogar e refazer tudo depois.
No GS Engage, a apiKey vai na própria URL da requisição, como um parâmetro chamado apiKey. Isso se chama query param (parâmetro de consulta) — é aquele pedaço que vem depois do ? no endereço.
Não é um header
Diferente de muitas APIs, aqui a chave não vai em um cabeçalho (header) Authorization. Ela vai na URL, no formato ?apiKey=SUA_CHAVE. Se você tentar mandar por header, a API vai responder que você não está autenticado.
O formato é sempre este:
https://api.gsengage.com/api/v1/CAMINHO?apiKey=SUA_CHAVEVamos ver um exemplo real. Para listar os seus leads, o gatilho é uma chamada GET ao endpoint de leads, com a sua chave na URL:
curl "https://api.gsengage.com/api/v1/leads?apiKey=$GSENGAGE_API_KEY"const apiKey = process.env.GSENGAGE_API_KEY;
const resposta = await fetch(
`https://api.gsengage.com/api/v1/leads?apiKey=${apiKey}`
);
const leads = await resposta.json();import os
import requests
api_key = os.environ["GSENGAGE_API_KEY"]
resposta = requests.get(
"https://api.gsengage.com/api/v1/leads",
params={"apiKey": api_key},
)
leads = resposta.json()Se a chave estiver correta, você recebe um 200 (sucesso) com a sua lista de leads. Na prática, isso significa que a integração está autenticada e pronta para trabalhar. Se a chave estiver ausente ou errada, você recebe um 401 Unauthorized — a API está dizendo "não sei quem é você".
Precisa combinar mais parâmetros?
Quando o endpoint aceitar filtros ou paginação (como page, limit ou search), você simplesmente encadeia os parâmetros com &. Exemplo: ?apiKey=SUA_CHAVE&limit=50&page=2.
Antes de sair integrando, vale um teste rápido e inofensivo só para confirmar que a chave está valendo. Use o endpoint de campos personalizados: ele é leve, é somente leitura e exige apiKey.
O gatilho:
curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=$GSENGAGE_API_KEY"Um 200 com uma lista confirma que está tudo certo. A resposta pode até vir vazia ([]) se o seu projeto ainda não tiver campos personalizados — e tudo bem, isso continua significando que a chave funciona. O que importa aqui é o 200, não o conteúdo.
Por que esse endpoint?
Escolhemos GET /api/v1/custom-fields de propósito: ele só lê dados e não altera nada. É o jeito mais seguro de validar a chave sem risco de mexer na sua operação.
Sua apiKey pode vazar sem você perceber
Como a apiKey viaja dentro da URL, ela acaba sendo registrada e copiada em vários lugares que você talvez nem imagine:
- Logs de servidor — a URL completa (com a chave) costuma ser gravada nos registros de acesso de servidores, proxies e balanceadores.
- Histórico do navegador — se a URL for aberta em um navegador, a chave fica salva no histórico.
- Links compartilhados — ao colar uma URL de exemplo num chat, e-mail, ticket, print ou documento, você está compartilhando a chave junto.
- Ferramentas de monitoramento e analytics — muitas capturam a URL inteira das requisições.
Qualquer pessoa com uma dessas cópias da chave pode agir em nome da sua empresa, inclusive alterar dados reais.
Boas práticas obrigatórias:
- Trate como senha. Nunca digite a chave "na mão" dentro de código, prints ou mensagens.
- Use variável de ambiente. Guarde a chave numa variável (como
GSENGAGE_API_KEY) e leia dela no código — foi o que fizemos em todos os exemplos acima. - Nunca suba a chave para um repositório, especialmente se for público. Adicione o arquivo de configuração (por exemplo,
.env) ao seu.gitignore. - Não cole a chave em canais públicos — grupos, fóruns, issues abertas, prints em redes sociais.
- Se desconfiar que vazou, revogue na hora. Volte em Configurações → Configurações de API, revogue a chave comprometida e gere uma nova. É rápido e corta o acesso indevido imediatamente.
Bons e maus usos na prática
- Ler a chave de uma variável de ambiente (
GSENGAGE_API_KEY) e montá-la na URL só na hora da chamada. - Guardar a chave num cofre de senhas ou no gerenciador de secrets da sua infraestrutura.
- Manter o arquivo
.envno.gitignorepara ele nunca ir parar no repositório. - Revogar e regerar a chave imediatamente ao menor sinal de vazamento.
- Escrever a chave direto no código-fonte (
?apiKey=ab12cd34...) e commitar no Git. - Colar uma URL de exemplo com a chave real em um chamado de suporte, chat ou print de tela.
- Subir a chave para um repositório público "só pra testar rápido".
- Continuar usando uma chave que você suspeita ter exposto, na esperança de que ninguém tenha visto.
Este é o ponto mais importante para você não ter sustos.
Não há sandbox — os dados são de produção
O GS Engage não tem um ambiente de teste separado nem uma "chave de teste". Existe uma única API, com dados reais.
Isso significa que toda chamada afeta a sua operação de verdade: um POST de lead cria um lead que aparece para o seu time; uma prospecção iniciada entra na fila do vendedor; um webhook criado começa a disparar.
Como se proteger enquanto experimenta:
- Comece pelas leituras. Use endpoints
GET(como/api/v1/custom-fieldse/api/v1/leads) para explorar — eles não mudam nada. - Só faça escrita quando tiver certeza. Antes de qualquer
POST,PATCH,PUTouDELETE, confirme os dados. Um lead criado via API, por exemplo, entra marcado como Levantada de Mão e vai direto para o topo da fila de atividades do vendedor.
Dica de quem já passou por isso
Ao construir uma integração nova, deixe as ações de escrita comentadas ou atrás de uma confirmação até validar o fluxo inteiro só com leituras. Assim você entende o comportamento da API sem gerar ruído na operação do time.
Recebi 401 Unauthorized. O que houve?
O 401 significa que a API não reconheceu a sua chave — ela está ausente, incorreta ou foi revogada. Confira se você incluiu ?apiKey=SUA_CHAVE na URL, se a chave foi copiada por inteiro (sem espaços ou quebras) e se ela ainda está ativa em Configurações → Configurações de API. As mensagens de erro do GS Engage já vêm em português para facilitar o diagnóstico.
Posso mandar a apiKey no header Authorization?
Não. No GS Engage a autenticação é feita exclusivamente pelo query param ?apiKey=SUA_CHAVE na URL. Enviar por header não autentica a chamada.
A chave expira sozinha?
A chave continua válida até você revogá-la. Se ela vazar ou você não precisar mais dela, revogue e gere uma nova em Configurações de API.
Preciso saber programar para usar a API?
Não necessariamente. O GS Engage expõe gatilhos nativos no Zapier (por exemplo, gatilhos de webhook), o que permite montar integrações sem escrever código. Ferramentas como Make e n8n também conseguem consumir a API REST e receber webhooks.
Este artigo foi útil?
Ler as conversas (WhatsApp e E-mail) de um lead
Liste as conversas de um lead por canal e puxe as mensagens de cada thread para registrar o histórico de contato onde você quiser.
Limites de uso (rate limit)
Entenda quantas chamadas a API do GS Engage aceita por minuto e como tratar o erro 429 com backoff para não travar sua integração.