Receta 1 — Primera integración (end-to-end)¶

Esta es la receta canónica: el happy path completo, de cero a resultados. Al terminar vas a haber autenticado, elegido un agent, armado un CSV, lanzado una campaña real, monitoreado su avance y leído los resultados de las llamadas.

Lo que vas a lograr:

1. Obtener y configurar tu API Key.
2. Verificar la autenticación.
3. Listar los agents de tu organización y elegir uno.
4. (Opcional) Descargar la plantilla CSV y armar tu lista de contactos.
5. Lanzar la campaña (POST /api/campaign/start).
6. Monitorear el estado (GET /api/campaign/status).
7. Obtener los resultados por polling (GET /api/analytics/calls y el detalle por llamada).

⚠️ Importante antes de empezar: un start exitoso dispara llamadas reales de inmediato — no hay modo de prueba. Si es la primera vez que integras, haz primero la Receta 2 — Probar sin impacto, que valida todo el flujo con una única llamada a tu propio número.

Prerrequisitos¶

• Una API Key con scope full (necesario para lanzar campañas). Las keys no son self-serve: solicita la tuya a tu contacto de Neuron / al administrador de tu organización. Se muestra una sola vez al crearse.
• Una herramienta para hacer requests HTTP (curl en estos ejemplos) y, opcionalmente, jq para formatear el JSON.

Define estas dos variables una vez y reutilízalas en todos los pasos:

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

Paso 1 — Obtener tu API Key¶

La API Key tiene el formato nrn_live_ + 32 caracteres hexadecimales (41 caracteres en total), por ejemplo nrn_live_abcdef1234567890abcdef1234567890. Va en el header X-API-Key de cada request.

La key está vinculada a tu organización: solo ve los datos de tu propia organización, sin que tengas que enviar ningún identificador adicional.

No la generas tú desde un panel: pídesela a tu contacto de Neuron / administrador de tu organización. Guárdala como secreto (variable de entorno, gestor de secretos) — nunca la escribas en el código fuente ni la subas a un repositorio.

Paso 2 — Verificar la autenticación¶

Antes de operar, confirma que tu key funciona con una lectura simple. Listar tus campañas es una buena prueba (no modifica nada):

curl -s "$API_BASE_URL/api/campaigns" \
  -H "X-API-Key: $API_KEY"

Respuesta esperada (200):

{
  "success": true,
  "campaigns": [ ]
}

Si recibes 401, la key es inválida o está mal escrita. Si recibes 403 en un endpoint de escritura, tu key probablemente tiene scope read (solo lectura) y no full.

Paso 3 — Listar los agents y elegir uno¶

Un agent es la configuración de voz/conversación que atenderá las llamadas. Tu organización tiene uno o más agents asignados durante el onboarding. Lístalos:

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

Respuesta:

{
  "success": true,
  "agents": [
    { "agent_id": "agent_abc123", "agent_name": "Cobranza Español", "agent_type": "collections" },
    { "agent_id": "agent_xyz789", "agent_name": "Calificación de Leads", "agent_type": "sdr" }
  ]
}

Puedes filtrar por tipo con ?type=:

curl -s "$API_BASE_URL/api/agents?type=collections" \
  -H "X-API-Key: $API_KEY"

Anota el agent_id del agent que vas a usar. El agent_type del agent debe coincidir con el campaign_type de la campaña que vas a lanzar.

Si la lista vuelve vacía ("agents": []), todavía no hay agents asignados a tu organización → contacta a tu equipo de Neuron.

Tipos disponibles (campaign_type / agent_type): collections (cobranza, default), sdr (ventas / calificación de leads), cx (atención al cliente), interviewer (entrevistas).

Paso 4 — Armar el CSV de contactos¶

Cada fila del CSV es un contacto a llamar. Las columnas requeridas dependen del tipo de campaña:

• to_number — teléfono del contacto en formato E.164 (+ país + número, ej. +525512345678).
• lead_id — identificador único del contacto de tu lado (te sirve para cruzar resultados).
• client_name — nombre del contacto.
• debt / position — según el tipo (monto de deuda; puesto a entrevistar).

Las columnas extra que agregues (por ejemplo Fecha_Limite_Pago) se preservan y se pasan al motor de llamadas. Las filas sin to_number o sin lead_id se saltan.

Si quieres un punto de partida, descarga la plantilla oficial del tipo que vas a usar:

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

Ejemplo de CSV (cobranza):

to_number,lead_id,client_name,debt
+525512345678,L001,Juan Pérez,5000.00
+525598765432,L002,María García,3500.50

En esta receta vamos a enviar el CSV inline (como texto dentro del JSON). Si tu archivo es grande o lo exportas directo de Excel, mira la Receta 4 — Carga por archivo CSV.

Paso 5 — Lanzar la campaña¶

Con el agent_id (Paso 3) y el CSV (Paso 4), lanza la campaña con POST /api/campaign/start. El CSV va en el campo csv_content como texto plano (con saltos de línea \n), no base64 ni ruta de archivo.

curl -s -X POST "$API_BASE_URL/api/campaign/start" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cobranza Enero",
    "csv_content": "to_number,lead_id,client_name,debt\n+525512345678,L001,Juan Pérez,5000.00\n+525598765432,L002,María García,3500.50",
    "agent_id": "agent_abc123",
    "campaign_type": "collections",
    "customer_email": "ops@tuempresa.com"
  }'

Respuesta (200):

{
  "success": true,
  "campaign_id": 123,
  "total_leads": 2,
  "agent_id": "agent_abc123",
  "campaign_type": "collections",
  "message": "Campaign 'Cobranza Enero' started"
}

Guarda el campaign_id (123 en el ejemplo): lo vas a usar para monitorear y para filtrar los resultados.

A partir de este punto, las llamadas ya están saliendo. Solo puede haber una campaña activa por organización a la vez: si ya tienes una corriendo, recibirás 409. Puedes pause / resume / stop la campaña en cualquier momento (todos requieren scope full).

Paso 6 — Monitorear el estado¶

Mientras la campaña corre, consulta su avance en tiempo real con GET /api/campaign/status:

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

Respuesta:

{
  "success": true,
  "status": { "state": "running", "campaign_id": 123, "active_calls": 2, "queue_size": 0 },
  "campaign": { "id": 123, "name": "Cobranza Enero", "total_leads": 2, "leads_called": 0 },
  "global_status": { }
}

• state: running (en ejecución) o idle (sin campaña activa).
• active_calls: llamadas en curso ahora mismo.
• queue_size: contactos pendientes en la cola.

Cuando active_calls llega a 0 y queue_size es 0, ya se llamó a todos los contactos. Conviene esperar un poco más antes de leer resultados: el análisis de cada llamada (resumen, sentimiento, resultado) se procesa al terminar la llamada, así que puede tardar unos segundos en estar disponible.

Ejemplo de loop simple de monitoreo:

while true; do
  STATE=$(curl -s "$API_BASE_URL/api/campaign/status" \
    -H "X-API-Key: $API_KEY" | jq -r '.status.state')
  ACTIVE=$(curl -s "$API_BASE_URL/api/campaign/status" \
    -H "X-API-Key: $API_KEY" | jq -r '.status.active_calls')
  echo "estado=$STATE activas=$ACTIVE"
  [ "$STATE" = "idle" ] && break
  sleep 30
done

Paso 7 — Obtener los resultados (polling)¶

Los resultados se obtienen consultando los endpoints de analytics (polling). Filtra por el campaign_id de tu campaña:

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

Respuesta:

{
  "success": true,
  "calls": [
    {
      "call_id": "call_abc",
      "campaign_id": 123,
      "client_name": "Juan Pérez",
      "lead_id": "L001",
      "to_number": "+525512345678",
      "call_duration": 42,
      "call_status": "completed",
      "call_outcome": "promised_payment",
      "sentiment": "positive",
      "payment_promised": true,
      "payment_amount": "5000.00",
      "payment_date": "2026-02-20",
      "summary": "El cliente se comprometió a pagar el monto completo.",
      "start_timestamp": "2026-02-10T10:15:00Z"
    }
  ],
  "pagination": { "limit": 100, "count": 1, "has_more": false, "next_cursor": null }
}

Si has_more es true, hay más resultados: repite el request pasando cursor=<next_cursor> hasta que has_more sea false. El detalle de la paginación por cursor está en la Receta 3 — Sincronizar resultados.

Detalle completo de una llamada¶

Para ver la transcripción completa, la grabación y el análisis extendido de una llamada, usa su call_id:

curl -s "$API_BASE_URL/api/analytics/call/call_abc" \
  -H "X-API-Key: $API_KEY"

Respuesta (resumida):

{
  "success": true,
  "call": { "call_id": "call_abc", "transcript": "...", "recording_url": "..." },
  "analysis": {
    "call_outcome": "promised_payment",
    "sentiment": "positive",
    "payment_promised": true,
    "payment_amount": "5000.00",
    "payment_date": "2026-02-20",
    "summary": "El cliente se comprometió a pagar el monto completo el 20 de febrero.",
    "customer_objections": [],
    "follow_up_needed": true,
    "analyzed_at": "2026-02-10T10:16:30Z"
  }
}

Estadísticas agregadas¶

Para un resumen de toda la operación (totales, sentimiento, promesas de pago), usa GET /api/analytics/stats:

curl -s "$API_BASE_URL/api/analytics/stats" \
  -H "X-API-Key: $API_KEY"

Resumen del flujo¶

1. API Key (X-API-Key)
        │
2. Verificar auth ──► GET /api/campaigns
        │
3. Elegir agent  ──► GET /api/agents            → agent_id
        │
4. Armar CSV     ──► GET /api/csv-template?type=…  (opcional)
        │
5. Lanzar        ──► POST /api/campaign/start    → campaign_id   ⚠️ llamadas reales
        │
6. Monitorear    ──► GET /api/campaign/status    (loop hasta idle)
        │
7. Resultados    ──► GET /api/analytics/calls?campaign_ids=…  (polling + cursor)
                     GET /api/analytics/call/{call_id}        (detalle)
                     GET /api/analytics/stats                 (agregados)

Próximos pasos¶

• Antes de tu primera campaña real a tu base completa: Receta 2 — Probar sin impacto.
• Para mantener tu sistema sincronizado de forma continua: Receta 3 — Sincronizar resultados.
• Para subir el CSV como archivo en lugar de inline: Receta 4 — Carga por archivo CSV.
• Si algo falla: revisa Errores y troubleshooting.