Receta 2 — Probar sin impacto¶

Lo que vas a lograr: validar tu integración end-to-end —autenticación, formato del CSV, selección de agent, lanzamiento, monitoreo y lectura de resultados— sin llamar a tu base real de contactos. Lo logras ejecutando el flujo completo con una única llamada real a tu propio número de teléfono.

⚠️ Lo primero que tienes que saber: no existe un modo de prueba¶

Esta API no tiene un modo dry-run, ni sandbox, ni un flag de "simulación". No hay un endpoint ni un parámetro que dispare llamadas falsas.

Un POST /api/campaign/start exitoso dispara llamadas telefónicas reales de inmediato. Cada fila válida de tu CSV se convierte en una llamada saliente real apenas la campaña arranca.

Esto significa que no puedes "probar" lanzando tu CSV completo a ver qué pasa. Si lo haces, estás llamando de verdad a todos tus contactos. La forma correcta de probar es la disciplina segura que describe esta receta: una lista mínima, con tu propio número, fuera de horario productivo.

La disciplina segura¶

Cuatro reglas, en orden de importancia:

Un solo contacto, y que sea TU PROPIO número. El CSV tiene exactamente una fila, con un número de teléfono que tú controlas (tu celular, una línea de prueba interna). Así la única llamada real que se genera te llega a ti.
Fuera de horario productivo. Corre la prueba en un momento en que, si algo sale distinto a lo esperado, no interfiera con tu operación real.
Valida el flujo completo con esa única llamada. Autenticar → listar agents → lanzar → monitorear → leer el resultado. Si los siete pasos funcionan con un contacto, funcionan con mil.
Revisa el resultado en el detalle de la llamada (GET /api/analytics/call/{call_id}) antes de confiar en el pipeline a escala.

Prerrequisitos¶

API Key con scope full (igual que en la Receta 1).
Un número de teléfono propio, en formato E.164, donde puedas atender la llamada.

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

Paso 1 — Elegir el agent (igual que en producción)¶

Prueba con el mismo agent que vas a usar en la campaña real, para validar también su comportamiento:

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

Anota el agent_id.

Paso 2 — Armar un CSV de UN solo contacto: tu número¶

El CSV de prueba tiene una sola fila de datos, y el to_number es tu propio teléfono. Las columnas son las del campaign_type que vas a usar en producción (ver tabla en la Receta 1, Paso 4).

Ejemplo para una campaña de cobranza (collections), usando tu número:

to_number,lead_id,client_name,debt
+525500000000,TEST001,Prueba Interna,1.00

Reemplaza +525500000000 por tu número real en formato E.164. El debt puede ser un monto simbólico — el objetivo es validar el flujo, no el contenido.

Paso 3 — Lanzar la campaña de prueba (fuera de horario productivo)¶

Elige un momento tranquilo y lanza. Esto genera una llamada real a tu número en cuanto responda el 200:

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

Respuesta (200):

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

Tu teléfono debería sonar en unos segundos. Atiende la llamada y conversa con el agent para validar su comportamiento de punta a punta. Guarda el campaign_id (456 en el ejemplo).

Si necesitas cortar la prueba antes de tiempo, puedes detener la campaña:

curl -s -X POST "$API_BASE_URL/api/campaign/stop" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": 456 }'

Paso 4 — Monitorear hasta que termine¶

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

Espera a que state vuelva a idle y active_calls sea 0. Como hay un solo contacto, esto ocurre apenas termina tu llamada.

Paso 5 — Revisar el resultado de la llamada¶

Lista las llamadas de la campaña de prueba para obtener el call_id:

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

Toma el call_id de la única llamada y pide su detalle completo —aquí validas que la transcripción, el sentimiento y el análisis se generaron correctamente:

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": "...",
    "sentiment": "...",
    "summary": "...",
    "analyzed_at": "2026-02-10T10:16:30Z"
  }
}

Si todo esto se ve correcto —la llamada salió, la atendiste, y el análisis aparece— tu integración está validada de punta a punta.

Checklist de validación¶

Antes de lanzar a tu base completa, confirma que con la prueba de un contacto verificaste:

[ ] La autenticación funciona (X-API-Key aceptada, sin 401/403).
[ ] GET /api/agents devuelve el agent esperado.
[ ] El CSV se aceptó sin error de validación (sin 400).
[ ] POST /api/campaign/start devolvió 200 y un campaign_id.
[ ] La llamada real llegó a tu número y el agent se comportó como esperabas.
[ ] GET /api/campaign/status reflejó el avance y volvió a idle.
[ ] GET /api/analytics/call/{call_id} devolvió transcripción y análisis.

Con eso puedes escalar al CSV completo con confianza. El flujo es idéntico al de la Receta 1: la única diferencia es el tamaño del CSV.

Por qué esta es la forma correcta¶

No inventamos un modo de prueba porque no existe: cualquier start mueve teléfonos reales. La forma de "probar sin impacto" no es engañar al sistema, sino acotar el impacto a un único número que tú controlas. Una lista de un contacto, tu propio número, fuera de horario productivo, te da exactamente la misma cobertura de validación que un sandbox — sin riesgo sobre tu base real.