Primeros pasos¶

De cero a tu primera campaña de prueba en unos 5 minutos. Esta guía asume que ya tienes —o estás por solicitar— tu API Key.

A lo largo de la guía usamos la base URL canónica mediante la variable API_BASE_URL:

API_BASE_URL="https://api.neuronstudio.ai"

Paso 1 — Obtén tu API Key¶

Las API Keys no son self-serve: no se generan desde un panel público. Las emite un administrador de tu organización y se muestran una sola vez al momento de crearlas.

👉 Solicita tu API Key a tu contacto de Neuron o al administrador de tu organización.

Tu key tiene este formato:

nrn_live_abcdef1234567890abcdef1234567890

Cada key tiene un scope asociado (read o full). Para lanzar campañas necesitas una key con scope full. Más detalle en Autenticación.

Guarda la key en un gestor de secretos o variable de entorno. Nunca la incrustes en código de frontend ni la subas a un repositorio.

Paso 2 — Prueba la autenticación con un GET simple¶

El test más rápido para confirmar que tu key funciona es listar los agents de tu organización. Es una lectura (GET), así que funciona con cualquier scope:

curl "$API_BASE_URL/api/agents" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890"

Respuesta esperada:

{
  "success": true,
  "agents": [
    { "agent_id": "agent_abc123", "agent_name": "Cobranza Español", "agent_type": "collections" }
  ]
}

• Si ves la lista de agents → tu key está activa. Anota el agent_id que vas a usar.
• Si recibes 401 → la key es inválida o falta el header X-API-Key.
• Si agents viene vacío → tu organización todavía no tiene agents asignados; contacta a tu equipo de Neuron.

(Ver el catálogo completo de errores en Errores y troubleshooting.)

Paso 3 — Descarga la plantilla CSV¶

Cada tipo de campaña tiene su propio formato de columnas. Descarga la plantilla del tipo que vas a usar:

curl "$API_BASE_URL/api/csv-template?type=collections" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890" \
  -o plantilla.csv

Columnas requeridas por tipo:

• to_number: teléfono en formato E.164 (ej. +525512345678).
• lead_id: identificador único de cada contacto.
• Las columnas extra que agregues se preservan y se pasan al motor de llamadas.
• Las filas sin to_number o sin lead_id se saltan.

Paso 4 — Lanza una primera campaña de prueba (1 contacto)¶

⚠️ No existe modo sandbox ni dry-run. Un start exitoso dispara llamadas reales de inmediato. Para probar sin impacto, usa una lista de 1 solo contacto con tu propio número, fuera del horario productivo.

El procedimiento seguro completo está en la receta “Probar sin impacto” (recipe 02).

Ejemplo mínimo con un único contacto (pon tu propio número en to_number):

curl -X POST "$API_BASE_URL/api/campaign/start" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prueba de integración",
    "csv_content": "to_number,lead_id,client_name,debt\n+525512345678,L001,Prueba,100",
    "agent_id": "agent_abc123",
    "campaign_type": "collections"
  }'

Respuesta esperada:

{
  "success": true,
  "campaign_id": 123,
  "total_leads": 1,
  "agent_id": "agent_abc123",
  "campaign_type": "collections",
  "message": "Campaign 'Prueba de integración' started"
}

Guarda el campaign_id: lo vas a usar para monitorear y consultar resultados.

Mientras corre, puedes ver el estado en tiempo real:

curl "$API_BASE_URL/api/campaign/status" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890"

{
  "success": true,
  "status": { "state": "running", "campaign_id": 123, "active_calls": 1, "queue_size": 0 },
  "campaign": { "...": "..." },
  "global_status": { "...": "..." }
}

Paso 5 — Consulta los resultados (polling)¶

Los resultados se obtienen consultando los endpoints de analytics (no hay push por webhooks todavía). Filtra por tu campaign_id y pagina con el cursor:

curl "$API_BASE_URL/api/analytics/calls?campaign_ids=123&limit=100" \
  -H "X-API-Key: nrn_live_abcdef1234567890abcdef1234567890"

{
  "success": true,
  "calls": [
    {
      "call_id": "call_abc",
      "campaign_id": 123,
      "client_name": "Prueba",
      "call_status": "completed",
      "call_outcome": "promised_payment",
      "sentiment": "positive",
      "payment_promised": true,
      "summary": "..."
    }
  ],
  "pagination": { "limit": 100, "count": 1, "has_more": false, "next_cursor": null }
}

Para campañas grandes, repite el GET pasando cursor=<next_cursor> hasta que has_more sea false. El patrón completo de polling y paginación está en las recetas.

Siguientes pasos¶

• Autenticación — scopes, JWT de sesión y buenas prácticas.
• Endpoints — referencia detallada de cada endpoint.
• Recetas — flujos completos: probar sin impacto, paginar resultados, etc.
• Límites de uso — cuántas requests por minuto y cómo manejar el 429.