Receta 4 — Carga por archivo CSV (upload)¶

Lo que vas a lograr: lanzar una campaña subiendo un archivo .csv directamente (multipart) con POST /api/campaign/start-upload, en lugar de pegar el CSV como texto dentro del JSON. Útil cuando tu lista es grande, la exportas directo de Excel, o tu pipeline genera un archivo en disco.

start (CSV inline) vs. start-upload (archivo) — ¿cuál uso?¶

Ambos lanzan una campaña real de inmediato; la validación, la selección de agent y el comportamiento de marcado son idénticos. La única diferencia es cómo le pasas el CSV.

Regla práctica: si ya tienes el CSV como archivo, usa start-upload — te evita escapar saltos de línea y comillas dentro del JSON. Si armas la lista en memoria desde tu código, start con csv_content suele ser más directo.

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

Prerrequisitos¶

• API Key con scope full.
• Un archivo .csv válido (ver columnas requeridas abajo). Máximo 10 MB.

Paso 1 — Preparar el archivo CSV¶

Las columnas requeridas dependen del campaign_type (igual que en start):

• to_number en formato E.164 (+525512345678).
• lead_id único por contacto.
• Las columnas extra (ej. 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 la plantilla exacta de un tipo:

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

Ejemplo de leads.csv (cobranza):

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

Export de Excel: puedes subir el archivo tal como lo exporta Excel. El sistema lo decodifica como UTF-8 y maneja automáticamente el marcador inicial (BOM) de los exports "CSV UTF-8" de Excel, con un fallback para exports más antiguos. No necesitas convertirlo a mano.

Paso 2 — Subir el archivo y lanzar la campaña¶

POST /api/campaign/start-upload espera multipart/form-data. Con curl, cada campo va con -F; el archivo se adjunta con -F "file=@ruta":

curl -s -X POST "$API_BASE_URL/api/campaign/start-upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@leads.csv" \
  -F "name=Cobranza Enero" \
  -F "agent_id=agent_abc123" \
  -F "campaign_type=collections" \
  -F "customer_email=ops@tuempresa.com"

Respuesta (200) — idéntica a la de start:

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

⚠️ Igual que start, esto dispara llamadas reales de inmediato. Si es tu primera vez, valida antes con la Receta 2 — Probar sin impacto.

Ejemplo en Python¶

import requests

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

headers = {"X-API-Key": API_KEY}

with open("leads.csv", "rb") as f:
    resp = requests.post(
        f"{API_BASE_URL}/api/campaign/start-upload",
        headers=headers,
        files={"file": ("leads.csv", f, "text/csv")},
        data={
            "name": "Cobranza Enero",
            "agent_id": "agent_abc123",
            "campaign_type": "collections",
        },
    )

print(resp.json())

Paso 3 — Continuar el flujo normal¶

A partir del campaign_id que devuelve el upload, el resto del flujo es idéntico al de la Receta 1:

• Monitorear: GET /api/campaign/status.
• Obtener resultados (polling): GET /api/analytics/calls?campaign_ids=789 — ver Receta 3 para el loop con cursor.
• Detalle de una llamada: GET /api/analytics/call/{call_id}.

Errores comunes¶

Todos los errores devuelven un cuerpo con error_id y request_id. Si necesitas soporte, cita esos dos valores para que tu equipo de Neuron correlacione el caso.

Resumen¶

1. Preparar leads.csv  (columnas según campaign_type; máx 10 MB)
        │
2. POST /api/campaign/start-upload   (multipart: file + name + agent_id + campaign_type)
        │                             → campaign_id   ⚠️ llamadas reales
        │
3. Flujo normal  ──► status → analytics/calls (polling + cursor) → analytics/call/{id}

Si prefieres pasar el CSV como texto en lugar de archivo, mira POST /api/campaign/start en la Receta 1 — Primera integración.