Utiliser FirstSales avec Codex

Connectez Codex à FirstSales via l'API REST (ou la CLI dans un shell) — premier appel whoami, clés à portée limitée, écritures idempotentes et arrêt sur les opérations non prises en charge.

8 min de lecture·Avancé·6 étapes

1
Choisissez le bon chemin pour votre configuration Codex
FirstSales propose deux voies d'intégration. Si votre environnement Codex dispose d'un shell avec npm, installez @firstsales.io/cli et pilotez-le comme n'importe quel agent shell — il gère l'authentification, le JSON et l'idempotence pour vous. Si Codex s'exécute sans accès shell (navigateur ou sandbox), appelez directement la Developer API en HTTPS. La documentation regroupe Codex avec les agents API-first précisément pour cette raison.
2
Stockez la clé comme secret d'environnement
Créez une clé Developer API dans Settings → API et placez-la dans le gestionnaire de secrets de votre environnement Codex sous FIRSTSALES_API_KEY. Ne collez jamais la clé brute dans un prompt et ne la committez jamais — référencez la variable d'environnement dans le code.
```
# in your Codex task's environment
FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
```
3
Vérifiez d'abord l'identité
Quel que soit le chemin choisi, le premier appel confirme que la clé pointe vers l'org et le workspace attendus :
```
curl https://api.app.firstsales.io/api/v1/whoami \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
```

Lisez l'état avant d'écrire

Faites en sorte que Codex inspecte avant de muter. Les ressources sont rattachées à une org et un 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"

Écrivez de façon idempotente

Sur les créations, envoyez un en-tête Idempotency-Key afin qu'une requête retentée ne duplique jamais de données — important pour un agent autonome susceptible de réessayer après 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
Gardez Codex sur la surface publique
Demandez à Codex de n'utiliser que les endpoints publics /api/v1. Face à une réponse unsupported_operation, il doit s'arrêter et le signaler — jamais faire de scraping de l'app ni appeler des routes privées, des callbacks de fournisseur, des pixels de tracking, des gestionnaires de désabonnement ou des endpoints cron pour forcer un résultat. Gérez explicitement 401 (mauvaise clé), 422 (validation — le corps nomme le champ), et 429 (temporisez).

Astuces de pro

Des raccourcis chèrement acquis pour garder le préchauffage sur la bonne voie.

Shell disponible ? Privilégiez le CLI

Si votre sandbox Codex peut exécuter npm, le CLI supprime beaucoup de code répétitif — authentification, JSON, idempotence et confirmation de suppression sont gérés pour vous. Ne repassez au HTTP brut que lorsqu'il n'y a pas de shell.

La clé vit dans l'environnement, pas dans le prompt

Placez FIRSTSALES_API_KEY dans le gestionnaire de secrets de Codex et référencez-la. Une clé dans le prompt finit dans les logs et l'historique.

whoami est le contrôle de sécurité le moins coûteux

Un seul appel confirme que Codex cible la bonne org et le bon workspace avant d'écrire quoi que ce soit. Le sauter, c'est comment des données finissent dans le mauvais workspace.

Idempotency-Key sur chaque création

Les agents autonomes réessaient. Une clé d'idempotence stable transforme un POST retenté en no-op plutôt qu'en contact en double ou en double facturation.

Questions fréquentes

Codex doit-il utiliser le CLI ou l'API ?

Si Codex dispose d'un accès shell avec npm, utilisez le CLI. S'il s'exécute dans un navigateur ou une sandbox sans shell, appelez la Developer API en HTTPS. Le chemin API est celui par défaut pour les agents basés navigateur.

Comment donner la clé à Codex en toute sécurité ?

Stockez-la sous FIRSTSALES_API_KEY dans le gestionnaire de secrets/environnement de Codex et référencez la variable dans le code. Ne collez pas la clé brute dans des prompts et ne la committez pas.

Quels sont l'URL de base et le premier appel ?

Base https://api.app.firstsales.io, authentification Bearer. Premier appel GET /api/v1/whoami pour confirmer le contexte org et workspace avant toute écriture.

Comment éviter les écritures en double lors des relances ?

Envoyez un en-tête Idempotency-Key sur les requêtes de création. Une relecture avec la même clé renvoie le résultat d'origine plutôt que de créer un second enregistrement.

Que Codex ne doit-il jamais faire ?

Ne jamais appeler de routes privées de l'app, de callbacks de fournisseur, de pixels de tracking, de gestionnaires de désabonnement ou d'endpoints cron internes, et ne jamais faire de scraping de l'interface de l'app. Rester sur /api/v1 public ; s'arrêter et signaler sur unsupported_operation.

Prêt à passer à la pratique ?

Démarrez votre essai FirstSales et lancez une boîte mail préchauffée et authentifiée en quelques minutes.

Commencer pour 1 $

Tous les tutoriels