NovoVeja como
FirstSales
Início/Tutoriais/Usando o FirstSales com o Gemini
Desenvolvedor e CLI

Usando o FirstSales com o Gemini

Conecte o Gemini ao FirstSales via API REST com ferramentas de função restritas — leia antes de escrever, escopos por ferramenta e mutações seguras e verificáveis.

8 min de leitura·Avançado·6 etapas
  1. 1

    Duas formas de conectar o Gemini

    Se o seu ambiente Gemini (por exemplo, o Gemini CLI com acesso a shell) puder rodar npm, instale o @firstsales.io/cli e exponha-o como uma ferramenta — ele cuida da autenticação, do JSON e da idempotência. Se o Gemini funcionar apenas via API, chame a Developer API da FirstSales por HTTPS a partir das implementações da sua função/ferramenta. A documentação classifica o Gemini junto com os agentes que priorizam a API por padrão.

  2. 2

    Guarde a chave fora do modelo

    Crie uma chave da Developer API em Settings → API e mantenha-a na configuração server-side do seu app como FIRSTSALES_API_KEY. O Gemini deve chamar uma tool/function que lê a chave no lado do servidor — o próprio modelo nunca deve ver ou emitir a chave bruta.

    FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
  3. 3

    Defina ferramentas restritas, não uma porta de escape HTTP genérica

    Dê ao Gemini um pequeno conjunto de funções feitas sob medida — whoami, list_contacts, create_contact, campaign_analytics — cada uma mapeada para um endpoint público. Isso mantém o modelo na superfície suportada, em vez de deixá-lo construir URLs arbitrárias.

    # o que cada tool chama por baixo dos panos
GET  /api/v1/whoami
GET  /api/v1/organizations/{org}/workspaces/{ws}/contacts
POST /api/v1/organizations/{org}/workspaces/{ws}/contacts     # Idempotency-Key
GET  /api/v1/organizations/{org}/workspaces/{ws}/campaigns/{id}/analytics
  4. 4

    Verifique a identidade na primeira chamada de ferramenta

    Faça o agente chamar whoami antes de qualquer escrita, para confirmar o contexto de org e workspace:

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  5. 5

    Escreva de forma idempotente a partir da sua tool de criação

    Sua tool create_contact deve sempre anexar um Idempotency-Key, para que uma chamada de função repetida não gere uma escrita duplicada:

    curl -X POST \
  https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gemini-lead-2026-01" \
  -d '{"email":"lead@acme.com","first_name":"Sam"}'
  6. 6

    Trate erros e permaneça na superfície pública

    Em cada tool, trate 401 (chave inválida/revogada), 422 (validação — exiba o campo) e 429 (recue e tente novamente). Em unsupported_operation, retorne a limitação ao modelo e pare — nunca deixe o Gemini raspar o app ou acessar rotas privadas, callbacks, pixels ou endpoints de cron.

Dicas de especialista

Atalhos conquistados na prática que mantêm o aquecimento nos trilhos.

1

Empacote endpoints como ferramentas restritas

Não entregue ao Gemini uma função genérica de 'chamar qualquer URL'. Ferramentas feitas sob medida (create_contact, campaign_analytics) mantêm o modelo na superfície pública e tornam suas ações auditáveis.

2

O modelo nunca toca na chave

Leia FIRSTSALES_API_KEY no lado do servidor, dentro da ferramenta. Se a chave puder aparecer no contexto ou na saída do modelo, ela pode vazar para os logs.

3

whoami como primeira chamada de função

Torne a verificação de identidade o primeiro passo, para que o Gemini sempre confirme org/workspace antes de escrever.

4

Tem shell disponível? O CLI é menos código

Se o Gemini CLI tiver shell + npm, chamar o firstsales via shell é melhor do que criar ferramentas HTTP na mão — autenticação, JSON, idempotência e confirmação de exclusão vêm de graça.

Perguntas frequentes

O Gemini usa o CLI ou a API?

Por padrão, a Developer API, empacotada como functions/tools. Se o seu ambiente Gemini tiver acesso a shell com npm, o CLI é uma alternativa de menor esforço que cuida da autenticação e da idempotência para você.

Como mantenho a chave longe do modelo?

Guarde FIRSTSALES_API_KEY na configuração server-side e leia-a dentro da implementação da ferramenta. O modelo chama a ferramenta; ele nunca vê ou emite a chave bruta.

Como devo estruturar as ferramentas?

Como funções restritas e de propósito único — uma por endpoint público (whoami, listar/criar contato, campaign analytics). Evite uma tool genérica de 'buscar qualquer URL' que permita ao modelo sair da superfície suportada.

Como evito escritas duplicadas?

Anexe um cabeçalho Idempotency-Key dentro da sua tool de criação. Uma chamada de função repetida com a mesma chave retorna o resultado original em vez de criar um duplicado.

O que está fora dos limites?

Rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de descadastro, endpoints internos de cron e raspagem da UI. Fique na /api/v1 pública; pare em unsupported_operation.

Pronto para colocar isso em prática?

Comece seu teste do FirstSales e lance uma caixa de e-mail aquecida e autenticada em minutos.

Comece por $1
Todos os tutoriais