Início/Tutoriais/Usando o FirstSales com o Claude Code

Desenvolvedor e CLI

Usando o FirstSales com o Claude Code

Controle o FirstSales a partir do Claude Code via CLI — instale, autentique, inspecione antes de alterar dados e nunca exponha sua chave de API na saída do agente.

8 min de leitura·Avançado·7 etapas

1
Por que a CLI para o Claude Code
O Claude Code tem acesso a shell, então ele deve controlar o FirstSales pela CLI, não por HTTP puro. A CLI centraliza a autenticação, retorna JSON estável que o agente consegue parsear, cuida dos headers de idempotência e força confirmação em operações destrutivas — tudo que você, de outra forma, teria que instruir o agente a fazer corretamente toda vez.
Regra geral da documentação: agentes devem preferir a CLI quando há acesso a shell.
2
Instale e exponha a chave
Instale a CLI uma vez, e passe a chave ao Claude Code pelo ambiente para que ela nunca apareça em um prompt ou transcrição:
```
npm install -g @firstsales.io/cli
export FIRSTSALES_API_KEY="fs-key-..."   # definida no seu shell, não no chat
```
3
Dê ao agente suas regras de operação
Cole um contrato de operação curto no Claude Code (ou em um arquivo de regras do projeto) para que ele se comporte com segurança:
- Comece toda sessão com firstsales whoami --json; confirme org e workspace antes de agir.
- Inspecione primeiro, mute deliberadamente, verifique depois.
- Use --idempotency-key em qualquer criação que possa ser repetida.
- Use --confirm somente para uma exclusão intencional pedida pelo usuário.
- Nunca imprima chaves de API cruas.

Exploração somente leitura é sempre segura

Encoraje o agente a explorar livremente com comandos list/get — eles não conseguem danificar nada:

firstsales campaigns list --org ORG_ID --workspace WS_ID --json
firstsales contacts list --org ORG_ID --workspace WS_ID --json
firstsales billing overview --org ORG_ID --json

Mutações: pré-visualizar, agir, verificar

Para qualquer coisa que escreve, faça o Claude Code seguir o ciclo do início ao fim — --dry-run, depois a chamada real com uma chave de idempotência, depois uma releitura:

firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"lead@acme.com","first_name":"Sam"}' --dry-run

firstsales contacts create --org ORG_ID --workspace WS_ID \
  --data '{"email":"lead@acme.com","first_name":"Sam"}' \
  --idempotency-key sam-acme-2026-01

firstsales contacts list --org ORG_ID --workspace WS_ID --json

Aprove ou rejeite rascunhos de IA pelo terminal

Um ciclo útil no Claude Code: revisar respostas escritas por IA pendentes e agir sobre elas sem abrir o app. Liste as threads, leia uma, depois aprove ou rejeite o rascunho:

firstsales inbox threads --org ORG_ID --workspace WS_ID
firstsales inbox thread --org ORG_ID --workspace WS_ID --thread THREAD_ID
firstsales inbox approve-draft --org ORG_ID --workspace WS_ID \
  --email EMAIL_ID --idempotency-key approve-EMAIL_ID

7
Respeite a superfície pública
Instrua o agente a permanecer nos comandos públicos da CLI. Se um comando retornar unsupported_operation, ele deve parar e reportar — não tentar chamar rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de descadastro ou endpoints de cron internos para forçar o resultado.

Dicas de especialista

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

Coloque as regras de operação em um arquivo de regras do projeto

Em vez de colar o contrato de segurança de novo a cada sessão, coloque-o nas regras do projeto do Claude Code para que toda execução comece com whoami e o ciclo inspecionar-mutar-verificar.

Chave no ambiente, nunca no chat

Exporte FIRSTSALES_API_KEY no shell em que o Claude Code roda. Se a chave está em um prompt, ela está na transcrição — a CLI a mantém fora da saída, não a coloque de volta.

Deixe ele ler livremente, controle as escritas

Comandos list/get/analytics são seguros para rodar sem supervisão. Reserve sua revisão para qualquer coisa com create/update/delete ou --confirm.

unsupported_operation significa parar

Treine o agente para tratar unsupported_operation como um muro, não um quebra-cabeça. A CLI pública é toda a superfície permitida; não há gambiarra que valha o risco.

Perguntas frequentes

O Claude Code deve usar a CLI ou a API?

A CLI. Como o Claude Code tem acesso a shell, a CLI é preferida — ela centraliza a autenticação, emite JSON estável e reforça idempotência e confirmação de operações destrutivas, para que o agente não precise reimplementar isso.

Como mantenho minha chave de API fora da transcrição?

Exporte FIRSTSALES_API_KEY no shell antes de iniciar o Claude Code, e instrua-o a nunca imprimir chaves cruas. A CLI lê a variável de ambiente e nunca a ecoa na saída.

Qual é o fluxo seguro para mudanças?

Verifique a identidade com whoami, confirme org/workspace, inspecione o estado atual, faça a mudança mínima com --dry-run e depois --idempotency-key, use --confirm só para exclusões pretendidas, e releia para validar.

Ele consegue gerenciar a caixa de entrada?

Sim — inbox threads, inbox thread e inbox approve-draft / reject-draft permitem que o Claude Code triem e aja sobre respostas escritas por IA pelo terminal.

O que fazer se um comando não é suportado?

Se a CLI retornar unsupported_operation, o agente deve parar e reportar. Ele não deve recorrer a rotas privadas do app, callbacks, pixels ou endpoints de cron — esses são proibidos e vão quebrar.

Como evito exclusões acidentais?

Comandos destrutivos exigem --confirm. Enquanto o agente só adicionar --confirm para exclusões explicitamente pedidas pelo usuário, uma exclusão acidental não pode acontecer silenciosamente.

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