Extrair prospecções e atividades para um dashboardCopiar

Você é o Rafael, cuida de BI, e o time de vendas quer enxergar o funil: quantas prospecções estão rodando, quantas foram ganhas, quantas foram perdidas — e qual a taxa de conversão. Esse número não mora num relatório pronto: você precisa extrair os dados brutos do GS Engage e montar o painel do seu jeito (Metabase, Power BI, Looker Studio, uma planilha, o que for).

Este guia mostra como puxar todas as suas prospecções e, quando precisar, o histórico de atividades de cada uma — de forma paginada e confiável — para alimentar um dashboard.

Um endpoint é só um endereço da API que devolve dados. Para montar o dashboard de funil, você usa dois:

Na prática: comece sempre pela lista de prospecções. Só desça para as atividades quando o painel precisar detalhar o que aconteceu dentro de cada prospecção específica.

A API devolve o status de cada prospecção como um código técnico em inglês. O time de vendas não fala essa língua — ele fala "Ganha", "Perdida". Antes de montar qualquer gráfico, faça essa tradução na sua camada de dados. É simples e direto:

Conversão é a pergunta central do funil: de tudo que foi decidido, quanto virou venda? A conta usa só dois status — WON e LOST — porque prospecções IN_PROGRESS e FROZEN ainda não têm desfecho e distorceriam o número se entrassem na base.

Taxa de conversão = Ganhas (WON) ÷ (Ganhas (WON) + Perdidas (LOST))

Exemplo concreto: em um período você tem 120 WON e 380 LOST. As IN_PROGRESS e FROZEN ficam de fora do cálculo.

120 ÷ (120 + 380) = 120 ÷ 500 = 0,24 → 24% de conversão

O GET /api/v1/prospections aceita filtros que você pode combinar com a paginação. Use-os para reduzir o volume e focar só no recorte que o dashboard precisa.

A lista de prospecções não vem toda de uma vez — ela vem paginada. A resposta tem sempre dois blocos: data (o pedaço de registros daquela página) e meta (as informações que dizem onde você está e quanto falta).

{
  "data": [
    { "id": "...", "status": "WON", "leadId": "...", "createdAt": "2026-07-10T14:03:00Z" }
  ],
  "meta": {
    "limit": 50,
    "count": 50,
    "total": 1240,
    "page": 1,
    "totalPages": 25
  }
}

O que cada campo de meta significa para você:

A regra de ouro da paginação: continue pedindo a próxima página enquanto page < totalPages. Você controla a página com o parâmetro page e o tamanho com limit.

Ao paginar uma extração, você precisa de uma ordem estável — senão registros novos entrando durante a leitura podem fazer você pular ou repetir linhas entre páginas. Ordene explicitamente por data de criação usando os parâmetros orderBy e orderDirection (asc ou desc):

GET /api/v1/prospections?apiKey=SUA_CHAVE&orderBy=createdAt&orderDirection=asc&limit=100&page=1

Este é o coração do guia: um loop que percorre todas as páginas de prospecções e junta tudo numa lista única, pronta para carregar no seu dashboard. Troque SUA_CHAVE pela sua chave (de preferência via variável de ambiente).

import os
import time
import requests

api_key = os.environ["GS_API_KEY"]  # guarde a chave em variável de ambiente
url = "https://api.gsengage.com/api/v1/prospections"

def fetch_all_prospections():
    todas = []
    page = 1
    while True:
        resp = requests.get(url, params={
            "apiKey": api_key,
            "limit": 100,
            "page": page,
            "orderBy": "createdAt",
            "orderDirection": "asc",
        })

        # Respeita o rate limit (200 leituras/min)
        if resp.status_code == 429:
            espera = int(resp.headers.get("Retry-After", "5"))
            time.sleep(espera)
            continue

        resp.raise_for_status()
        body = resp.json()
        todas.extend(body["data"])

        meta = body["meta"]
        if meta["page"] >= meta["totalPages"]:
            break
        page += 1

    return todas

prospeccoes = fetch_all_prospections()
print(f"Extraídas {len(prospeccoes)} prospecções")

# Traduz o status e calcula a conversão
rotulos = {
    "IN_PROGRESS": "Em andamento",
    "FROZEN": "Congelada",
    "WON": "Ganha",
    "LOST": "Perdida",
}
ganhas = sum(1 for p in prospeccoes if p["status"] == "WON")
perdidas = sum(1 for p in prospeccoes if p["status"] == "LOST")
decididas = ganhas + perdidas
conversao = (ganhas / decididas) if decididas else 0
print(f"Ganhas: {ganhas} | Perdidas: {perdidas} | Conversão: {conversao:.1%}")

const apiKey = process.env.GS_API_KEY; // guarde a chave em variável de ambiente
const baseUrl = "https://api.gsengage.com/api/v1/prospections";

async function fetchAllProspections() {
  const todas = [];
  let page = 1;

  while (true) {
    const params = new URLSearchParams({
      apiKey,
      limit: "100",
      page: String(page),
      orderBy: "createdAt",
      orderDirection: "asc",
    });

    const resp = await fetch(`${baseUrl}?${params}`);

    // Respeita o rate limit (200 leituras/min)
    if (resp.status === 429) {
      const espera = Number(resp.headers.get("Retry-After") ?? 5);
      await new Promise((r) => setTimeout(r, espera * 1000));
      continue;
    }

    if (!resp.ok) throw new Error(`Erro ${resp.status}`);

    const body = await resp.json();
    todas.push(...body.data);

    const { page: atual, totalPages } = body.meta;
    if (atual >= totalPages) break;
    page += 1;
  }

  return todas;
}

const prospeccoes = await fetchAllProspections();
const ganhas = prospeccoes.filter((p) => p.status === "WON").length;
const perdidas = prospeccoes.filter((p) => p.status === "LOST").length;
const decididas = ganhas + perdidas;
const conversao = decididas ? ganhas / decididas : 0;
console.log(`Ganhas: ${ganhas} | Perdidas: ${perdidas} | Conversão: ${(conversao * 100).toFixed(1)}%`);

# Página 1 — veja meta.totalPages na resposta
curl "https://api.gsengage.com/api/v1/prospections?apiKey=SUA_CHAVE&orderBy=createdAt&orderDirection=asc&limit=100&page=1"

# Página 2, 3, ... até page == totalPages
curl "https://api.gsengage.com/api/v1/prospections?apiKey=SUA_CHAVE&orderBy=createdAt&orderDirection=asc&limit=100&page=2"

O que a resposta significa para o negócio: com essa lista completa em mãos, você tem o funil inteiro — dá para contar quantas prospecções estão em cada estado, calcular a conversão do período e quebrar por cadência (routineIds) ou por vendedor, dependendo dos campos que o seu painel expõe.

Quando o painel precisar ir além do funil — por exemplo, medir quanto esforço cada prospecção exigiu (número de ligações, mensagens, e-mails) — você desce para as atividades de uma prospecção específica:

curl "https://api.gsengage.com/api/v1/prospections/ID_DA_PROSPECCAO/activities?apiKey=SUA_CHAVE&limit=100&page=1"

Essa resposta também é paginada no formato { data, meta } — use exatamente o mesmo loop do exemplo acima para percorrer todas as páginas. Como você faria uma chamada por prospecção, use isso com parcimônia: puxe as atividades só das prospecções que o dashboard realmente detalha, para não estourar o limite de requisições.

graph TD
A["Inicia extracao page=1"] --> B["GET /prospections?page=N"]
B --> C["Junta body.data na lista"]
C --> D{"meta.page < meta.totalPages?"}
D -->|Sim| E["page = page + 1"]
E --> B
D -->|Nao| F["Lista completa em maos"]
F --> G["Traduz status e calcula conversao"]
G --> H["Carrega no dashboard de funil"]

As mensagens de erro do GS Engage já vêm em português — leia sempre o campo message da resposta. Os tropeços mais frequentes nessa extração: