Usando o FirstSales com o Codex

Conecte o Codex ao FirstSales via API REST (ou CLI em um shell) — primeira chamada whoami, chaves com escopo restrito, escritas idempotentes e interrupção em operações não suportadas.

8 min de leitura·Avançado·6 etapas

1
Escolha o caminho certo para sua configuração do Codex
O FirstSales oferece dois caminhos de integração. Se o seu ambiente Codex tem shell com npm, instale o @firstsales.io/cli e controle-o como qualquer agente com shell — ele cuida de autenticação, JSON e idempotência para você. Se o Codex roda sem acesso a shell (navegador ou sandbox), chame a Developer API diretamente via HTTPS. A documentação agrupa o Codex com agentes API-first exatamente por esse motivo.
2
Guarde a chave como um secret de ambiente
Crie uma chave de API de desenvolvedor em Settings → API e coloque-a no cofre de secrets do seu ambiente Codex como FIRSTSALES_API_KEY. Nunca cole a chave crua em um prompt nem a commite — referencie a variável de ambiente no código.
```
# no ambiente da sua tarefa do Codex
FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
```
3
Verifique a identidade primeiro
Qualquer que seja o caminho, a primeira chamada confirma que a chave resolve para a org e o workspace esperados:
```
curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
```

Leia o estado antes de escrever

Faça o Codex inspecionar antes de mutar. Os recursos são vinculados a org e workspace:

curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/contacts \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

Escreva de forma idempotente

Em criações, envie um header Idempotency-Key para que uma requisição repetida nunca duplique dados — importante para um agente autônomo que pode repetir a chamada em caso de timeout:

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: codex-lead-2026-01" \
  -d '{"email":"lead@acme.com","first_name":"Sam"}'

6
Mantenha o Codex na superfície pública
Instrua o Codex a usar apenas os endpoints públicos /api/v1. Em uma resposta unsupported_operation, ele deve parar e reportar — nunca raspar o app ou chamar rotas privadas, callbacks de provedores, pixels de rastreamento, handlers de descadastro ou endpoints de cron para forçar um resultado. Trate 401 (chave errada), 422 (validação — o corpo nomeia o campo) e 429 (recue) explicitamente.

Dicas de especialista

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

Tem shell? Prefira a CLI

Se o seu sandbox do Codex consegue rodar npm, a CLI elimina bastante boilerplate — autenticação, JSON, idempotência e confirmação de exclusão já vêm resolvidas. Recorra a HTTP puro só quando não há shell.

A chave vive no ambiente, não no prompt

Coloque FIRSTSALES_API_KEY no cofre de secrets do Codex e referencie-a. Uma chave no prompt acaba nos logs e no histórico.

whoami é a verificação de segurança mais barata

Uma chamada confirma que o Codex está apontando para a org e o workspace certos antes de escrever qualquer coisa. Pulá-la é como dados acabam no workspace errado.

Idempotency-Key em toda criação

Agentes autônomos repetem chamadas. Uma chave de idempotência estável transforma um POST repetido em um no-op em vez de um contato duplicado ou uma cobrança dobrada.

Perguntas frequentes

O Codex deve usar a CLI ou a API?

Se o Codex tem acesso a shell com npm, use a CLI. Se ele roda em um navegador ou em um sandbox sem shell, chame a Developer API via HTTPS. O caminho da API é o padrão para agentes baseados em navegador.

Como dou a chave ao Codex com segurança?

Guarde-a como FIRSTSALES_API_KEY no ambiente/cofre de secrets do Codex e referencie a variável no código. Não cole a chave crua em prompts nem a commite.

Qual é a URL base e a primeira chamada?

Base https://api.app.firstsales.io, autenticação Bearer. Primeira chamada GET /api/v1/whoami para confirmar o contexto de org e workspace antes de qualquer escrita.

Como evito escritas duplicadas em retentativas?

Envie um header Idempotency-Key nas requisições de criação. Uma repetição com a mesma chave retorna o resultado original em vez de criar um segundo registro.

O que o Codex nunca deve fazer?

Nunca chamar rotas privadas do app, callbacks de provedores, pixels de rastreamento, handlers de descadastro ou endpoints internos de cron, e nunca raspar a interface do app. Fique na /api/v1 pública; pare e reporte 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