Início/Tutoriais/Playbook de RevOps: automatize o outbound com chaves de API, a CLI e CSV

Primeiros Passos

Playbook de RevOps: automatize o outbound com chaves de API, a CLI e CSV

Gere chaves de API com escopo, importe e sincronize contatos programaticamente, conduza campanhas pela CLI, integre ao CI/CD e monitore o uso de chaves e o runway de créditos — usando a API REST e CSV, a superfície disponível hoje.

14 min de leitura·Avançado·8 etapas

1
Enquadre a superfície automatizável (e o que ainda não é)
O que já está disponível hoje: a REST API, a CLI e a importação/exportação de contatos em CSV/JSON. O que não está: webhooks, conectores de CRM (Salesforce, HubSpot, Zoho, Pipedrive) e conectores Slack/Teams/Sheets/Airtable/Notion — todos em breve e retornam unsupported_operation se você tentar chamá-los. Construa a automação sobre a superfície ativa — faça polling e exporte via REST/CSV em vez de esperar por um conector.
2
Crie uma API key de privilégio mínimo
Vá em Settings → API e crie uma chave nomeada por consumidor — por exemplo, ci-contact-sync — apenas com os escopos necessários (contacts:read/write, campaigns:read, etc.). A chave é exibida uma única vez; copie-a direto para um gerenciador de segredos. Revogue imediatamente se ela vazar — a revogação é instantânea. Veja Create & Manage Developer API Keys.

Instale e verifique a CLI

Instale a CLI e confirme que a chave é resolvida antes de fazer qualquer outra coisa:

npm install -g @firstsales.io/cli
export FIRSTSALES_API_KEY="fs_live_..."   # from your secret manager
firstsales whoami --json
firstsales doctor

4
Importe contatos programaticamente de um CSV
Envie um lote por meio de um job de importação com uma chave de idempotência — a plataforma deduplica por e-mail no lado do servidor, então reexecutar o mesmo arquivo não duplica ninguém:
```
firstsales contact-imports create --org "$ORG_ID" --workspace "$WS_ID" \
  --data-file ./leads.csv \
  --idempotency-key "leads-import-2026-07"
```

Mantenha os contatos sincronizados — o ciclo de ouro

A automação segue o mesmo ciclo de um operador humano: inspecionar, depois alterar deliberadamente, depois verificar. Faça uma prévia com --dry-run antes de qualquer escrita, altere com uma chave de idempotência e depois releia para confirmar:

firstsales contacts list --org "$ORG_ID" --workspace "$WS_ID" --json
firstsales contacts update --org "$ORG_ID" --workspace "$WS_ID" \
  --contact "$CONTACT_ID" --data '{"job_title":"VP Sales"}' --dry-run
firstsales contacts update --org "$ORG_ID" --workspace "$WS_ID" \
  --contact "$CONTACT_ID" --data '{"job_title":"VP Sales"}'
firstsales contacts get --org "$ORG_ID" --workspace "$WS_ID" --contact "$CONTACT_ID"

Conduza campanhas pela CLI ou pela API

Liste e leia campanhas pela CLI, ou acesse /api/v1 diretamente com um token Bearer quando preferir não usar a CLI:

firstsales campaigns list --org "$ORG_ID" --workspace "$WS_ID" --json

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

7
Integre ao CI/CD
Injete a chave a partir do armazenamento de segredos do seu provedor de CI, nunca a fixe no código. Comece cada job com whoami para que uma chave inválida falhe rápido, e proteja as escritas reais com --dry-run nos PRs versus alteração real na main, com chaves de idempotência derivadas de uma variável estável do CI para que a repetição de um pipeline seja um no-op:
```
# GitHub Actions
- name: FirstSales sync
  env:
    FIRSTSALES_API_KEY: ${{ secrets.FIRSTSALES_API_KEY }}
  run: |
    firstsales whoami --json > /dev/null || { echo "auth failed"; exit 1; }
    firstsales contact-imports create --org "$ORG_ID" --workspace "$WS_ID" \
      --data-file ./leads.csv --idempotency-key "import-${GITHUB_SHA}"
```
8
Monitore o uso e a margem de créditos
Acompanhe uso/logs da API key em Settings → API e o saldo de créditos do org em Billing para que um pipeline automatizado nunca deixe o org sem créditos silenciosamente. Veja Credits, Plans & Billing e Read Campaign Analytics.

Dicas de especialista

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

Uma chave com escopo por consumidor

CI, seu laptop e cada integração recebem sua própria chave nomeada — se uma vazar ou for aposentada, você revoga só ela, não tudo.

Chaves de idempotência são um seguro grátis

Toda criação automatizada carrega --idempotency-key para que uma etapa de pipeline reexecutada seja um no-op, não um registro duplicado.

Não construa sobre conectores em breve

Webhooks, CRM, Slack e conectores do Sheets retornam unsupported_operation hoje — faça polling ou exporte via REST + CSV em vez de esperar por eles.

Inspecione, dry-run, altere, verifique — também em scripts

O mesmo ciclo que protege um operador humano protege um agente. Sempre use --dry-run antes de qualquer escrita na automação, não só interativamente.

Perguntas frequentes

O que posso realmente automatizar hoje?

A REST API, a CLI e a importação/exportação de contatos em CSV/JSON, todas autenticadas com Developer API keys com escopo.

Há webhooks, CRM ou integrações com Slack?

Ainda não — webhooks, conectores de CRM (Salesforce, HubSpot, Zoho, Pipedrive) e conectores Slack/Teams/Sheets/Airtable/Notion estão em breve e retornam unsupported_operation. Não construa automação que dependa deles.

Como importo contatos programaticamente?

contact-imports create --data-file com um arquivo CSV ou JSON. Os contatos são deduplicados por e-mail no lado do servidor, então reexecutar a mesma importação é seguro.

Como funciona a autenticação no CI?

Armazene a Developer API key no armazenamento de segredos do seu provedor de CI e exponha-a como FIRSTSALES_API_KEY. Para HTTP puro, envie-a como um token Bearer.

Como evito escritas duplicadas em um pipeline?

Passe --idempotency-key (ou o header Idempotency-Key no HTTP puro) derivado de um valor estável como um SHA de commit — uma etapa reexecutada vira um no-op em vez de um duplicado.

Como evito que um delete apague dados no CI?

Comandos destrutivos da CLI exigem --confirm — mantenha-o fora de qualquer etapa que não deva excluir, para que um job de limpeza só remova dados quando a flag estiver explicitamente presente.

Como acompanho uso e margem de créditos?

Verifique o uso/logs da API key em Settings → API e o saldo de créditos do org em Billing para que um pipeline automatizado não te deixe sem créditos silenciosamente.

CLI ou API pura?

A CLI é um wrapper leve sobre a mesma superfície pública /api/v1. Ambas funcionam — a CLI adiciona tratamento de autenticação, idempotência e saída em JSON convenientes para scripts e agentes.

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

Playbook de RevOps: automatize o outbound com chaves de API, a CLI e CSV

Enquadre a superfície automatizável (e o que ainda não é)

Crie uma API key de privilégio mínimo