Enmarca la superficie automatizable (y lo que aún no lo es)
Lo que está en vivo hoy: la REST API, la CLI, y la importación/exportación de contactos en CSV/JSON. Lo que no: los webhooks, los conectores CRM (Salesforce, HubSpot, Zoho, Pipedrive) y los conectores de Slack/Teams/Sheets/Airtable/Notion están todos próximamente y devuelven
unsupported_operationsi intentas llamarlos. Construye tu automatización sobre la superficie en vivo: haz polling y exporta vía REST/CSV en lugar de esperar un conector.Genera una API key de mínimo privilegio
Ve a Settings → API y crea una key nombrada por consumidor: p. ej.
ci-contact-sync: con solo los scopes que necesita (contacts:read/write,campaigns:read, etc.). La key se muestra una sola vez; cópiala directo a un gestor de secretos. Revócala de inmediato si alguna vez se filtra: la revocación es instantánea. Consulta Create & Manage Developer API Keys.
Instala y verifica la CLI
Instala la CLI y confirma que la key se resuelve antes de hacer cualquier otra cosa:
npm install -g @firstsales.io/cli export FIRSTSALES_API_KEY="fs_live_..." # from your secret manager firstsales whoami --json firstsales doctorImporta contactos programáticamente desde CSV
Envía un lote a través de un job de importación con una idempotency key: la plataforma deduplica por correo del lado del servidor, así que reejecutar el mismo archivo no duplicará a nadie:
firstsales contact-imports create --org "$ORG_ID" --workspace "$WS_ID" \ --data-file ./leads.csv \ --idempotency-key "leads-import-2026-07"Mantén los contactos sincronizados: el bucle de oro
La automatización sigue el mismo bucle que un operador humano: inspeccionar, luego mutar deliberadamente, luego verificar. Previsualiza con
--dry-runantes de cualquier escritura, muta con una idempotency key, luego vuelve a leer 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"Impulsa campañas desde la CLI o la API
Lista y lee campañas a través de la CLI, o pega directamente a
/api/v1con un Bearer token cuando prefieras no usar la 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"Conéctalo a CI/CD
Inyecta la key desde el almacén de secretos de tu proveedor de CI, nunca la codifiques directamente. Empieza cada job con
whoamipara que una key mala falle rápido, y controla las escrituras reales con--dry-runen PRs frente a mutación real en main, con idempotency keys derivadas de una variable de CI estable para que un paso de pipeline repetido sea un 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}"Monitorea el uso y la autonomía de créditos
Vigila el uso/logs de la API key bajo Settings → API y el saldo de créditos del org bajo Billing para que un pipeline automatizado nunca deje al org sin recursos en silencio. Consulta Credits, Plans & Billing y Read Campaign Analytics.
Consejos de experto
Una key con scope por consumidor
CI, tu laptop y cada integración obtienen su propia key nombrada: filtra o retira una y revocas solo esa key, no todo.
Las idempotency keys son un seguro gratis
Cada creación automatizada lleva --idempotency-key para que un paso de pipeline reintentado sea un no-op, no un registro duplicado.
No construyas sobre conectores próximamente
Los webhooks, CRM, Slack y Sheets devuelven unsupported_operation hoy: haz polling o exporta vía REST + CSV en lugar de esperarlos.
Inspecciona, dry-run, muta, verifica: también en scripts
El mismo bucle que protege a un operador humano protege a un agente. Siempre --dry-run antes de cualquier escritura en automatización, no solo interactivamente.
Preguntas frecuentes
¿Qué puedo automatizar realmente hoy?
La REST API, la CLI, y la importación/exportación de contactos en CSV/JSON, todo autenticado con Developer API keys con scope.
¿Hay integraciones de webhooks, CRM o Slack?
Todavía no: los webhooks, los conectores CRM (Salesforce, HubSpot, Zoho, Pipedrive) y los conectores de Slack/Teams/Sheets/Airtable/Notion están próximamente y devuelven unsupported_operation. No construyas automatización que dependa de ellos.
¿Cómo importo contactos programáticamente?
contact-imports create --data-file con un archivo CSV o JSON. Los contactos se deduplican por correo del lado del servidor, así que reejecutar la misma importación es seguro.
¿Cómo funciona la autenticación para CI?
Guarda la Developer API key en el almacén de secretos de tu proveedor de CI y expónla como FIRSTSALES_API_KEY. Para HTTP directo, envíala como un Bearer token.
¿Cómo evito escrituras duplicadas en un pipeline?
Pasa --idempotency-key (o el header Idempotency-Key en HTTP directo) derivada de un valor estable como un commit SHA: un paso reintentado se convierte en un no-op en lugar de un duplicado.
¿Cómo evito que un delete borre datos en CI?
Los comandos destructivos de la CLI requieren --confirm: mantenlo fuera de cualquier paso que no deba borrar, así un job de limpieza solo puede eliminar datos cuando el flag está explícitamente presente.
¿Cómo vigilo el uso y la autonomía de créditos?
Revisa el uso/logs de la API key bajo Settings → API y el saldo de créditos del org bajo Billing para que un pipeline automatizado no te deje sin créditos en silencio.
¿CLI o API directa?
La CLI es un wrapper delgado sobre la misma superficie pública /api/v1. Ambas funcionan: la CLI agrega manejo de autenticación conveniente, idempotencia y salida en JSON para scripts y agentes.