API pública

Documentación de la API Call Trace

Envíe grabaciones de llamadas desde su sistema, reciba una respuesta 202 inmediata y obtenga la transcripción y evaluación finales mediante webhooks.

Cree una clave API

Abra Admin > Integraciones y cree una clave con el alcance analysis:write.

Envíe una URL de archivo

Envíe un fileUrl HTTPS a POST /api/v1/analyses. La API responde con 202 Accepted.

Reciba el resultado

Suscríbase a analysis.completed y analysis.failed para obtener la evaluación final.

Verifique el secret

Compare X-CallTrace-Secret con el webhook secret guardado al crear el endpoint.

Claves API

Cree un token en el panel de administración

Solo los administradores pueden crear claves API de integración. Las claves tienen alcances, pueden expirar, revocarse y son independientes de las sesiones de empleados.

01
Abra Integraciones
Inicie sesión como administrador y abra Admin > Integraciones > API Keys.
02
Nombre la clave
Use un nombre que identifique el sistema externo, entorno y responsable.
03
Elija los alcances
Seleccione solo los permisos que el sistema necesita. La mayoría de integraciones de carga necesitan analysis:write y analysis:read.
04
Defina la vigencia
Elija una fecha de expiración para acceso temporal o déjela permanente para integraciones de servicio de larga duración.
05
Copie una vez
El token ct_live_ completo se muestra solo una vez. Tras cerrar el panel, solo permanece visible el prefijo.
ct_live_••••••••

Formato del token

ct_live_8Lk3...full-secret-value

Guarde el token completo en el gestor de secretos de su sistema externo. Call Trace almacena solo un hash y muestra únicamente el prefijo tras la creación.

Autenticación

Use una clave de integración con alcances

Las claves API de integración están separadas de las sesiones de empleados. Envíe la clave en el encabezado Authorization y conceda solo los alcances que su sistema necesita.

Encabezado

Authorization: Bearer ct_live_...
Content-Type: application/json

Alcances

analysis:write crea análisis.

analysis:read lee estado y resultados.

webhooks:write gestiona la configuración de webhooks.

Permisos

Qué permite cada alcance

Los alcances son acumulativos. Comience con el conjunto mínimo que soporta la integración y añada más solo cuando un endpoint específico lo requiera.

Alcance

Uso

Descripción

analysis:write

Crear nuevos análisis

Requerido para POST /api/v1/analyses. Permite que el sistema externo envíe un fileUrl y encole el análisis.

analysis:read

Leer estado y resultado del análisis

Requerido para GET /api/v1/analyses y GET /api/v1/analyses/{analysisId}. Úselo para polling y reconciliación.

calls:read

Leer datos a nivel de llamada

Permite acceso a metadatos de llamadas expuestos por endpoints seguros para integración. No lo conceda si la integración solo envía archivos.

storage:write

Escribir archivos de origen

Reservado para integraciones que necesitan flujos de carga directa al almacenamiento. Las integraciones fileUrl normalmente no lo necesitan.

webhooks:read

Leer configuración e historial de webhooks

Permite listar endpoints de webhook e intentos de entrega para soporte o monitorización.

webhooks:write

Gestionar webhooks

Permite crear o actualizar endpoints de webhook. Manténgalo en claves admin/servicio, no en claves comunes de envío de análisis.

Mínimo recomendado

Para el flujo estándar, cree un token con analysis:write y analysis:read. Los webhooks los configura un admin en la UI, por lo que el remitente externo normalmente no necesita webhooks:write.

Vida útil del token

Expiración, acceso permanente y rotación

Cada clave API tiene su propia vigencia. Un token puede ser permanente, expirar automáticamente o revocarse manualmente.

Token permanente

expiresAt está vacío. El token permanece activo hasta que un admin lo revoque. Úselo solo para integraciones backend-to-backend de confianza con proceso de rotación.

Token con expiración

expiresAt está definido. Tras esa fecha la API devuelve 401 y no se aceptan nuevas solicitudes. Úselo para pruebas, contratistas o acceso temporal.

Token revocado

revokedAt se establece de inmediato cuando un admin revoca la clave. La revocación es instantánea e irreversible; cree una clave nueva.

Rotación

Cree una clave nueva, desplieguela en el sistema externo, confirme que last used se actualizó y luego revoque la clave antigua. Esto evita tiempo de inactividad.

Referencia de la API

Crear un análisis

La solicitud almacena el archivo de origen e inicia el procesamiento en segundo plano. Su cliente no debe esperar a que termine la transcripción o evaluación en esta solicitud.

Crear análisis

Devuelve 202 Accepted y encola el procesamiento.

POST/api/v1/analyses

Solicitud

POST /api/v1/analyses
Authorization: Bearer ct_live_...
Content-Type: application/json

{
  "fileUrl": "https://example.com/calls/call-123.mp3",
  "agentId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "queueId": "7a7bf5cc-5e34-4f4g-b98f-96g3g9433ed2",
  "externalId": "crm-call-123",
  "idempotencyKey": "crm-call-123",
  "metadata": {
    "customerId": "cust_42",
    "source": "crm"
  }
}

Respuesta

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "queued",
  "externalId": "crm-call-123"
}

Campo

Tipo

Obligatoriedad

Descripción

fileUrl

string

Obligatorio

URL HTTPS del archivo de audio a analizar. Tamaño máximo: 20 MB.

fileName

string

Opcional

Nombre visible en Call Trace. Si se omite, se usa el último segmento de la ruta de fileUrl.

agentId

uuid

Obligatorio

Agente asociado al análisis. Debe existir en su empresa.

queueId

uuid

Obligatorio

Cola con el script usado en la evaluación. Debe tener una versión activa del script.

language

string

Opcional

Idioma de la transcripción. Por defecto auto si se omite.

externalId

string

Opcional

Su identificador de CRM, helpdesk o telefonía.

idempotencyKey

string

Opcional

Deduplica reintentos de su sistema.

metadata

object

Opcional

Pequeño objeto JSON devuelto en payloads de estado y webhook.

Requisitos de URL de archivo

fileUrl debe usar HTTPS. Privados, localhost y rangos de IP internos se rechazan, incluidos redireccionamientos a redes privadas. Tamaño máximo del archivo: 20 MB. Los archivos se descargan con timeouts y comprobación de content-type antes del procesamiento.

Referencia de la API

Leer estado y resultados

Use este endpoint cuando su sistema necesite reconciliar estado o recuperarse tras entregas de webhook perdidas.

Obtener análisis

Devuelve el estado más reciente del trabajo y los campos de resultado disponibles.

GET/api/v1/analyses/{analysisId}

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "completed",
  "externalId": "crm-call-123",
  "call": {
    "durationSeconds": 184,
    "agentId": "agent-uuid",
    "queueId": "queue-uuid"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 },
      { "name": "Need discovery", "score": 18, "maxScore": 20 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

queued

La solicitud fue aceptada y espera procesamiento.

processing

El archivo se está descargando, transcribiendo y evaluando.

completed

La evaluación, transcripción y resumen de la llamada están disponibles.

failed

El procesamiento falló tras reintentos. Los detalles se devuelven en error.

Referencia de la API

Listar análisis

Busque por status, externalId, agent, queue o rango de fechas. Úselo para reconciliación back-office y herramientas de soporte.

Listar análisis

Devuelve análisis paginados de la empresa de integración.

GET/api/v1/analyses

GET /api/v1/analyses?status=completed&externalId=crm-call-123
Authorization: Bearer ct_live_...

Webhooks

Payload de webhook

Configure endpoints de webhook en Admin > Integraciones. Los payloads incluyen la información necesaria para almacenar el resultado de la evaluación en su sistema.

analysis.createdanalysis.completedanalysis.failed

{
  "deliveryId": "whd_01jz8n0f8ck2bk0smq7h2x1t0r",
  "event": "analysis.completed",
  "occurredAt": "2026-06-19T12:00:00.000Z",
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "externalId": "crm-call-123",
  "call": {
    "status": "completed",
    "durationSeconds": 184,
    "recordingUrl": "https://storage.example.com/audio/call-123.mp3"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

El texto del script no se incluye por defecto. Use deliveryId para deduplicación y analysisId más event al almacenar transiciones de estado.

Webhooks

Entrega y reintentos

Call Trace almacena cada intento de entrega y reintenta entregas fallidas para que los resultados no se pierdan por timeout o indisponibilidad temporal del cliente.

Éxito

Cualquier respuesta 2xx marca la entrega como completada.

Política de reintentos

Intento inicial más 3 reintentos con backoff, por ejemplo 10 segundos, 1 minuto y 5 minutos.

Historial

Cada intento almacena estado, código de respuesta, mensaje de error, marcas de tiempo y snapshot del payload.

Webhooks

Webhook secret

Cada webhook endpoint recibe un secret. Call Trace lo envía en cada entrega para que pueda rechazar solicitudes de fuentes desconocidas.

Por qué verificar el secret

La URL del webhook es accesible desde internet. Compare el encabezado X-CallTrace-Secret con el secret guardado al crear el endpoint. Si no coincide, devuelva 401 e ignore el payload.

Qué llega en cada entrega

POST /your/webhook-handler

X-CallTrace-Secret: whsec_8Lk3...your-endpoint-secret

X-CallTrace-Delivery: whd_01jz8n0f8ck2bk0smq7h2x1t0r

X-CallTrace-Event: analysis.completed

X-CallTrace-Timestamp: 2026-06-19T12:00:00.000Z

{ "event": "analysis.completed", "analysisId": "6f6af4bb-..." }

X-CallTrace-Secret

El secret del endpoint. Compare este valor con CALL_TRACE_WEBHOOK_SECRET en su servidor.

X-CallTrace-Delivery

ID único de entrega. Úselo para ignorar reintentos duplicados del mismo evento.

X-CallTrace-Event

Tipo de evento, por ejemplo analysis.completed.

X-CallTrace-Timestamp

Cuándo Call Trace envió la solicitud. Útil para logs y soporte.

Cómo verificar

Lea X-CallTrace-Secret de los encabezados de la solicitud y compárelo con el secret mostrado una vez en Admin > Integraciones al crear el webhook. Guarde el secret en una variable de entorno y rechace discrepancias antes de procesar el JSON.

Ejemplo en Node.js

const secret = request.headers.get("x-calltrace-secret");

if (secret !== process.env.CALL_TRACE_WEBHOOK_SECRET) {
  return new Response("Unauthorized", { status: 401 });
}

const payload = await request.json();

Ejemplos

Crear un análisis desde su lenguaje

Todos los ejemplos usan el mismo endpoint estable y esperan la clave API en CALL_TRACE_API_KEY.

const response = await fetch("https://your-domain.com/api/v1/analyses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CALL_TRACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fileUrl: "https://example.com/calls/call-123.mp3",
    fileName: "call-123.mp3",
    language: "auto",
    externalId: "crm-call-123",
    idempotencyKey: "crm-call-123"
  })
});

const analysis = await response.json();
console.log(analysis.analysisId);

Errores

Manejo de errores

Use idempotency keys para reintentos seguros. Los errores de validación se devuelven de forma síncrona. Los errores de procesamiento se devuelven por el endpoint de estado y webhooks analysis.failed.

400

JSON inválido, fileUrl ausente, content type no soportado o metadata inválida.

401

Clave API ausente, expirada, revocada o malformada.

403

La clave API no incluye el alcance requerido.

409

La misma idempotency key ya se usó para otro payload.

422

La URL del archivo está bloqueada, es privada, no es HTTPS, es demasiado grande o inaccesible.

500

Error temporal del servidor. Reintente con la misma idempotency key.

Documentación de la API Call Trace

Cree una clave API

Envíe una URL de archivo

Reciba el resultado

Verifique el secret

Cree un token en el panel de administración

Abra Integraciones

Nombre la clave

Elija los alcances

Defina la vigencia

Copie una vez

Formato del token

Use una clave de integración con alcances

Encabezado

Alcances

Qué permite cada alcance

Expiración, acceso permanente y rotación

Token permanente

Token con expiración

Token revocado

Rotación

Crear un análisis

Crear análisis

Leer estado y resultados

Obtener análisis

Listar análisis

Listar análisis

Payload de webhook

Entrega y reintentos

Éxito

Política de reintentos

Historial

Webhook secret

Por qué verificar el secret

Crear un análisis desde su lenguaje

Manejo de errores