NuevoVer cómo
FirstSales
Inicio/Tutoriales/Guía rápida de la API de FirstSales
Desarrollador y CLI

Guía rápida de la API de FirstSales

Genera una clave de API y haz tus primeras llamadas — crea contactos, inscríbelos en campañas y extrae respuestas de la bandeja de entrada vía la API REST.

9 min de lectura·Avanzado·7 pasos
  1. 1

    Genera una clave de API para desarrolladores

    En la app ve a Settings → API y crea una Developer API key. Define sus alcances (scopes) y su nivel de acceso (solo lectura o lectura-escritura) al mínimo que necesite la integración. El secreto se muestra una sola vez — cópialo de inmediato en un gestor de secretos; la app solo guarda una forma redactada.

    Revoca y regenera en la misma página si alguna vez se filtra una clave.

  2. 2

    Verifica la identidad con whoami

    La URL base es https://api.app.firstsales.io. La autenticación es un token Bearer. Empieza siempre confirmando que la clave resuelve a la organización y el espacio de trabajo que esperas — GET /api/v1/whoami:

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

    Encuentra los IDs de tu organización y espacio de trabajo

    Cada recurso está delimitado a una organización y un espacio de trabajo, así que la mayoría de las rutas se ven como /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Lístalos:

    # Organizations you can access
curl https://api.app.firstsales.io/api/v1/organizations \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"

# Workspaces inside an org
curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  4. 4

    Crea un contacto (de forma idempotente)

    Haz un POST de un contacto dentro de un espacio de trabajo. Envía un encabezado Idempotency-Key para que una solicitud reintentada nunca cree un duplicado — seguro de repetir tras un fallo de red.

    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: jane-acme-2026-01" \
  -d '{ "email": "jane@acme.com", "first_name": "Jane", "company_name": "Acme" }'
  5. 5

    Lee las analíticas de una campaña

    Extrae métricas de embudo y de interacción de una campaña para sincronizar los resultados en tu propio reporting — sin hacer scraping del dashboard:

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/campaigns/CAMPAIGN_ID/analytics \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  6. 6

    Lee las respuestas desde la bandeja de entrada

    Lista los hilos de la bandeja de entrada para extraer envíos, aperturas, respuestas y rebotes hacia tus sistemas. Los cuerpos de los hilos se redactan en la vista de lista; obtén un solo hilo para el detalle. Así es como enrutas respuestas positivas hacia un CRM mientras los conectores nativos siguen en camino.

    curl https://api.app.firstsales.io/api/v1/organizations/ORG_ID/workspaces/WS_ID/inbox/threads \
  -H "Authorization: Bearer $FIRSTSALES_API_KEY"
  7. 7

    Mantente dentro de la superficie pública

    La API solo expone la superficie pública /api/v1. No llames a rutas privadas de la app, callbacks de proveedores, píxeles de seguimiento, manejadores de baja de suscripción, o rutas cron internas — no forman parte del contrato y se romperán. Si una llamada devuelve unsupported_operation, detente y trátalo como "no disponible vía la API", no como algo que rodear.

    Aplican los códigos de estado estándar: 401 clave inválida/revocada, 422 validación (el body indica el campo), 429 límite de tasa (reduce la frecuencia y reintenta).

Consejos de experto

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

1

whoami antes de escribir

Confirma que la clave resuelve a la organización/espacio de trabajo que pretendes antes de cualquier llamada que modifique datos. Una clave con alcance al espacio de trabajo equivocado es la forma más común de escribir datos en el lugar incorrecto.

2

Envía siempre un Idempotency-Key en las creaciones

Los reintentos de red ocurren. Un Idempotency-Key hace que un POST repetido sea una operación nula en vez de un contacto duplicado o un cobro doble.

3

Guarda la clave una vez, nunca la imprimas

El secreto se muestra una sola vez y se guarda redactado. Ponlo directo en un gestor de secretos; nunca lo registres en logs, lo subas a un commit, ni lo envíes dentro de un bundle de cliente.

4

Trata unsupported_operation como una parada dura

Si la API devuelve unsupported_operation, lo que quieres hacer no está en el contrato público. No recurras a rutas privadas de la app para forzarlo — reporta la limitación.

Preguntas frecuentes

¿Dónde consigo una clave de API?

Settings → API. Crea una Developer API key con los alcances y el nivel de acceso que necesitas; se muestra una sola vez, así que cópiala de inmediato. Revoca y regenera en la misma página si queda expuesta.

¿Cuál es la URL base y la autenticación?

URL base https://api.app.firstsales.io; autentica con Authorization: Bearer $FIRSTSALES_API_KEY y envía JSON. Empieza con GET /api/v1/whoami para confirmar el contexto.

¿Por qué las rutas son tan largas?

Los recursos están delimitados a una organización y un espacio de trabajo, así que las rutas son /api/v1/organizations/{orgId}/workspaces/{workspaceId}/…. Obtén los IDs desde /api/v1/organizations y su subrecurso /workspaces (o desde whoami).

¿Cómo evito escrituras duplicadas?

Envía un encabezado Idempotency-Key en las solicitudes de creación. Una solicitud reintentada con la misma clave devuelve el resultado original en vez de crear un segundo registro — segura de repetir tras un timeout.

¿Puedo leer métricas de campaña y respuestas?

Sí — GET …/campaigns/{id}/analytics para embudo/interacción, y GET …/inbox/threads para actividad de conversación. Los cuerpos de los hilos se redactan en la lista; obtén un solo hilo para el detalle completo.

¿Hay una integración de Zapier o CRM en su lugar?

No hay conector de Zapier, y los conectores nativos de CRM (Salesforce, HubSpot, Pipedrive) todavía están en camino. Hasta que se lancen, la API REST — o el CLI — es la forma soportada de integrar y sincronizar.

¿Qué significa unsupported_operation?

La acción solicitada no forma parte del contrato público /api/v1. Detente y repórtalo — no llames a rutas privadas de la app, callbacks, píxeles ni endpoints internos para rodearlo; no están soportados y se romperán.

¿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