# Perguntas frequentes

> Respostas curtas para as dúvidas mais comuns de quem vai usar a API do GS Engage, da chave de acesso aos webhooks.

- URL canônica: https://docs.growthstation.app/docs/api/faq
- Idioma: pt-BR
- Última atualização: 2026-09-20T08:21:20.450Z
- Produto: GS Engage
- Mantido por: Produto GS Engage



<PageHero emoji="❓" title="Perguntas frequentes" description="As dúvidas que mais aparecem sobre a API do GS Engage, respondidas de forma curta e direta — com links para se aprofundar." gradient="brand" />

Reunimos aqui as perguntas que o time comercial e quem está começando na integração mais fazem. As respostas são curtas de propósito. Sempre que dá para se aprofundar, deixamos um link no fim.

🚀 Primeiros passos [#-primeiros-passos]

<FAQ>
  <FAQItem question="Preciso saber programar para usar a API?">
    Não. Dá para integrar sem escrever nenhuma linha de código usando <TextHighlight>Zapier</TextHighlight>, Make ou n8n — você monta a automação arrastando blocos. Comece pela trilha [Sem código](/docs/api/no-code/zapier). Se você (ou seu time de tecnologia) preferir programar, a API REST está toda na [Referência](/docs/api/referencia).
  </FAQItem>

  <FAQItem question="Onde eu pego minha chave de acesso (apiKey)?">
    Dentro da plataforma, em <TextHighlight>Configurações</TextHighlight> > <TextHighlight>Configurações de API</TextHighlight>. A chave tem cerca de 40 caracteres. Se estiver em dúvida sobre qual trilha seguir, veja [Escolha seu caminho](/docs/api/comece-aqui/escolha-seu-caminho).
  </FAQItem>

  <FAQItem question="Como sei se minha chave está funcionando?">
    Faça uma leitura leve e segura: liste os campos personalizados. Um `200` com uma lista (mesmo vazia, `[]`) confirma que a chave funciona.

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

    Não existe `GET /info` nem `GET /health` — este é o teste de saúde recomendado.
  </FAQItem>
</FAQ>

🔑 Segurança da chave [#-segurança-da-chave]

<FAQ>
  <FAQItem question="A minha apiKey expira?">
    Não. A chave continua válida enquanto existir na plataforma. Se precisar revogá-la, remova ou substitua em <TextHighlight>Configurações</TextHighlight> > <TextHighlight>Configurações de API</TextHighlight>.
  </FAQItem>

  <FAQItem question="É seguro colocar a chave na URL?">
    A `apiKey` viaja na própria URL, no formato `?apiKey=SUA_CHAVE`. Isso significa que ela pode aparecer em logs de servidor, no histórico do navegador e em links compartilhados. Por isso, trate-a como uma senha.

    <Callout type="danger" title="Trate a apiKey como senha">
      Guarde a chave em uma variável de ambiente e nunca cole em canais públicos (chat, e-mail, tickets, prints). Se ela vazar, gere uma nova na plataforma.
    </Callout>
  </FAQItem>

  <FAQItem question="Existe um ambiente de teste (sandbox)?">
    Não. Toda chamada é **real** e afeta os dados de produção — os mesmos que o time comercial usa. Ao experimentar, prefira operações de leitura (consultar dados) e avise sua equipe antes de qualquer escrita (criar, editar ou remover).
  </FAQItem>
</FAQ>

📇 Leads e prospecções [#-leads-e-prospecções]

<FAQ>
  <FAQItem question="Qual a diferença entre adicionar um lead a uma cadência e criar uma prospecção?">
    As duas coisas iniciam a prospecção, mas por caminhos diferentes:

    * **Adicionar lead à cadência** coloca um lead já existente em uma [cadência](/docs/api/conceitos/glossario). Se a distribuição automática estiver ativa (ou você informar um responsável), a prospecção começa sozinha.
    * **Criar prospecção** monta a prospecção diretamente, indicando o lead, a cadência e, opcionalmente, o responsável.

    Na prática: use "adicionar à cadência" quando o gatilho é o lead entrar no fluxo; use "criar prospecção" quando você já sabe exatamente lead, cadência e vendedor. Veja o passo a passo em [Adicionar um lead a uma cadência](/docs/api/guias/adicionar-lead-cadencia).
  </FAQItem>

  <FAQItem question="Onde o lead criado pela API aparece para o vendedor?">
    Um lead criado via API entra marcado como <TextHighlight>Levantada de Mão</TextHighlight> e aparece no topo da fila de atividades do vendedor. Lembrando que criar um lead exige pelo menos um contato (e-mail, telefone ou celular).
  </FAQItem>

  <FAQItem question="O que significam os status IN_PROGRESS, WON e LOST?">
    São os estados de uma prospecção. Sempre que for mostrar para alguém, use o rótulo em português que aparece no app:

    | Status técnico | Rótulo no app |
    | -------------- | ------------- |
    | `IN_PROGRESS`  | Em andamento  |
    | `FROZEN`       | Congelada     |
    | `WON`          | Ganha         |
    | `LOST`         | Perdida       |

    Ao encerrar uma prospecção como `LOST`, o motivo da perda (`lostReason`) é obrigatório.
  </FAQItem>
</FAQ>

🚦 Erros e limites [#-erros-e-limites]

<FAQ>
  <FAQItem question="Por que recebi o erro 401?">
    O `401` (não autorizado) quer dizer que a `apiKey` está ausente ou inválida. **Por quê:** a chave não foi enviada na URL, foi digitada errada ou foi revogada. **Como corrigir:** confira se você incluiu `?apiKey=SUA_CHAVE` no fim da URL e se a chave está correta, copiando-a de novo em <TextHighlight>Configurações</TextHighlight> > <TextHighlight>Configurações de API</TextHighlight>.
  </FAQItem>

  <FAQItem question="Por que recebi o erro 429?">
    O `429` significa que você passou do limite de requisições. **Por quê:** numa janela de 60 segundos, a API permite 200 leituras/min (GET/HEAD) e 100 escritas/min (POST, PUT, PATCH, DELETE). **Como corrigir:** espere e tente de novo respeitando o header `Retry-After` (em segundos), que vem na resposta. A boa prática é usar *backoff* exponencial — aumentar o intervalo entre tentativas. Os headers `X-RateLimit-Remaining` e `X-RateLimit-Reset` ajudam a saber quanto ainda resta e quando o contador zera.
  </FAQItem>
</FAQ>

🔔 Webhooks e vendas ganhas [#-webhooks-e-vendas-ganhas]

<FAQ>
  <FAQItem question="Como recebo um aviso quando uma venda é ganha?">
    Você cria um webhook — um aviso automático que o GS Engage envia para uma URL sua sempre que algo acontece. Para vendas ganhas, cadastre um webhook ouvindo o evento `prospection.won` (existem também `prospection.lost`, `prospection.started`, entre outros).

    <Callout type="warning" title="Guarde o secret na hora">
      Ao criar um webhook, o campo `secret` é retornado **uma única vez**, só na resposta de criação. Copie e guarde na hora — depois não dá para vê-lo de novo.
    </Callout>

    O passo a passo está em [Avisos de venda por webhook](/docs/api/guias/avisos-de-venda-webhook).
  </FAQItem>

  <FAQItem question="Como sei que o aviso veio mesmo do GS Engage?">
    Cada entrega é assinada com HMAC SHA-256 — uma assinatura calculada a partir do corpo da mensagem e do seu `secret`, que vem em um header. Do seu lado, você recalcula a assinatura com o mesmo `secret` e compara: se baterem, o aviso é autêntico. (A assinatura foi atualizada de SHA-1 para SHA-256.) Veja como validar em [Validar a assinatura do webhook](/docs/api/guias/validar-assinatura-webhook).
  </FAQItem>

  <FAQItem question="Posso reprocessar (reenviar) um webhook?">
    Sim. O envelope de cada entrega traz os campos `retries` e `manualRetries`, que indicam as tentativas automáticas e as manuais. Ou seja, uma mesma entrega pode ser reenviada — e o seu código deve estar preparado para receber o mesmo evento mais de uma vez sem duplicar o efeito.
  </FAQItem>
</FAQ>

❓ Ainda com dúvida? [#-ainda-com-dúvida]

Se a sua pergunta não estava aqui, estes atalhos costumam resolver:

<CardGrid cols={2}>
  <CardLink href="/docs/api/comece-aqui/escolha-seu-caminho" icon="🧭" title="Escolha seu caminho">
    Descubra a trilha certa para o seu objetivo: sem código, com código ou análise de dados.
  </CardLink>

  <CardLink href="/docs/api/conceitos/glossario" icon="📖" title="Glossário">
    O significado de cada termo técnico, em português claro.
  </CardLink>

  <CardLink href="/docs/api/referencia" icon="📚" title="Referência" span>
    A lista completa de operações, campos e respostas da API.
  </CardLink>
</CardGrid>

Artigos Relacionados [#artigos-relacionados]

<RelatedArticles>
  <RelatedArticle href="/docs/api/comece-aqui/escolha-seu-caminho" title="Escolha seu caminho" description="A trilha certa para integrar, com ou sem código." />

  <RelatedArticle href="/docs/api/no-code/zapier" title="Integrar sem código" description="Automatize com Zapier, Make ou n8n, sem programar." />

  <RelatedArticle href="/docs/api/guias/adicionar-lead-cadencia" title="Adicionar um lead a uma cadência" description="Comece a prospecção automaticamente." />

  <RelatedArticle href="/docs/api/conceitos/glossario" title="Glossário" description="Traduz o jargão: endpoint, rate limit, webhook e mais." />
</RelatedArticles>