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_operationse 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.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 doctorImporte 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-runantes 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/v1diretamente 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"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
whoamipara que uma chave inválida falhe rápido, e proteja as escritas reais com--dry-runnos 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}"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
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.