Vista General de la API

La API de CallCov está organizada alrededor de principios REST. Usa URLs predecibles orientadas a recursos, acepta cuerpos de solicitud codificados en JSON, devuelve respuestas codificadas en JSON y usa códigos de respuesta HTTP estándar y autenticación.

URL Base

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

Autenticación

La API de CallCov usa claves API o tokens JWT para autenticar solicitudes. Incluye tu clave en el encabezado Authorization:

Authorization: Bearer sk_live_abc123...

Aprende más en la Guía de Autenticación.

Formato de Solicitud

Todas las solicitudes POST, PUT y PATCH deben incluir un encabezado Content-Type:

Content-Type: application/json

Para subida de archivos, usa:

Content-Type: multipart/form-data

Formato de Respuesta

Todas las respuestas se devuelven en formato JSON con una estructura consistente:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "analysis",
  "created": 1642248000,
  ...
}

Códigos de Estado HTTP

CallCov usa códigos de respuesta HTTP convencionales:

Código	Significado	Descripción
200	OK	La solicitud fue exitosa
201	Creado	El recurso se creó exitosamente
400	Solicitud Incorrecta	Parámetros de solicitud inválidos
401	No Autorizado	Autenticación inválida o faltante
403	Prohibido	Permisos insuficientes
404	No Encontrado	El recurso no existe
422	Entidad No Procesable	Error de validación
429	Demasiadas Solicitudes	Límite de tasa excedido
500	Error Interno del Servidor	Error de servidor (contacta soporte)

Manejo de Errores

Los errores incluyen información detallada:

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

Aprende más en la Guía de Manejo de Errores.

Versionado

La versión de la API está incluida en la ruta de la URL:

/api/v1/analysis/

Mantendremos compatibilidad hacia atrás dentro de versiones principales. Cambios que rompan compatibilidad resultarán en una nueva versión (ej., /api/v2/).

Límites de Tasa

Los límites de tasa protegen nuestra infraestructura y aseguran uso justo:

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

Los encabezados de límite de tasa se incluyen en todas las respuestas:

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

Paginación

Los endpoints de lista soportan paginación:

GET /api/v1/analysis/?skip=0&limit=20

Parámetros:

• skip: Número de registros a saltar (por defecto: 0)
• limit: Número máximo de registros a devolver (por defecto: 20, máx: 100)

Respuesta:

{
  "items": [...],
  "total": 150,
  "skip": 0,
  "limit": 20
}

Timestamps

Todos los timestamps son timestamps Unix (segundos desde epoch):

{
  "created": 1642248000  // 15 de enero de 2022 10:00:00 UTC
}

Convierte en tu lenguaje de preferencia:

# Python
from datetime import datetime
dt = datetime.fromtimestamp(1642248000)

// JavaScript
const date = new Date(1642248000 * 1000);

Idempotencia

Para reintentar solicitudes de manera segura sin realizar la misma operación dos veces, incluye un encabezado Idempotency-Key:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Las claves de idempotencia son válidas por 24 horas.

Metadata

Muchos recursos aceptan metadata personalizada:

{
  "audio_url": "https://ejemplo.com/llamada.wav",
  "metadata": {
    "campaign_id": "verano_2024",
    "department": "ventas"
  }
}

La metadata se devuelve sin cambios y puede usarse para tus propios propósitos de rastreo.

Webhooks

Para operaciones de larga duración como análisis, usa webhooks en lugar de polling:

{
  "audio_url": "https://ejemplo.com/llamada.wav",
  "webhook_url": "https://tu-app.com/webhooks/analysis"
}

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

Modo Prueba vs Modo Producción

Usa modo prueba para experimentar sin afectar datos de producción:

• Claves API de Prueba: sk_test_...
• Claves API de Producción: sk_live_...

El modo prueba usa la misma URL base pero no procesa cargos reales ni envía notificaciones reales.

Endpoints de la API

Autenticación

• POST /auth/register - Crear cuenta
• POST /auth/login - Obtener token de acceso
• POST /auth/refresh - Refrescar token de acceso
• POST /auth/verify-email - Verificar dirección de email
• POST /auth/password-reset - Solicitar restablecimiento de contraseña
• POST /auth/password-reset/confirm - Confirmar restablecimiento de contraseña

Gestión de Usuarios

• GET /users/me - Obtener usuario actual
• PUT /users/me - Actualizar usuario actual
• DELETE /users/me - Eliminar cuenta

Claves API

• POST /api-keys/ - Crear clave API
• GET /api-keys/ - Listar claves API
• DELETE /api-keys/{id} - Revocar clave API

Análisis (Principal)

• POST /analysis/ - Enviar análisis
• GET /analysis/{id} - Obtener análisis
• GET /analysis/ - Listar análisis
• POST /analysis/{id}/webhook - Registrar webhook

Facturación

• GET /billing/subscription - Obtener suscripción
• POST /billing/subscription - Crear suscripción
• POST /billing/subscription/update - Actualizar plan
• POST /billing/subscription/cancel - Cancelar suscripción
• GET /billing/usage - Obtener resumen de uso
• GET /billing/history - Obtener historial de uso
• GET /billing/customer-portal - Portal de cliente Stripe

SDKs

Los SDKs oficiales estarán disponibles pronto para:

• Python
• Node.js
• Ruby
• PHP

Mientras tanto, la API funciona genial con librerías HTTP estándar como requests (Python) o axios (Node.js).

Soporte

• Documentación: https://docs.callcov.com
• Email: support@callcov.com
• Estado: status.callcov.com