Archivos de Audio

Gestiona archivos de audio: listar, subir, descargar e iniciar procesamiento IA.

Endpoints

Metodo	Endpoint	Alcance	Descripcion
GET	/api/v1/audio-files	audio:read	Listar archivos de audio con filtros
GET	/api/v1/audio-files/{id}	audio:read	Obtener archivo de audio por ID
GET	/api/v1/audio-files/{id}/download-url	audio:download	Generar URL de descarga SAS (expira en 15 min)
GET	/api/v1/audio-files/{id}/transcript	audio:read	Obtener transcripcion
POST	/api/v1/audio-files/upload-url	audio:write	Solicitar URL de carga
POST	/api/v1/audio-files/{id}/process	audio:write	Iniciar procesamiento IA
GET	/api/v1/audio-files/{id}/processing-status	audio:read	Verificar estado de procesamiento

Parametros de Consulta (Endpoint de Listado)

Parametro	Tipo	Descripcion
campaignId	string	Filtrar por campana
isAICall	bool	Filtrar llamadas IA vs humanas
engagementId	string	Filtrar por engagement
dateFrom	datetime	Inicio del rango de fechas
dateTo	datetime	Fin del rango de fechas
page	int	Numero de pagina (por defecto: 1)
pageSize	int	Resultados por pagina (por defecto: 50, max: 100)

Flujo de Descarga

Como descargar archivos de audio

Lista los archivos de audio usando GET /api/v1/audio-files con los filtros deseados.
Llama a GET /api/v1/audio-files/{id}/download-url para obtener una URL SAS con tiempo limitado (expira en 15 min).
Realiza un GET a la URL SAS directamente -- no se necesita encabezado de autenticacion, la firma esta embebida en la URL.

Flujo de Carga

Paso 1: Solicitar una URL de carga

POST /api/v1/audio-files/upload-url
Authorization: Bearer <token>
Content-Type: application/json

{
  "fileName": "call-2026-03-30.wav",
  "engagementId": "eng_abc123",
  "campaignId": "camp_xyz"   // optional
}

// Response
{
  "audioFileId": "af_98765",
  "uploadUrl": "https://storage.blob.core.windows.net/audio/...?sv=2023&sp=w&sig=...",
  "expiresAt": "2026-03-30T12:15:00Z"
}

Paso 2: Subir el archivo a la URL SAS

PUT <uploadUrl>
x-ms-blob-type: BlockBlob
Content-Type: audio/wav

<binary file content>

El encabezado x-ms-blob-type: BlockBlob es requerido por Azure Blob Storage. Omitirlo resultara en un error 400.

Paso 3: Iniciar procesamiento IA

POST /api/v1/audio-files/af_98765/process
Authorization: Bearer <token>

// Response
{
  "status": "pending",
  "message": "Processing queued successfully"
}

Valores de Estado de Procesamiento

Estado	Descripcion
pending	Archivo subido, esperando ser procesado
processing	Transcripcion en progreso
evaluating	Evaluacion IA ejecutandose sobre la transcripcion
completed	Procesamiento finalizado exitosamente
failed	Ocurrio un error durante el procesamiento

Consulta de estado

Despues de iniciar el procesamiento, consulta GET /api/v1/audio-files/{id}/processing-status cada pocos segundos hasta que el estado alcance completed o failed. Alternativamente, configura un webhook analysis.completed para ser notificado automaticamente.