Processamento

Envio de áudio

Envie gravações para o Quality Spy usando multipart/form-data, separando os metadados da ocorrência do arquivo de áudio.

Endpoint principal

Método: POST
Caminho: /api/v1/external-audio
Tipo de conteúdo: multipart/form-data

Como o envio funciona

A requisição usa multipart/form-data para enviar campos de texto e arquivo na mesma chamada. O cliente HTTP deve montar o corpo multipart e gerar o boundary.

metadata: Objeto JSON serializado com os dados da ocorrência.
audio: Arquivo da gravação enviado como arquivo do formulário.

Metadados documentados

Os metadados descrevem a ocorrência e ajudam a relacionar a gravação ao seu sistema de origem. Eles não substituem o arquivo de áudio.

Campo	Tipo esperado	Exemplo	Descrição	Obrigatoriedade
`id`	String	`OCC-001`	Identificador da ocorrência no sistema integrador.	Conforme configuração da integração
`id_ocorrencia`	String	`CALL-0001`	Identificador de chamada ou ocorrência relacionado ao atendimento.	Conforme configuração da integração
`funcionarionome`	String	`João Silva`	Nome do funcionário associado ao atendimento.	Conforme configuração da integração
`funcionarioemail`	String	`joao@empresa.com`	E-mail do funcionário associado ao atendimento.	Conforme configuração da integração
`duracao_gravacao`	Número	`320`	Duração informada para a gravação.	Conforme configuração da integração
`horario_inicio`	String de data e hora	`2026-07-09T09:30:00`	Data e hora de início da ocorrência.	Conforme configuração da integração
`ocorrencia_descricao`	String	`Cobrança`	Descrição ou categoria da ocorrência.	Conforme configuração da integração

Identificadores e duplicidade

Use identificadores únicos e estáveis para relacionar cada gravação ao registro correspondente no seu sistema. Essa prática facilita rastreabilidade, conciliação e prevenção de duplicidade.

Exemplos de envio

curl -X POST "https://SEU_DOMINIO/api/v1/external-audio" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -F 'metadata={"id":"OCC-001","id_ocorrencia":"CALL-001"}' \
  -F "audio=@gravacao.mp3"

const API_URL = 'https://SEU_DOMINIO/api/v1/external-audio';
const QUALITY_SPY_TOKEN = 'SEU_TOKEN';
const audioInput = document.querySelector('#audio');

const formData = new FormData();
formData.append('metadata', JSON.stringify({
  id: 'OCC-001',
  id_ocorrencia: 'CALL-001',
}));
formData.append('audio', audioInput.files[0]);

try {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${QUALITY_SPY_TOKEN}`,
    },
    body: formData,
  });

  if (!response.ok) {
    throw new Error('Falha ao enviar áudio para processamento.');
  }
} catch (error) {
  console.error('Erro no envio:', error);
}

import json
import os
import requests

API_URL = "https://SEU_DOMINIO/api/v1/external-audio"
QUALITY_SPY_TOKEN = os.getenv("QUALITY_SPY_TOKEN", "SEU_TOKEN")

metadata = {
    "id": "OCC-001",
    "id_ocorrencia": "CALL-001",
}

try:
    with open("gravacao.mp3", "rb") as audio_file:
        response = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {QUALITY_SPY_TOKEN}"},
            data={"metadata": json.dumps(metadata)},
            files={"audio": audio_file},
            timeout=60,
        )
        response.raise_for_status()
except requests.RequestException as error:
    print(f"Erro no envio: {error}")

<?php
$apiUrl = 'https://SEU_DOMINIO/api/v1/external-audio';
$qualitySpyToken = getenv('QUALITY_SPY_TOKEN') ?: 'SEU_TOKEN';

$metadata = json_encode([
    'id' => 'OCC-001',
    'id_ocorrencia' => 'CALL-001',
]);

$curl = curl_init($apiUrl);

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $qualitySpyToken,
    ],
    CURLOPT_POSTFIELDS => [
        'metadata' => $metadata,
        'audio' => new CURLFile('gravacao.mp3'),
    ],
]);

$response = curl_exec($curl);

if ($response === false) {
    error_log('Erro no envio: ' . curl_error($curl));
}

curl_close($curl);

Timeout e retry do cliente

Configure timeout no cliente HTTP para evitar chamadas presas indefinidamente. Em falhas transitórias, use retry com intervalo progressivo e cuidado para não reenviar a mesma gravação com identificadores conflitantes.