Saltar al contenido
NuevoVer cómo

Usar FirstSales con Codex

Conecta Codex a FirstSales vía la API REST (o la CLI en una shell) — primera llamada whoami, claves con alcance limitado, escrituras idempotentes, y detenerse ante operaciones no soportadas.

Tutoriales
Desarrollador y CLI
min de lectura
8 min
pasos
6 · Avanzado

  1. Elige el camino correcto para tu configuración de Codex

    FirstSales ofrece dos vías de integración. Si tu entorno de Codex tiene shell con npm, instala @firstsales.io/cli y opérala como cualquier agente de shell: se encarga de la autenticación, el JSON y la idempotencia por ti. Si Codex se ejecuta sin acceso a shell (navegador o sandbox), llama directamente a la Developer API por HTTPS. La documentación agrupa a Codex con los agentes API-first exactamente por esta razón.

  2. Guarda la clave como un secreto de entorno

    Crea una Developer API key en Settings → API y ponla en el almacén de secretos de tu entorno de Codex como FIRSTSALES_API_KEY. Nunca pegues la clave en crudo en un prompt ni la hagas commit: referencia la variable de entorno en el código.

    # in your Codex task's environment
FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io

  3. Verifica la identidad primero

    Sea cual sea la vía, la primera llamada confirma que la clave resuelve a la org y al workspace que esperas:

    curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

  4. Lee el estado antes de escribir

    Haz que Codex inspeccione antes de mutar. Los recursos están acotados a org y 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"

  5. Escribe de forma idempotente

    En las creaciones, envía una cabecera Idempotency-Key para que una solicitud reintentada nunca duplique datos: importante para un agente autónomo que puede reintentar tras un 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":"[email protected]","first_name":"Sam"}'

  6. Mantén a Codex en la superficie pública

    Indica a Codex que use únicamente los endpoints públicos /api/v1. Ante una respuesta unsupported_operation debe detenerse y reportarlo (nunca hacer scraping de la app ni llamar a rutas privadas, callbacks de proveedores, píxeles de seguimiento, gestores de baja, o endpoints de cron para forzar un resultado. Maneja explícitamente 401 (clave incorrecta), 422 (validación) el cuerpo nombra el campo), y 429 (reduce la frecuencia).

Consejos de experto

  • ¿Tienes shell disponible? Prioriza la CLI

    Si tu sandbox de Codex puede ejecutar npm, la CLI elimina mucho código repetitivo: la autenticación, el JSON, la idempotencia y la confirmación de eliminaciones ya están resueltas. Recurre a HTTP en crudo solo cuando no haya shell.

  • La clave vive en el entorno, no en el prompt

    Pon FIRSTSALES_API_KEY en el almacén de secretos de Codex y referéncialo. Una clave en el prompt termina en logs e historial.

  • whoami es la verificación de seguridad más barata

    Una sola llamada confirma que Codex apunta a la org y al workspace correctos antes de que escriba nada. Saltársela es cómo los datos terminan en el workspace equivocado.

  • Idempotency-Key en cada creación

    Los agentes autónomos reintentan. Una idempotency key estable convierte un POST reintentado en un no-op en lugar de un contacto duplicado o un cargo doble.

Preguntas frecuentes

¿Debería Codex usar la CLI o la API?

Si Codex tiene acceso a shell con npm, usa la CLI. Si se ejecuta en un navegador o en un sandbox sin shell, llama a la Developer API por HTTPS. La vía de la API es la predeterminada para agentes basados en navegador.

¿Cómo le doy a Codex la clave de forma segura?

Guárdala como FIRSTSALES_API_KEY en el entorno/almacén de secretos de Codex y referencia la variable en el código. No pegues la clave en crudo en prompts ni la hagas commit.

¿Cuál es la URL base y la primera llamada?

Base https://api.app.firstsales.io, autenticación Bearer. Primera llamada GET /api/v1/whoami para confirmar el contexto de org y workspace antes de cualquier escritura.

¿Cómo evito escrituras duplicadas en los reintentos?

Envía una cabecera Idempotency-Key en las solicitudes de creación. Una repetición con la misma clave devuelve el resultado original en lugar de crear un segundo registro.

¿Qué es lo que Codex nunca debe hacer?

Nunca llamar a rutas privadas de la app, callbacks de proveedores, píxeles de seguimiento, gestores de baja, o endpoints internos de cron, y nunca hacer scraping de la interfaz de la app. Mantente en /api/v1 público; detente y reporta ante unsupported_operation.

Desarrollador y CLI

Prospección que sigue cuando te desconectas.Leads, emails, seguimientos y respuestas, resueltos.

Conecta buzones ilimitados y deja que los agentes de IA busquen leads, escriban cada email y hagan seguimiento. O envía tus propias plantillas en modo manual. Desde $29/mes.

Empieza tu prueba de $1 Ver precios

$1 por 3 días · Cancela cuando quieras · Sin contrato

Instalar con IA

Tu agente de código configura la CLI y las skills de FirstSales por ti.

Prompt para Claude Code

I'm setting up FirstSales (https://firstsales.io), an AI outbound sales platform: campaigns, contacts, a reply inbox, deliverability and lead signals. Help me get my workspace sending real, good emails end to end, from Claude Code.

Read these first so you know how FirstSales works:
- Developer docs and API: https://developer.firstsales.io
- CLI: https://www.npmjs.com/package/@firstsales.io/cli
- Skills for coding agents: https://github.com/firstsalesio/firstsales-skills (read README.md and GUIDE.md)

Setup
1. Install the CLI: npm install -g @firstsales.io/cli
2. Install the FirstSales skills:
   claude plugin marketplace add firstsalesio/firstsales-skills
   claude plugin install firstsales@firstsales
3. Ask me if I already have a FirstSales account. If not, send me to https://app.firstsales.io to sign up.
4. Ask me to create an API key under Settings → API → API Keys, with only the scopes we need.
   Never ask me to paste the key into this chat. Tell me to run this in my own terminal, so the key stays hidden:
   read -rs FS_KEY && firstsales auth login --api-key "$FS_KEY"; unset FS_KEY
5. Run `firstsales whoami` and tell me which workspace and organisation we are connected to.

Then ask me about my business: what I sell, who I sell to (roles, company size, countries), my best customers, and what I use today for outbound (tools, lists, mailboxes). Walk me through:
1. Teaching FirstSales my business: website, offer, proof points and case studies in the knowledge base, so the AI writes like someone who knows the product.
2. Connecting my sending mailboxes and checking my sending domain: SPF, DKIM, DMARC and warm-up. If anything is unhealthy, tell me the exact DNS record to add.
3. Bringing in contacts: import my CSV or CRM export into a clean list, remove duplicates and bad emails, and block domains I must never email (customers, competitors, my own).
4. Building my first campaign: the right list, senders, steps and timing. Write the sequence with me, show me the drafts, and do not launch until I say yes.
5. Setting up Signals if it fits: find people engaging with LinkedIn posts about topics my buyers care about, and turn them into leads.
6. Inviting my team and giving each person the right access.

Once campaigns run, show me how to work the reply inbox from here: which replies need an answer, draft responses in my voice, and move good conversations into deals. If I use Cal.com, connect it so follow-ups can offer my booking link (not the first email).

Throughout, as you learn about my business, proactively suggest and help create:
- Reply templates for the questions and objections my prospects are likely to raise, based on my product, site and codebase if you can see them.
- Campaign ideas and segments worth testing, with the reason for each.

Safety rules:
- Show every change as a dry run (--dry-run) first and wait for my yes. Never send emails, launch campaigns or delete anything without my yes.
- Tell me before anything that spends credits, and how many.

Be opinionated. If the docs give a sensible default, just use it. Don't make me choose between five options.
Developer docs ↗npm: @firstsales.io/cli ↗GitHub: firstsales-skills ↗