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.

8 min de lectura·Avanzado·6 pasos

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"
```

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"

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":"lead@acme.com","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

Atajos aprendidos a fuerza de experiencia para mantener el precalentamiento en curso.

¿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.

¿Listo para ponerlo en práctica?

Comienza tu prueba de FirstSales y lanza un buzón precalentado y autenticado en minutos.

Empieza por $1

Todos los tutoriales