Saltar al contenido principal

Haciendo Tu Primera Solicitud

Esta guía te lleva paso a paso para hacer tu primera solicitud API a CallCov, desde la autenticación hasta recibir los resultados de tu análisis.

Antes de Empezar​

Asegúrate de tener:

  • ✅ Creada una cuenta de CallCov
  • ✅ Verificado tu email
  • ✅ Obtenido una clave API o token de acceso
  • ✅ Un archivo de grabación de llamada de muestra

Si no has completado estos pasos, ve a la Guía de Inicio Rápido.

URL Base​

Todas las solicitudes API se hacen a:

https://api.callcov.com/api/v1

Formato de Solicitud​

CallCov usa principios de API RESTful:

  • Protocolo: Solo HTTPS
  • Formato: JSON para cuerpos de solicitud/respuesta
  • Autenticación: Token Bearer en encabezado Authorization
  • Content-Type: application/json (o multipart/form-data para subida de archivos)

Ejemplo: Enviar un Análisis​

Analicemos una grabación de llamada paso a paso.

Ejemplo cURL​

curl -X POST https://api.callcov.com/api/v1/analysis/ \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://ejemplo.com/grabaciones/llamada-001.wav",
    "agent_id": "agente_juan_perez",
    "contact_id": "cliente_12345",
    "webhook_url": "https://tu-app.com/webhooks/analysis"
  }'

Ejemplo Python​

import requests

# Tus credenciales API
API_KEY = "sk_live_abc123..."
BASE_URL = "https://api.callcov.com/api/v1"

# Preparar la solicitud
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "audio_url": "https://ejemplo.com/grabaciones/llamada-001.wav",
    "agent_id": "agente_juan_perez",
    "contact_id": "cliente_12345",
    "webhook_url": "https://tu-app.com/webhooks/analysis"
}

# Hacer la solicitud
response = requests.post(
    f"{BASE_URL}/analysis/",
    headers=headers,
    json=payload
)

# Manejar la respuesta
if response.status_code == 201:
    analysis = response.json()
    print(f"✅ Análisis creado: {analysis['id']}")
    print(f"Estado: {analysis['status']}")
else:
    print(f"❌ Error: {response.status_code}")
    print(response.json())

Ejemplo Node.js​

const axios = require('axios');

const API_KEY = 'sk_live_abc123...';
const BASE_URL = 'https://api.callcov.com/api/v1';

async function submitAnalysis() {
  try {
    const response = await axios.post(
      `${BASE_URL}/analysis/`,
      {
        audio_url: 'https://ejemplo.com/grabaciones/llamada-001.wav',
        agent_id: 'agente_juan_perez',
        contact_id: 'cliente_12345',
        webhook_url: 'https://tu-app.com/webhooks/analysis'
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('✅ Análisis creado:', response.data.id);
    console.log('Estado:', response.data.status);
  } catch (error) {
    console.error('❌ Error:', error.response.status);
    console.error(error.response.data);
  }
}

submitAnalysis();

Estructura de Respuesta​

Respuesta Exitosa (201 Created)​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1642248000,
  "status": "processing",
  "livemode": true,
  "call": {
    "agent_id": "agente_juan_perez",
    "contact_id": "cliente_12345"
  },
  "audio": {
    "url": "https://s3.amazonaws.com/callcov/...",
    "duration_seconds": null,
    "format": "wav",
    "file_size": null
  },
  "transcript": null,
  "results": null,
  "metadata": {
    "processing_time_ms": null,
    "version": "1.0.0"
  }
}

Respuesta de Error (400 Bad Request)​

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "audio_url"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Verificando el Estado del Análisis​

Los análisis se procesan de manera asíncrona. Verifica el estado con:

curl -X GET https://api.callcov.com/api/v1/analysis/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_abc123..."

Valores de Estado​

EstadoDescripción
processingEl análisis está en progreso
completedEl análisis terminó exitosamente
failedEl análisis encontró un error

Polling para Resultados​

import time
import requests

def wait_for_analysis(analysis_id, api_key, max_wait=300):
    """Hacer polling hasta que complete el análisis (máx 5 minutos)"""
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.callcov.com/api/v1/analysis/{analysis_id}"

    start_time = time.time()
    while time.time() - start_time < max_wait:
        response = requests.get(url, headers=headers)
        analysis = response.json()

        if analysis['status'] == 'completed':
            print("✅ ¡Análisis completo!")
            return analysis
        elif analysis['status'] == 'failed':
            print("❌ Análisis falló:", analysis.get('error_message'))
            return None

        print(f"⏳ Estado: {analysis['status']}... esperando")
        time.sleep(10)  # Hacer polling cada 10 segundos

    print("⏱️ Tiempo de espera agotado")
    return None

# Uso
analysis_id = "550e8400-e29b-41d4-a716-446655440000"
result = wait_for_analysis(analysis_id, "sk_live_abc123...")

Usando Webhooks (Recomendado)​

En lugar de hacer polling, usa webhooks para notificaciones en tiempo real:

# Al crear el análisis, incluye webhook_url
payload = {
    "audio_url": "https://ejemplo.com/grabaciones/llamada-001.wav",
    "agent_id": "agente_juan_perez",
    "contact_id": "cliente_12345",
    "webhook_url": "https://tu-app.com/webhooks/analysis"  # ← Tu endpoint webhook
}

Tu webhook recibirá:

{
  "event": "analysis.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "results": { ... }
  }
}

Aprende más en la Guía de Webhooks.

Problemas Comunes​

401 No Autorizado​

{"detail": "Credenciales de autenticación inválidas"}

Solución: Verifica que tu clave API sea correcta y esté incluida en el encabezado Authorization.

400 Solicitud Incorrecta​

{"detail": "audio_url es requerido"}

Solución: Asegúrate de que todos los campos requeridos estén incluidos en tu solicitud.

422 Entidad No Procesable​

{"detail": "Formato de archivo de audio inválido"}

Solución: Verifica que tu archivo de audio esté en un formato soportado (WAV, MP3, etc.).

Límites de Tasa​

CallCov aplica límites de tasa para asegurar calidad de servicio:

  • Por defecto: 100 solicitudes por minuto
  • Envíos de análisis: 20 por minuto

La información de límite de tasa se incluye en los encabezados de respuesta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248060

Próximos Pasos​

Ahora que has hecho tu primera solicitud, explora: