NouveauDécouvrir comment
FirstSales
Accueil/Tutoriels/Utiliser FirstSales avec Gemini
Développeur & CLI

Utiliser FirstSales avec Gemini

Reliez Gemini à FirstSales via l'API REST avec des outils fonctionnels restreints — lecture avant écriture, portées par outil et mutations sûres et vérifiables.

8 min de lecture·Avancé·6 étapes
  1. 1

    Deux façons de connecter Gemini

    Si votre environnement Gemini (par exemple la CLI Gemini avec accès shell) peut exécuter npm, installez @firstsales.io/cli et exposez-la comme outil — elle gère l'authentification, le JSON et l'idempotence. Si Gemini fonctionne uniquement via API, appelez la Developer API de FirstSales en HTTPS depuis vos implémentations de fonction/outil. La documentation classe Gemini par défaut parmi les agents API-first.

  2. 2

    Stockez la clé en dehors du modèle

    Créez une clé Developer API dans Settings → API et conservez-la dans la configuration côté serveur de votre application sous FIRSTSALES_API_KEY. Gemini doit appeler un tool/function qui lit la clé côté serveur — le modèle lui-même ne doit jamais voir ni émettre la clé brute.

    FIRSTSALES_API_KEY=fs-key-...
FIRSTSALES_BASE_URL=https://api.app.firstsales.io
  3. 3

    Définissez des outils restreints, pas une échappatoire HTTP brute

    Donnez à Gemini un petit ensemble de fonctions dédiées — whoami, list_contacts, create_contact, campaign_analytics — chacune correspondant à un seul endpoint public. Cela maintient le modèle sur la surface prise en charge au lieu de le laisser construire des URL arbitraires.

    # what each tool calls under the hood
GET  /api/v1/whoami
GET  /api/v1/organizations/{org}/workspaces/{ws}/contacts
POST /api/v1/organizations/{org}/workspaces/{ws}/contacts     # Idempotency-Key
GET  /api/v1/organizations/{org}/workspaces/{ws}/campaigns/{id}/analytics
  4. 4

    Vérifiez l'identité dès le premier appel d'outil

    Demandez à l'agent d'appeler whoami avant toute écriture afin qu'il confirme le contexte de l'org et du workspace :

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

    Écrivez de façon idempotente depuis votre outil de création

    Votre outil create_contact doit toujours attacher un Idempotency-Key afin qu'un appel de fonction rejoué ne puisse pas créer un doublon :

    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: gemini-lead-2026-01" \
  -d '{"email":"lead@acme.com","first_name":"Sam"}'
  6. 6

    Gérez les erreurs et restez sur la surface publique

    Dans chaque outil, gérez le 401 (clé invalide/révoquée), le 422 (validation — remontez le champ concerné) et le 429 (patientez, puis réessayez). Sur unsupported_operation, renvoyez la limitation au modèle et arrêtez-vous — ne laissez jamais Gemini scraper l'application ou accéder à des routes privées, des callbacks, des pixels ou des endpoints cron.

Astuces de pro

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

1

Encapsulez les endpoints en outils restreints

Ne donnez pas à Gemini une fonction générique « appeler n'importe quelle URL ». Des outils dédiés (create_contact, campaign_analytics) maintiennent le modèle sur la surface publique et rendent ses actions auditables.

2

Le modèle ne touche jamais la clé

Lisez FIRSTSALES_API_KEY côté serveur, à l'intérieur de l'outil. Si la clé peut apparaître dans le contexte ou la sortie du modèle, elle peut fuiter dans les logs.

3

whoami comme premier appel de fonction

Faites de la vérification d'identité le tout premier geste, afin que Gemini confirme toujours l'org/le workspace avant d'écrire.

4

Shell disponible ? La CLI demande moins de code

Si la CLI Gemini dispose d'un shell et de npm, appeler firstsales en ligne de commande est plus simple que de coder des outils HTTP à la main — l'authentification, le JSON, l'idempotence et la confirmation de suppression sont inclus.

Questions fréquentes

Gemini utilise-t-il la CLI ou l'API ?

Par défaut la Developer API, encapsulée sous forme de fonctions/outils. Si votre environnement Gemini dispose d'un accès shell avec npm, la CLI est une alternative demandant moins d'effort, qui gère l'authentification et l'idempotence pour vous.

Comment garder la clé à l'écart du modèle ?

Stockez FIRSTSALES_API_KEY dans la configuration côté serveur et lisez-la à l'intérieur de l'implémentation de l'outil. Le modèle appelle l'outil ; il ne voit ni n'émet jamais la clé brute.

Comment structurer les outils ?

Sous forme de fonctions restreintes, à usage unique — une par endpoint public (whoami, liste/création de contact, campaign analytics). Évitez un outil générique « récupérer n'importe quelle URL » qui laisserait le modèle sortir de la surface prise en charge.

Comment éviter les écritures en double ?

Attachez un en-tête Idempotency-Key à l'intérieur de votre outil de création. Un appel de fonction rejoué avec la même clé renvoie le résultat original au lieu de créer un doublon.

Qu'est-ce qui est interdit ?

Les routes privées de l'application, les callbacks des fournisseurs, les pixels de suivi, les gestionnaires de désabonnement, les endpoints cron internes, et le scraping de l'interface. Restez sur /api/v1 public ; arrêtez-vous 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