Preguntas frecuentes (FAQ)¶

⚠️ BORRADOR — validar/expandir con preguntas reales de soporte.

Estas preguntas se derivaron de la documentación de la API y del material de habilitación. Cuando lleguen las primeras consultas reales de clientes que integran la API, hay que revisar las respuestas, ajustar el wording y agregar los casos que falten.

Esta página responde las dudas más comunes de quienes integran la API de campañas de llamadas con AI. Todos los ejemplos usan la URL base de Producción:

https://api.neuronstudio.ai

Si tu pregunta no está aquí, contacta a tu equipo de soporte.

Autenticación y acceso¶

1. ¿Cómo obtengo una API Key?¶

La emisión de API Keys no es self-serve: no se generan desde el panel. Las crea un administrador de tu organización (con verificación en dos pasos) y la key se muestra una sola vez al momento de crearse, así que guárdala en un lugar seguro apenas la recibas.

Para obtener la tuya, solicítala a tu contacto de Neuron o al administrador de tu organización. Si la pierdes, hay que emitir una nueva (no se puede recuperar la anterior).

Una vez que la tienes, se envía en cada request como header:

X-API-Key: nrn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. ¿Cuál es la diferencia entre una key con scope read y una con scope full?¶

Si usas una key con scope read para un POST, PATCH o DELETE, la API responde 403 Forbidden. Para operar campañas (no solo consultarlas) necesitas una key full.

3. ¿Por qué mi POST devuelve 403 si la autenticación es correcta?¶

Un 403 con credenciales válidas casi siempre significa una de dos cosas:

1. Tu API Key tiene scope read y estás intentando una operación de escritura (start/stop/pause/resume/schedule). Necesitas una key con scope full.
2. El agent_id que enviaste no está asignado a tu organización. Cada key solo puede usar agents de su propia organización. Verifica el agent_id contra GET /api/agents.

Si descartaste ambas, el body del error trae un error_id que puedes citar al pedir soporte.

4. ¿Puedo usar el login con usuario y contraseña (JWT) en vez de la API Key?¶

POST /api/auth/login existe y devuelve un access_token para sesiones de navegador. Para integraciones servidor-a-servidor recomendamos la API Key, no el JWT: la key es estable, no expira por sesión y está pensada para automatización. El JWT está orientado a la interfaz web.

5. ¿La organización va en algún header (tipo X-Tenant-ID)?¶

No. La organización va implícita en la API Key. No existe header de organización ni de tenant: cada key solo ve y opera datos de su propia organización.

Campañas y formato de datos¶

6. ¿Qué formato tiene que tener el CSV?¶

Las columnas requeridas dependen del tipo de campaña (campaign_type):

Reglas generales:

• to_number: teléfono en formato E.164 (ver pregunta 13).
• lead_id: identificador único por contacto.
• Las columnas extra que agregues (por ejemplo Fecha_Limite_Pago) se preservan y se pasan al motor de llamadas.
• Tamaño máximo del archivo: 10 MB.
• Las filas sin to_number o sin lead_id se saltan automáticamente.

Puedes descargar una plantilla lista para usar con GET /api/csv-template?type=<tipo>.

7. ¿Cómo inicio una campaña? ¿Mando el CSV como texto o como archivo?¶

Hay dos formas, equivalentes en comportamiento:

• CSV inline (JSON): POST /api/campaign/start con el CSV como texto plano en el campo csv_content.

API_BASE_URL="https://api.neuronstudio.ai"
curl -X POST "$API_BASE_URL/api/campaign/start" \
  -H "X-API-Key: nrn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cobranza Enero",
    "csv_content": "to_number,lead_id,client_name,debt\n+525512345678,L001,Juan,5000",
    "campaign_type": "collections"
  }'

• Archivo CSV (multipart): POST /api/campaign/start-upload con el .csv como archivo en un multipart/form-data (campos file y name, más los opcionales agent_id, campaign_type, customer_email).

Ambas devuelven la misma respuesta con el campaign_id y el total de leads cargados.

8. ¿Qué pasa si lanzo dos campañas al mismo tiempo?¶

Solo puede haber una campaña activa por organización. Si intentas iniciar una segunda mientras hay una corriendo, la API responde 409 Conflict (límite de campañas alcanzado).

Si necesitas encadenar trabajo, primero detén (stop) o espera a que termine la campaña activa, o programa la siguiente con POST /api/campaign/schedule para que arranque más tarde.

9. ¿Puedo crear agents desde la API?¶

No. La API pública no permite crear ni modificar agents. Con GET /api/agents puedes listar los agents asignados a tu organización y copiar el agent_id que quieras usar al iniciar una campaña. La creación y asignación de agents se coordina con tu contacto de Neuron.

Resultados, polling y webhooks¶

10. ¿Cómo obtengo los resultados de las llamadas?¶

Por polling (consulta periódica), no por push. El flujo recomendado:

1. Llama a GET /api/analytics/calls para traer la lista de llamadas con su resultado, sentimiento y datos de pago.
2. Para el detalle completo de una llamada (transcript + análisis), usa GET /api/analytics/call/{call_id}.
3. Para métricas agregadas (totales, tasas, breakdowns), usa GET /api/analytics/stats.

Patrón sugerido: consulta cada N minutos, filtrando por from_date/to_date o por campaign_ids para traer solo lo nuevo, y pagina con el cursor (ver pregunta 12).

11. ¿Hay webhooks? ¿Pueden empujar los resultados a mi sistema?¶

Hoy no hay webhooks salientes hacia el cliente: no existe forma de registrar una URL para recibir eventos push vía la API pública. La entrega por webhooks (push) está en desarrollo; por ahora la sincronización es por consulta (polling), con GET /api/analytics/calls (ver pregunta 10).

12. ¿Cómo pagino la lista de llamadas?¶

GET /api/analytics/calls usa paginación por cursor (no por offset):

1. Haz el primer request, opcionalmente con limit (default 100, máximo 100).
2. En la respuesta, el bloque pagination trae has_more y next_cursor.
3. Mientras has_more sea true, repite el request pasando cursor=<next_cursor>.
4. Cuando has_more sea false (y next_cursor sea null), llegaste al final.

API_BASE_URL="https://api.neuronstudio.ai"
# Primera página
curl "$API_BASE_URL/api/analytics/calls?limit=100" -H "X-API-Key: $KEY"
# Página siguiente
curl "$API_BASE_URL/api/analytics/calls?limit=100&cursor=<next_cursor>" -H "X-API-Key: $KEY"

Pruebas, límites y errores¶

13. ¿En qué formato tiene que ir el teléfono?¶

En formato E.164: el signo +, el código de país y el número, sin espacios ni guiones ni paréntesis. Ejemplos:

• México: +525512345678
• Estados Unidos: +14155552671

Las filas con un to_number mal formado o vacío se saltan al cargar la campaña.

14. ¿Hay un modo sandbox o de prueba para no disparar llamadas reales?¶

No existe un modo sandbox ni un flag de dry-run. Un start exitoso dispara llamadas reales de inmediato.

Para probar de forma segura sin impacto, la práctica recomendada es:

1. Arma una lista de un solo contacto con tu propio número.
2. Usa una lista chica y, si puedes, fuera del horario productivo.
3. Lanza la campaña y valida el flujo completo (la llamada, el resultado, el polling) con esa única llamada controlada.

Así verificas la integración punta a punta sin contactar a clientes reales.

15. ¿Qué límites de rate (rate limits) tiene la API?¶

Algunos endpoints tienen límite de frecuencia. Los principales:

Cuando excedes un límite, la API responde 429 e incluye el header Retry-After con los segundos que tienes que esperar antes de reintentar. No existen headers tipo X-RateLimit-*: el cliente infiere el límite a partir del 429 y del Retry-After. Implementa backoff respetando ese valor.

16. ¿Qué significan los campos call_outcome y sentiment?¶

Son parte del análisis con AI de cada llamada:

• call_outcome: el resultado categorizado de la conversación (por ejemplo promised_payment, no_answer, refused, etc.). Sirve para clasificar qué pasó en la llamada.
• sentiment: el sentimiento general detectado, normalmente positive, negative o neutral.

Ambos vienen en cada llamada de GET /api/analytics/calls y, con más detalle (junto al resumen, las objeciones del cliente y los datos de pago), en GET /api/analytics/call/{call_id}. Puedes filtrar las consultas por call_outcome y sentiment.

17. Recibe un error con un error_id. ¿Qué hago con eso?¶

Todos los errores devuelven un body con esta forma:

{
  "success": false,
  "error": "<mensaje genérico>",
  "error_id": "<uuid>",
  "request_id": "<uuid>"
}

El error_id (y el request_id) identifican de forma única ese error en nuestros registros. Cuando pidas soporte por un error, incluye el error_id: nos permite encontrar exactamente qué pasó sin que tengas que reproducir el problema.

Códigos de error más comunes: