NuevoVer cómo
FirstSales
Inicio/Tutoriales/Usar FirstSales con Gemini
Desarrollador y CLI

Usar FirstSales con Gemini

Conecta Gemini a FirstSales vía la API REST con herramientas de función acotadas — leer antes de escribir, alcances por herramienta y mutaciones seguras y verificables.

8 min de lectura·Avanzado·6 pasos
  1. 1

    Dos formas de conectar Gemini

    Si tu entorno de Gemini (por ejemplo, la CLI de Gemini con acceso a shell) puede ejecutar npm, instala @firstsales.io/cli y expónla como herramienta: se encarga de la autenticación, el JSON y la idempotencia. Si Gemini solo trabaja con API, llama a la Developer API de FirstSales por HTTPS desde tus implementaciones de función/herramienta. La documentación ubica a Gemini con los agentes API-first por defecto.

  2. 2

    Guarda la clave fuera del modelo

    Crea una clave de Developer API en Settings → API y guárdala en la configuración del lado del servidor de tu app como FIRSTSALES_API_KEY. Gemini debe llamar a una tool/función que lea la clave en el servidor: el modelo en sí nunca debe ver ni emitir la clave en bruto.

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

    Define herramientas acotadas, no una vía de escape HTTP genérica

    Dale a Gemini un pequeño conjunto de funciones diseñadas para un propósito específico — whoami, list_contacts, create_contact, campaign_analytics — cada una mapeada a un único endpoint público. Esto mantiene al modelo dentro de la superficie compatible en lugar de dejarlo construir URLs arbitrarias.

    # 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

    Verifica la identidad en la primera llamada a herramienta

    Haz que el agente llame a whoami antes de cualquier escritura, para que confirme el contexto de organización y workspace:

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

    Escribe de forma idempotente desde tu herramienta de creación

    Tu herramienta create_contact siempre debe adjuntar una Idempotency-Key para que una llamada de función reintentada no pueda escribir dos veces:

    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

    Gestiona errores y mantente en la superficie pública

    En cada herramienta, gestiona 401 (clave incorrecta o revocada), 422 (validación — expón el campo) y 429 (espera y reintenta). Ante unsupported_operation, devuelve la limitación al modelo y detente — nunca dejes que Gemini haga scraping de la app o acceda a rutas privadas, callbacks, píxeles o endpoints de cron.

Consejos de experto

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

1

Envuelve los endpoints como herramientas acotadas

No le des a Gemini una función genérica de 'llamar a cualquier URL'. Las herramientas diseñadas para un propósito específico (create_contact, campaign_analytics) mantienen al modelo en la superficie pública y hacen sus acciones auditables.

2

El modelo nunca toca la clave

Lee FIRSTSALES_API_KEY en el servidor, dentro de la herramienta. Si la clave puede aparecer en el contexto o la salida del modelo, puede filtrarse a los logs.

3

whoami como primera llamada a función

Haz de la verificación de identidad el primer movimiento, para que Gemini siempre confirme la organización/workspace antes de escribir.

4

¿Tienes shell disponible? La CLI implica menos código

Si la CLI de Gemini tiene shell + npm, usar firstsales por línea de comandos supera construir herramientas HTTP a mano — la autenticación, el JSON, la idempotencia y la confirmación de borrado vienen incluidas.

Preguntas frecuentes

¿Gemini usa la CLI o la API?

Por defecto, la Developer API, envuelta como funciones/herramientas. Si tu entorno de Gemini tiene acceso a shell con npm, la CLI es una alternativa que requiere menos esfuerzo y gestiona la autenticación y la idempotencia por ti.

¿Cómo mantengo la clave alejada del modelo?

Guarda FIRSTSALES_API_KEY en la configuración del lado del servidor y léela dentro de la implementación de la herramienta. El modelo llama a la herramienta; nunca ve ni emite la clave en bruto.

¿Cómo debería estructurar las herramientas?

Como funciones acotadas y de propósito único — una por endpoint público (whoami, listar/crear contacto, campaign analytics). Evita una herramienta genérica de 'obtener cualquier URL' que le permita al modelo salir de la superficie compatible.

¿Cómo evito escrituras duplicadas?

Adjunta un encabezado Idempotency-Key dentro de tu herramienta de creación. Una llamada de función reintentada con la misma clave devuelve el resultado original en lugar de crear un duplicado.

¿Qué está fuera de los límites permitidos?

Rutas privadas de la app, callbacks de proveedores, píxeles de seguimiento, gestores de cancelación de suscripción, endpoints internos de cron y el scraping de la interfaz. Mantente en /api/v1 público; detente 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