# Quickstart: sua primeira chamada em 5 minutos

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

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



<PageHero emoji="🚀" title="Quickstart: sua primeira chamada em 5 minutos" description="Pegue sua chave, confirme que ela funciona e crie seu primeiro lead — sem enrolação." gradient="brand" />

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.

<Callout type="tip" title="O que você precisa">
  Só uma conta no GS Engage com acesso a <TextHighlight>Configurações</TextHighlight> e um terminal (ou Node/Python instalado). Não precisa configurar servidor nem SDK.
</Callout>

🔑 Antes de começar: a apiKey é uma senha [#-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.

<Callout type="danger">
  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.
</Callout>

<Callout type="warning" title="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).
</Callout>

✅ Os 3 passos [#-os-3-passos]

<Steps>
  <Step num={1} title="Pegue sua apiKey na plataforma">
    Entre no GS Engage e vá em <TextHighlight>Configurações</TextHighlight> → <TextHighlight>Configurações de API</TextHighlight>. 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:

    ```bash
    export GS_API_KEY="sua_chave_de_40_caracteres_aqui"
    ```

    <Callout type="tip">
      Usar `$GS_API_KEY` no lugar da chave literal já resolve metade do risco de vazamento. Faça isso desde a primeira chamada.
    </Callout>
  </Step>

  <Step num={2} title="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:

    <Tabs items={['cURL', 'Node', 'Python']}>
      <Tab value="cURL">
        ```bash
        curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=$GS_API_KEY"
        ```
      </Tab>

      <Tab value="Node">
        ```js
        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());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        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())
        ```
      </Tab>
    </Tabs>

    <Callout type="tip" title="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=...`.
    </Callout>

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

  <Step num={3} title="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": "..." }`.

    <Tabs items={['cURL', 'Node', 'Python']}>
      <Tab value="cURL">
        ```bash
        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" }
            ]
          }'
        ```
      </Tab>

      <Tab value="Node">
        ```js
        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());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        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())
        ```
      </Tab>
    </Tabs>

    <Callout type="tip" title="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.
    </Callout>
  </Step>
</Steps>

🧯 Se algo deu errado [#-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). |

Próximos passos [#próximos-passos]

Deu certo? Escolha para onde ir agora:

<CardGrid cols={3}>
  <CardLink href="/docs/api/no-code/zapier" icon="🧩" title="Sem escrever código">
    Prefere não programar? Conecte via Zapier, Make ou n8n e use gatilhos prontos.
  </CardLink>

  <CardLink href="/docs/api/guias/adicionar-lead-cadencia" icon="📇" title="Adicionar o lead a uma cadência">
    Coloque o lead numa Cadência para iniciar a prospecção automática.
  </CardLink>

  <CardLink href="/docs/api/webhooks" icon="🔔" title="Criar e validar um webhook">
    Receba eventos em tempo real e confirme a autenticidade com HMAC SHA-256.
  </CardLink>
</CardGrid>

Artigos Relacionados [#artigos-relacionados]

<RelatedArticles>
  <RelatedArticle href="/docs/api/conceitos/autenticacao" title="Autenticação e segurança da apiKey" description="Como guardar a chave, rate limit e boas práticas." />

  <RelatedArticle href="/docs/api/referencia" title="Referência: Leads" description="Todos os campos e filtros da API de leads." />
</RelatedArticles>