# Glossário do GS Engage
> Dicionário simples de todos os termos técnicos da API do GS Engage, do jargão de rede (endpoint, webhook) aos rótulos que você vê no app (Cadência, Levantada de Mão).
- URL canônica: https://docs.growthstation.app/docs/api/conceitos/glossario
- Idioma: pt-BR
- Última atualização: 2026-09-20T08:21:20.450Z
- Produto: GS Engage
- Mantido por: Produto GS Engage
Esta página é o dicionário oficial do GS Engage. Sempre que aparecer uma palavra estranha em outra doc, volte aqui. Organizamos por assunto para você achar rápido, mas se preferir, use o índice do navegador (Ctrl+F / Cmd+F) e busque pelo termo.
Guarde o link desta página. Ela é a mesma fonte que alimenta as dicas (tooltips) espalhadas pela documentação.
🌐 Termos de tecnologia e integração [#-termos-de-tecnologia-e-integração]
Estes são os termos que aparecem quando falamos em conectar dois sistemas. Não se assuste: cada um tem uma tradução simples.
| Termo | O que significa, em português claro |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API** | É a "porta de entrada" do GS Engage para outros programas. Em vez de uma pessoa clicar na tela, um sistema conversa com o GS Engage por essa porta — criando leads, listando cadências e por aí vai. A sigla vem de *Application Programming Interface* (interface de programação). |
| **Endpoint** | É um endereço específico dentro da API, cada um com uma função. Pense em portas numeradas dentro do prédio: uma porta cria leads, outra lista cadências. Por exemplo, `GET /api/v1/leads` é o endpoint que devolve a lista de leads. |
| **OpenAPI** | É o "mapa oficial" da API, escrito num formato que máquinas e ferramentas entendem. Com ele, programas como Postman ou geradores de código montam sozinhos a integração, sem você digitar cada detalhe. |
| **ID do recurso (ObjectId)** | É o número de identidade único de cada item no GS Engage (um lead, uma cadência, uma prospecção). Tem 24 caracteres, algo como `65a1f2c3d4e5f6a7b8c9d0e1`. Sempre que uma doc pedir um `leadId` ou `routineId`, é esse código que ela quer. |
| **No-code** | Jeito de integrar sem escrever nenhuma linha de código. O GS Engage tem gatilhos nativos no **Zapier**, e ferramentas como **Make** e **n8n** também conseguem chamar a API e receber webhooks. |
A base de tudo é `https://api.gsengage.com`, e todos os caminhos ficam sob `/api/v1`. Então o endpoint de leads, por extenso, é `https://api.gsengage.com/api/v1/leads`.
🔑 Segurança e acesso [#-segurança-e-acesso]
Aqui moram os termos ligados a "provar quem é você" e proteger seus dados. Vale a leitura com calma.
| Termo | O que significa, em português claro |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **apiKey (chave de API)** | É a sua senha de acesso à API. Um texto de cerca de 40 caracteres que você gera na plataforma em Configurações > Configurações de API. Ela vai na URL, no formato `?apiKey=SUA_CHAVE` — não é um cabeçalho. |
| **Secret (segredo do webhook)** | É uma senha extra, gerada quando você cria um webhook. Serve para o GS Engage "carimbar" cada aviso e você confirmar que veio mesmo de nós. Atenção: ele aparece **uma única vez**, na resposta de criação. Copie na hora. |
| **Assinatura HMAC SHA-256** | É o "carimbo de autenticidade" de cada webhook. O GS Engage mistura o conteúdo da mensagem com o seu *secret* usando uma fórmula matemática (HMAC SHA-256) e coloca o resultado num cabeçalho. Você refaz a mesma conta do seu lado e compara: se bater, o aviso é legítimo; se não bater, ignore. (Antes usávamos SHA-1; hoje é SHA-256.) |
Como a chave viaja na URL, ela acaba registrada em logs de servidor, no histórico do navegador e em qualquer link que você compartilhe. Nunca cole a chave em chat público, e-mail solto ou print. Guarde-a numa variável de ambiente. Se desconfiar de vazamento, gere uma nova nas Configurações de API.
Toda chamada à API do GS Engage é real e mexe em dados de produção. Não há sandbox nem chave de teste. Ao experimentar, prefira operações de leitura (as que começam com `GET`) e avise a equipe antes de qualquer ação que grave ou apague dados.
🛡️ Limites e formato das respostas [#️-limites-e-formato-das-respostas]
Termos que explicam "quantas chamadas posso fazer" e "como a resposta vem organizada".
| Termo | O que significa, em português claro |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rate limit (limite de requisições)** | É o teto de chamadas num intervalo de tempo, para o sistema não sobrecarregar. Aqui a janela é de 60 segundos: **200 leituras** (`GET`/`HEAD`) e **100 escritas** (`POST`/`PUT`/`PATCH`/`DELETE`) por minuto. |
| **Retry-After** | Cabeçalho que vem junto do erro de limite (429). Ele diz, em segundos, quanto tempo esperar antes de tentar de novo. |
| **Backoff exponencial** | Boa prática ao levar um 429: em vez de insistir na hora, espere o tempo do `Retry-After` e vá dobrando a pausa a cada nova tentativa. Assim o sistema respira e sua integração não trava. |
| **Paginação** | Quando há muitos resultados, a API entrega em "páginas" para não mandar tudo de uma vez. Você controla com os parâmetros `limit` (quantos por página) e `page` (qual página). |
| **Ordenação** | Você escolhe a ordem dos resultados com `orderBy` (por qual campo) e `orderDirection` (`asc` para crescente, `desc` para decrescente). |
Quando exceder o limite, a resposta é um **HTTP 429** e traz estes cabeçalhos para você se organizar:
```json
{
"X-RateLimit-Limit": "200",
"X-RateLimit-Remaining": "0",
"X-RateLimit-Reset": "1721232000",
"Retry-After": "37"
}
```
Uma resposta paginada tem sempre este formato — a lista fica em `data` e o resumo em `meta`:
```json
{
"data": [ /* ... seus itens ... */ ],
"meta": {
"limit": 20,
"count": 20,
"total": 137,
"page": 1,
"totalPages": 7
}
}
```
`GET /api/v1/webhooks` devolve os itens em `data`, mas **sem** o bloco `meta` (lista completa, sem paginação). `GET /api/v1/custom-fields`, por sua vez, é paginado normal (`{ data, meta }`). Em ambos, os itens ficam em `data`.
📣 Webhooks e eventos [#-webhooks-e-eventos]
Webhook é como pedir para o GS Engage te avisar sozinho quando algo acontece — sem você ficar perguntando o tempo todo.
| Termo | O que significa, em português claro |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook** | É um aviso automático. Você cadastra uma URL sua, e sempre que algo relevante acontece (uma prospecção é ganha, por exemplo), o GS Engage envia um `POST` para essa URL na hora. É o oposto de ficar consultando a API de minuto em minuto. |
| **Evento** | É o "tipo de acontecimento" que dispara o webhook. Você escolhe quais quer receber. |
| **Handover** | É a troca de responsável por uma prospecção — quando ela passa de um vendedor para outro. Gera o evento `prospection.handover`. |
Estes são os eventos que você pode assinar:
| Evento | Quando dispara |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `prospection.started` | Uma prospecção começou. |
| `prospection.won` | Uma prospecção foi ganha (Ganha). |
| `prospection.lost` | Uma prospecção foi perdida (Perdida). |
| `activity.finished` | Uma atividade foi concluída. |
| `call.started` | Uma ligação começou. |
| `call.finished` | Uma ligação terminou. |
| `call.transcribed` | A transcrição da ligação ficou pronta. |
| `prospection.handover` | Troca de responsável. Emitido pelo sistema; ainda não assinável via API de criar webhook. |
Cada aviso que chega na sua URL vem embrulhado neste "envelope":
```json
{
"id": "65a1f2c3d4e5f6a7b8c9d0e1",
"test": false,
"event": "prospection.won",
"data": { /* ... detalhes do que aconteceu ... */ },
"retries": 0,
"manualRetries": 0,
"createdAt": "2026-07-17T12:00:00.000Z"
}
```
Ao ler esse envelope, confira a **assinatura HMAC SHA-256** antes de confiar no conteúdo — é ela que garante que o aviso veio mesmo do GS Engage.
📇 Conceitos do dia a dia de vendas [#-conceitos-do-dia-a-dia-de-vendas]
Agora os termos que você já conhece do app, com o nome que a API usa por trás. Sempre que houver diferença entre o rótulo técnico e o rótulo que aparece na tela, mostramos os dois.
| Termo | O que significa, em português claro |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Lead** | É um contato ou empresa em potencial. Na API, os dados de contato ficam em três listas — `emails`, `phones` (telefones fixos) e `mobiles` (celulares) — e cada item tem `value` (o dado) e `label` (um rótulo, como "comercial"). É obrigatório informar pelo menos um contato ao criar um lead. |
| **Prospecção** | É o trabalho de abordar e conduzir um lead ao longo de uma cadência, do primeiro contato até o desfecho. Um lead vira uma prospecção quando entra numa cadência com um responsável. |
| **Atividade** | É cada tarefa dentro de uma prospecção: ligar, enviar mensagem, mandar e-mail. As atividades ficam na fila do vendedor, na ordem certa. |
| **Cadência (routine)** | É a sequência planejada de atividades que o vendedor segue para abordar um lead — o famoso "fluxo de contatos". No app chamamos de **Cadência**; na API o termo técnico é `routine`. |
| **Distribuição automática** | Regra da cadência que reparte os leads novos entre os vendedores sozinha. Se estiver ligada (ou se você informar um `responsibleId`), o lead já entra em prospecção ao ser adicionado à cadência. |
| **Campo Personalizado** | É um campo extra que sua empresa cria para guardar informações próprias no lead (ex.: "segmento", "número do contrato"). Você lista os campos existentes em `GET /api/v1/custom-fields`. |
| **Conversa / Thread** | É o histórico de mensagens trocadas com um lead num canal. Cada *thread* é uma conversa; hoje os canais são **WhatsApp** e **E-mail**. |
Todo lead que entra pela API é marcado como Levantada de Mão e aparece no topo da fila de atividades do vendedor. É a forma de sinalizar que aquele contato demonstrou interesse e merece prioridade.
🏷️ Rótulos e status (enums) [#️-rótulos-e-status-enums]
"Enum" é só uma lista fechada de opções possíveis. A API guarda um valor técnico (em inglês, maiúsculas), mas no app você vê o rótulo em português. Aqui estão os dois lado a lado.
Situação da prospecção [#situação-da-prospecção]
| Valor técnico | Rótulo no app | O que significa |
| ------------- | ---------------- | ----------------------------------------------------------------- |
| `IN_PROGRESS` | **Em andamento** | A prospecção está ativa, com atividades acontecendo. |
| `FROZEN` | **Congelada** | Foi pausada temporariamente; nada avança até descongelar. |
| `WON` | **Ganha** | Deu certo — o negócio foi fechado. |
| `LOST` | **Perdida** | Não avançou. Aqui é obrigatório informar o motivo (`lostReason`). |
Origem do lead (sourceType) [#origem-do-lead-sourcetype]
| Valor técnico | Rótulo no app | O que significa |
| -------------- | ------------------- | ---------------------------------------------------- |
| `FILE` | **Lista importada** | Veio de uma planilha ou arquivo enviado. |
| `RD_MARKETING` | **RD Station** | Veio da integração com o RD Station. |
| `API` | **Via API** | Foi criado pela API (como esta que você está lendo). |
Modo de execução da cadência (executionMode) [#modo-de-execução-da-cadência-executionmode]
| Valor técnico | Rótulo no app | O que significa |
| ------------- | ----------------- | -------------------------------------------------------------- |
| `MANUAL` | **Manual** | O vendedor conduz as atividades no próprio ritmo. |
| `AI_DRIVEN` | **Guiada por IA** | A inteligência artificial ajuda a orientar os próximos passos. |
Tipo de aquisição (acquisitionType) [#tipo-de-aquisição-acquisitiontype]
De onde o lead surgiu, do ponto de vista comercial. É um dos filtros de cadências e leads.
| Valor técnico | Rótulo no app | O que significa |
| ------------------ | -------------------- | -------------------------------------------------------------------- |
| `OUTBOUND` | **Outbound** | Prospecção ativa: você foi atrás do lead. |
| `PASSIVE_INBOUND` | **Fishing** | Lead que "mordeu a isca" de forma passiva, sem pedir contato direto. |
| `ACTIVE_INBOUND` | **Levantada de Mão** | O lead pediu contato ativamente — demonstrou interesse claro. |
| `REFERRAL` | **Indicação** | Chegou por indicação de alguém. |
| `REACTIVATION` | **Resgate** | Lead antigo sendo reativado. |
| `EVENT_NETWORKING` | **Networking** | Veio de evento ou relacionamento presencial. |
| `OTHER` | **Outro** | Qualquer origem que não se encaixa nas anteriores. |
Na dúvida entre Fishing e Levantada de Mão: no Fishing o lead entra de forma passiva; na Levantada de Mão ele pede contato ativamente. Lembre que todo lead criado pela API já entra como Levantada de Mão.
✅ Como validar sua chave (exemplo prático) [#-como-validar-sua-chave-exemplo-prático]
Antes de sair integrando, vale confirmar que sua **apiKey** funciona. O jeito mais leve é pedir a lista de campos personalizados — é uma leitura, não muda nada.
```bash
curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=SUA_CHAVE"
```
Se voltar um **200** com uma lista (mesmo que seja `[]`, caso o projeto ainda não tenha campos), sua chave está valendo. Se voltar **401**, a chave está ausente ou errada — confira em Configurações de API.
Não existe `GET /info` nem `GET /health`. O endpoint de campos personalizados é o teste de vida recomendado justamente por ser leve e só de leitura.
❓ Perguntas frequentes [#-perguntas-frequentes]
Sim. No GS Engage a autenticação é por query param: `?apiKey=SUA_CHAVE`. Por isso a recomendação de tratá-la como senha e nunca compartilhá-la em links ou canais públicos.
Não existe ambiente de teste separado. Toda chamada é real e afeta produção. Prefira operações de leitura (`GET`) ao explorar e avise antes de qualquer escrita.
O `secret` só aparece uma vez, na resposta de criação do webhook. Se você não guardou, apague o webhook e crie de novo para receber um secret novo.
Um endpoint (`GET /api/v1/webhooks`) devolve `data` sem `meta` (lista completa, sem paginação). Nos demais — inclusive `custom-fields` — você recebe `data` + `meta` com a paginação.
Não necessariamente. O GS Engage tem gatilhos nativos no Zapier, e ferramentas como Make e n8n também consomem a API e recebem webhooks — tudo sem escrever código.
Artigos Relacionados [#artigos-relacionados]