Integrações de áudio

Uma origem de áudio define como as gravações de uma campanha entram no AuditorIA. Pode ser um envio feito pelo próprio app ou uma plataforma externa conectada por webhook, API, SFTP ou outro mecanismo. Cada origem é um ponto de entrada: deixa o áudio dentro do AuditorIA e, a partir daí, o app o leva pelo fluxo correspondente.

As origens de áudio são escolhidas em cada campanha, na aba Origens de Áudio. Esta página explica o que significa escolher cada origem e o que verificar depois. Para o mapa geral da campanha, veja Configuração de campanhas.

O que uma integração faz e o que não faz

Nenhuma origem audita sozinha. Ela apenas faz o áudio entrar no AuditorIA. Dependendo da origem, essa entrada pode criar uma tarefa diretamente ou deixar o áudio/registro pronto para o fluxo correspondente.

O endereço do webhook precisa estar acessível

As integrações por webhook enviam dados pela internet à API Externa da sua instalação: o serviço que recebe esses avisos. O endereço dela é a URL base da API Externa configurada em /admin/settings, e pode estar em um domínio diferente daquele pelo qual você entra no app. Uma instalação em localhost não pode receber esses webhooks: a plataforma externa precisa de um endereço acessível pela internet.

---

Interno

Interno é a via nativa do AuditorIA: os áudios entram porque alguém os envia pelo próprio app. Não é uma integração com uma plataforma externa, então você não precisa configurar host, webhook, API Key externa, segredo nem credenciais remotas.

Interno não sincroniza nada por conta própria

Diferente das demais origens desta página, o Interno não busca áudios nem os recebe automaticamente. Nada entra sozinho: cada chamada chega ao AuditorIA porque uma pessoa a enviou.

Passo 1 - Na campanha: escolher Interno

1. No menu lateral, abra Campanhas > Configuração de campanhas > Chamadas.
2. Abra a campanha correspondente. Se for nova, salve-a primeiro: a origem é configurada sobre uma campanha já salva.
3. Entre na aba Origens de Áudio.
4. Escolha Interno e salve.

Ao escolher Interno, o AuditorIA não mostra campos adicionais de conexão. Com isso fica registrado que essa campanha trabalha com áudios enviados pelo app, e a configuração da origem termina aqui: não há credenciais para colar nem serviço externo para manter ligado.

O que ignorar nesta tela

A aba Origens de Áudio reaproveita textos pensados para as integrações externas que não se aplicam ao Interno:

• onde diz provedor ou receber áudios automaticamente: para o Interno não há provedor nem automatismo;
• o estado Sincronização ativa / inativa: o Interno não sincroniza, então esse indicador não serve para saber se a campanha ficou bem configurada.

Para o Interno, o sinal de que está tudo certo é o envio terminar corretamente e a tarefa aparecer.

Passo 2 - Enviar os áudios

Os áudios são enviados pela tela Enviar arquivo. Escolha o fluxo conforme o caso:

• Um ou vários arquivos avulsos: Anexar arquivos no envio padrão.
• Muitos áudios de uma vez: Envio em massa com ZIP + CSV.
• Uma chamada dividida em partes: Enviar uma chamada fragmentada.

Cada fluxo está explicado passo a passo em Enviar áudio. Esta página não os repete.

O que verificar depois

Depois de iniciar um envio, o AuditorIA cria a tarefa e o registro da chamada, e os deixa no fluxo normal de tarefas. Para conferir, verifique:

• a confirmação de envio na tela Enviar áudio;
• Buscar e trabalhar com tarefas, para abrir a tarefa criada;
• Buscar áudios, se quiser verificar se o áudio já estava carregado antes de enviá-lo de novo.

O que significa "API interna"

Na tela, o Interno é descrito como "Envio manual de arquivos ou API interna". Essa menção não é uma via separada que você possa configurar por aqui: refere-se aos endpoints que o próprio app usa quando você envia um arquivo. Não existe uma "API interna" que o AuditorIA entregue para conectar sistemas.

Se o que você precisa é que um sistema de terceiros envie áudios por conta própria, com a própria API Key, esse caso é API Externa, não Interno.

---

Anura

Conecte seu PBX na nuvem Anura para que cada chamada finalizada com gravação entre automaticamente no AuditorIA e fique pronta para auditar.

Como funciona

Quando uma chamada termina na Anura, a Anura envia um aviso (webhook) ao AuditorIA com os dados da chamada e o link da gravação. O AuditorIA valida a chave de acesso, identifica o operador, baixa a gravação, cria a tarefa e a processa. Você não precisa enviar nada manualmente.

Antes de começar

• Uma campanha de chamadas criada no AuditorIA. Você vai precisar do identificador dela (campaign_id). Veja Configuração de campanhas.
• Uma planilha de qualidade associada a essa campanha, para poder auditar depois. Veja Planilhas de qualidade.
• Uma API Key do AuditorIA (a chave que autentica o aviso da Anura).
• Acesso à configuração de Eventos / Webhooks na sua conta da Anura.
• A URL externa do seu AuditorIA (veja o aviso sobre o endereço do webhook).

Passo 1 - No AuditorIA: marcar a Anura como origem

1. No menu lateral, abra Campanhas > Configuração de campanhas > Chamadas. Você verá a lista de campanhas: escolha a que quer integrar com a Anura.

2. Abra a campanha (se for nova, salve-a primeiro: a origem se configura sobre uma campanha já salva) e entre na aba Origens de Áudio.

3. Escolha Anura e salve.

Ao escolher a Anura, o AuditorIA mostra um guia com o formato do aviso, os cabeçalhos e as regras. Use-o como referência enquanto configura o evento na Anura.

Passo 2 - No AuditorIA: criar a API Key

1. Abra Configurações > API Keys (/dashboard/settings/api-keys).
2. Gere uma API Key e copie. Você vai usá-la como cabeçalho X-API-Key ao configurar a Anura.

informação

Guarde a API Key em um lugar seguro ao criá-la. É a credencial que autentica os avisos da Anura no seu AuditorIA.

Passo 3 - Na Anura: criar o evento

Na sua conta da Anura, crie um evento que avise o AuditorIA quando a chamada termina.

1. Entre no painel da Anura.

2. Abra Configuração > Eventos.

3. Use Adicionar para criar um evento novo.

O evento tem três abas: Requisição, Cabeçalhos e Corpo. Preencha as três.

Requisição

Define para onde e como o aviso é enviado.

Campo	Valor
Protocolo	HTTPS
Host	o domínio público do seu AuditorIA
Porta	443
Rota	/webhook/anura/
Método	POST
Tipo de conteúdo	application/json
Autorização	Sem autorização (a chave vai nos Cabeçalhos)

O host é o da sua instalação

O host é o domínio da API Externa da sua instalação, que é quem recebe o aviso da Anura. É a URL base da API Externa configurada em /admin/settings, e nem sempre coincide com o domínio pelo qual você entra no AuditorIA. Se não souber qual é a da sua implantação, peça a quem a administra.

Cabeçalhos

Adicione, como pares Chave / Valor, os cabeçalhos do aviso:

• X-API-Key: a API Key que você criou no passo 2.
• Content-Type: application/json.

Corpo

O Corpo é o JSON que a Anura vai enviar em cada chamada. Monta-se assim:

• as chaves são os campos que o AuditorIA precisa;
• os valores são as variáveis da Anura {{ ... }}, que a Anura substitui pelos dados reais ao enviar;
• campaign_id não é uma variável: é o número da sua campanha no AuditorIA. Você o vê no cabeçalho da campanha como ID da campanha #N, e vai sem aspas.

Não inclua os campos automáticos: cdrid é gerado pelo AuditorIA se não vier, e hooktrigger assume END por padrão (além disso, seu evento já dispara somente em END).

Cole este JSON no Corpo e substitua <ID_DA_SUA_CAMPANHA> pelo número da sua campanha:

{
  "dialtime": "{{ dialtime }}",
  "direction": "{{ direction }}",
  "calling": "{{ calling }}",
  "called": "{{ called }}",
  "status": "{{ status }}",
  "duration": "{{ duration }}",
  "billseconds": "{{ billseconds }}",
  "wasrecorded": "{{ wasrecorded }}",
  "audio_file_mp3": "{{ audio_file_mp3 }}",
  "accountname": "{{ accountname }}",
  "accountextension": "{{ accountextension }}",
  "queueagentname": "{{ queueagentname }}",
  "answerterminal": "{{ answerterminal }}",
  "campaign_id": <ID_DA_SUA_CAMPANHA>
}

O que cada campo significa:

Campo	Para que serve
dialtime	Data e hora da chamada.
direction	Entrante (inbound) ou sainte (outbound).
calling / called	Números de origem e destino.
status	Estado final da chamada.
duration	Duração em segundos.
billseconds	Segundos faturados.
wasrecorded	Deve ser true.
audio_file_mp3	URL acessível da gravação.
accountname	Nome da conta/agente. Em chamadas saintes o AuditorIA o usa como operador.
accountextension	Ramal da conta.
queueagentname / answerterminal	Nome do agente em chamadas entrantes. O AuditorIA o usa como operador.
campaign_id	Número da campanha no AuditorIA (não é uma variável).

O operador depende da direção da chamada

O AuditorIA identifica o operador pelo nome, não pelo ramal: em chamadas saintes usa accountname; em entrantes usa queueagentname (ou answerterminal). Por isso o JSON inclui os três. Se a sua Anura nomear de outra forma as variáveis do agente em fila, ajuste esses dois valores.

A Anura envia o aviso mesmo que o JSON esteja incompleto, mas o AuditorIA o rejeita se não chegarem todos os dados da chamada de que precisa: dialtime, direction, calling, called, status, duration, billseconds, accountname e accountextension. Por isso convém colar o JSON completo, tal como está.

A Anura também oferece muitas outras variáveis (por exemplo callingname, calledname, dados de fila ou accounttags). Você pode adicioná-las ao Corpo se as quiser para seus próprios registros, mas são opcionais: hoje o AuditorIA não as usa, então, para que a chamada seja processada, bastam os campos da tabela.

As variáveis {{ ... }} que você vê no JSON são da Anura: ao enviar o aviso, a Anura as substitui pelos dados reais da chamada. Não é preciso carregá-las em nenhum outro lugar nem preencher outro formulário; elas vão dentro do Corpo, tal como estão acima. O guia de Origens de Áudio > Anura inclui uma lista de variáveis como referência, mas, para que a chamada seja processada, basta o JSON desta página.

aviso

Só são processados eventos END com gravação. Se wasrecorded não for true ou audio_file_mp3 não estiver acessível, nenhuma tarefa é criada.

Com isso a integração fica pronta

Salve o evento. Não há passos adicionais: a partir da próxima chamada finalizada com gravação, a Anura avisa o AuditorIA e a chamada entra sozinha no fluxo. A Anura não tem botão de teste, então, para confirmar, faça uma chamada real (curta, com gravação) e verifique se aparece nas tarefas da campanha.

O que acontece depois

Quando tudo está configurado, cada chamada finalizada com gravação:

1. Chega ao AuditorIA, que valida a API Key.
2. Identifica o operador pelo nome. Se esse operador ainda não existir, ele o cria.
3. Baixa a gravação e cria a tarefa.
4. Entra no fluxo normal: aparece em Buscar e trabalhar com tarefas, é transcrita e fica pronta para revisar e auditar.

Notas importantes

• Operador pelo nome: se o nome do agente na Anura não coincidir com um operador existente, o AuditorIA cria um novo. Para evitar operadores duplicados, use os mesmos nomes que você já tem cadastrados. Veja Gerenciar operadores locais.
• Campanha correta: se campaign_id não coincidir com uma campanha real, a chamada pode não ser associada à campanha esperada.
• Apenas END com gravação: os demais eventos são recebidos mas não geram tarefas.

Problemas frequentes

• Nenhuma chamada entra: verifique que o evento seja END, que a gravação esteja ativada, que audio_file_mp3 seja acessível e que a URL e os cabeçalhos estejam corretos.
• O aviso é rejeitado (não autorizado): a X-API-Key está faltando ou incorreta.
• A chamada entra em outra campanha ou sem o operador correto: verifique campaign_id e o nome do agente.

---

Net2Phone

Conecte o Net2Phone para que as chamadas gravadas cheguem ao AuditorIA por webhook e fiquem prontas para entrar no fluxo de tarefas.

A configuração começa na campanha do AuditorIA. A partir dessa tela você vê quais dados a integração pede e, para cada campo, onde obter o valor correspondente no Net2Phone.

Passo 1 - Abrir Net2Phone em Origens de Áudio

1. No menu lateral, abra Campanhas > Configuração de campanhas > Chamadas.
2. Abra a campanha correspondente. Se for nova, salve-a primeiro.
3. Entre na aba Origens de Áudio.
4. Escolha Net2Phone.

O AuditorIA vai pedir três dados:

• Source ID: identifica qual conta do Net2Phone corresponde a esta campanha.
• Segredo de assinatura do webhook: permite aceitar apenas eventos assinados pelo webhook que você vai criar.
• API Key do Net2Phone: permite pedir ao Net2Phone o link baixável da gravação.

Passo 2 - Preencher Source ID

Em Source ID, o AuditorIA espera o account_id numérico do Net2Phone. Não use o ID interno de campanha do AuditorIA, a menos que ele realmente coincida com esse account_id.

Source ID não é o ID da campanha

Para Net2Phone, Source ID = account_id do Net2Phone.

Se sua equipe já conhece o account_id, use-o diretamente. Se ele não aparecer visível na tela do Net2Phone, você pode buscá-lo pelo navegador:

1. Entre no Net2Phone.
2. Abra as ferramentas de desenvolvedor com F12. No Chrome, também é possível abrir pelo menu de três pontos > Mais ferramentas > Ferramentas do desenvolvedor.

3. No DevTools, entre na aba Application.

4. Em Local Storage, selecione o domínio do Net2Phone e procure o valor account_id.
5. Copie esse número e cole em Source ID dentro do AuditorIA.

Passo 3 - Criar o webhook e preencher o segredo de assinatura

O campo Segredo de assinatura do webhook é preenchido com um valor que o Net2Phone mostra depois de salvar o webhook.

Antes de criar o webhook, copie a URL de destino. Ela deve ser a URL base externa da API Externa da sua instalação e terminar em /webhook/net2phone/.

Se o AuditorIA mostra o Endpoint externo para Net2Phone, copie-o desse campo. Se não mostra, ou se seu deploy ainda não tem essa URL configurada, peça ao administrador do deploy. Não monte essa URL a partir do endereço onde você navega no AuditorIA, porque a API Externa pode estar em outro domínio.

1. No Net2Phone, clique no ícone de usuário no canto superior direito.

2. No menu, entre em Configurações da Empresa.

3. Abra Configuração da API e entre na aba Webhook.

4. Crie um novo webhook.
5. Em URL de destino, cole o endpoint público da API Externa.
6. Use um nome reconhecível, por exemplo AuditorIA, e complete a descrição se sua equipe a usa para identificar integrações.

7. Em eventos, escolha Eventos específicos.

8. Ative pelo menos Call Recorded e Call Completed. Se o Net2Phone mostrar eventos de chamada atendida, chamadas recebidas ou chamadas realizadas, também é útil ativá-los para ter mais rastreabilidade.

9. Em usuários, escolha o alcance correspondente. Para auditar todo um call center, use uma opção de toda a empresa ou todos os telefones somente se ela realmente se aplicar a todos os usuários que você quer auditar.

O webhook não ativa a gravação sozinho

Selecionar usuários para o webhook define de quem o Net2Phone envia eventos. Isso não substitui a configuração de gravação. Verifique no Net2Phone se a gravação está ativa para cada usuário, ramal ou telefone que deve ser auditado.

10. Salve o webhook.
11. Volte para a lista de webhooks e abra a configuração do webhook que você acabou de criar.

12. No modal de configuração, copie o Segredo de assinatura.

13. Volte ao AuditorIA e cole em Segredo de assinatura do webhook.

Passo 4 - No Net2Phone: criar a API Key e colar no AuditorIA

O campo API Key do Net2Phone é preenchido com uma chave gerada no Net2Phone. O AuditorIA a usa para pedir o link baixável da gravação quando chega o evento de chamada gravada.

1. No Net2Phone, entre na aba API Keys.

2. Crie uma chave para o AuditorIA.
3. Se o Net2Phone pedir scope, use o scope que permita Public API v2 e acesso a gravações. No ambiente testado apareceu public_api.v2; se sua conta mostrar opções diferentes, confirme com sua equipe ou com o suporte do Net2Phone.

4. Ao criá-la, o Net2Phone mostra a chave completa. Copie nesse momento.

5. Volte ao AuditorIA e cole em API Key do Net2Phone.

6. Salve a configuração da campanha.

Passo 5 - Verificar com uma chamada real

Para testar a integração, gere uma chamada curta com gravação habilitada e verifique:

• se o Net2Phone envia call_recorded;
• se o evento inclui audio_message_url;
• se o account_id do evento coincide com o Source ID da campanha;
• se aparece uma nova tarefa em Buscar e trabalhar com tarefas.

O caso esperado para criar a tarefa é Call Recorded (call_recorded) com audio_message_url. Call Completed (call_completed) pode indicar que a chamada foi gravada, mas se não trouxer uma URL de áudio o AuditorIA não tem gravação para baixar.

Problemas frequentes

• Você não sabe qual URL colocar no Net2Phone: peça a URL base externa da API Externa do deploy. Ela deve terminar em /webhook/net2phone/.
• O webhook é rejeitado: verifique se o segredo de assinatura copiado do Net2Phone é o mesmo salvo no AuditorIA.
• A chamada não aparece na campanha: verifique se Source ID é o account_id do Net2Phone.
• Chega call_completed, mas nenhuma tarefa é criada: verifique se também chegou call_recorded com audio_message_url. Sem URL de áudio, não há gravação para baixar.
• O download falha: verifique se a API Key do Net2Phone está ativa e tem permissão para acessar gravações.

---

Neotel

O Neotel é uma central telefônica instalada na própria empresa. Diferente do Anura ou do Net2Phone, aqui o Neotel não avisa nada ao AuditorIA: é o AuditorIA que vai buscar as chamadas, sozinho, a cada poucos minutos, e traz as gravações.

Use quando as chamadas da campanha já são gravadas no Neotel e você não quer enviá-las manualmente.

Como funciona

Existe um único Neotel conectado ao AuditorIA, compartilhado por todas as campanhas. Essa conexão (onde o Neotel está e com qual usuário entrar) é deixada pronta pelo administrador da sua instalação, uma única vez, para toda a aplicação.

O que você faz na campanha é muito mais simples: avisar que essa campanha usa Neotel. A partir daí, o AuditorIA consulta o Neotel a cada poucos minutos, encontra as chamadas novas dessa campanha, traz a gravação e a deixa registrada.

O Neotel não precisa de um endereço acessível pela internet

O aviso do começo desta página, sobre o endereço do webhook, não se aplica ao Neotel. O Neotel não envia nada ao AuditorIA: é o AuditorIA que o consulta, de dentro da rede.

Antes de começar

• Uma campanha de chamadas criada e salva no AuditorIA. Veja Configuração de campanhas.
• Que o administrador da sua instalação já tenha conectado o Neotel. É um passo técnico feito uma única vez para toda a aplicação, não campanha por campanha. Se não estiver feito, você pode selecionar Neotel mesmo assim, mas nenhuma chamada vai entrar.
• O número com que o Neotel identifica essa campanha. No Neotel esse dado aparece como IDAPLICACION. Se você não o tem, peça a quem administra o Neotel.

Passo 1 - No AuditorIA: selecionar Neotel

1. No menu lateral, abra Campanhas > Configuração de campanhas > Chamadas.
2. Abra a campanha correspondente. Se for nova, salve-a primeiro.
3. Entre na aba Origens de Áudio.
4. Selecione Neotel e salve.

Com isso a campanha fica ativada. Na próxima verificação, o AuditorIA passa a incluí-la quando procura chamadas novas no Neotel.

Repare que o AuditorIA não pede aqui nem usuário, nem senha, nem endereço do Neotel: tudo isso já vem da conexão geral que o administrador deixou pronta.

Passo 2 - Verificar que a campanha coincide com o Neotel

Este é o ponto que mais falha, e não tem nenhum campo onde escrevê-lo: é uma correspondência que precisa existir entre os dois sistemas.

O ID de campanha do AuditorIA (o número que aparece no cabeçalho da campanha como ID de campanha #N) precisa ser o mesmo número que o Neotel usa para essa campanha em IDAPLICACION.

Se os números não coincidem, nada entra

O AuditorIA procura no Neotel as chamadas cujo IDAPLICACION seja igual ao ID da campanha. Se esses dois números não forem o mesmo, a busca não retorna nada: a campanha fica vazia mesmo com todo o resto configurado corretamente.

Se não coincidem, não tente resolver por esta tela. Consulte quem administra o Neotel ou o administrador da sua instalação.

Opções avançadas

O painel do Neotel inclui um bloco de Overrides avançados, com um interruptor e uma caixa de texto para colar configuração. Serve para um caso pouco frequente: essa campanha em particular precisar se conectar a um Neotel diferente do que as demais usam.

Se você não sabe se precisa, você não precisa

Deixe desligado. Com o interruptor em off, a campanha usa a conexão geral, que é o correto em praticamente todos os casos. Preencher esse bloco incorretamente pode deixar a campanha sem receber chamadas.

O que acontece depois

Quando o AuditorIA encontra uma chamada nova no Neotel, traz a gravação e a deixa como registro de chamada na campanha.

Esse registro ainda não é uma tarefa. Para que vire tarefa e seja transcrito, a campanha precisa ter o Envio Automático de Chamadas ativado. Veja Envio automático em Configuração de campanhas.

O Neotel traz a chamada, mas não a envia para auditar

Essa é a principal diferença em relação ao Anura e ao Net2Phone, que criam a tarefa diretamente. Com o Neotel, se a campanha não tem envio automático, as chamadas entram e ficam registradas, mas não são processadas.

Com o envio automático ativo, as chamadas seguem o fluxo normal: aparecem em Buscar e trabalhar com tarefas, são transcritas e ficam prontas para revisar e auditar.

Notas importantes

• A conexão é uma só para todas as campanhas: se ela mudar, afeta todas as campanhas que usam Neotel, não apenas a sua.
• Selecionar Neotel não ativa a gravação: as chamadas precisam já estar sendo gravadas no Neotel. O AuditorIA apenas busca o que já existe.
• Os dados exibidos na tela são de referência: o painel do Neotel mostra nomes de bancos de dados, comandos e configuração interna. São dados para o administrador da instalação, não passos que você precise executar. Para conectar a campanha basta selecionar Neotel, salvar e verificar a correspondência de ID.

Problemas frequentes

• Nenhuma chamada entra: confirme com o administrador da sua instalação que a conexão geral com o Neotel está configurada e ativa. É o primeiro a descartar, porque não é visível por esta tela.
• A campanha está salva com Neotel mas continua vazia: verifique se o ID de campanha coincide com o IDAPLICACION do Neotel (passo 2).
• As chamadas entram mas não são processadas: a campanha não tem Envio Automático de Chamadas ativado, ou as chamadas ficam fora dos filtros de duração ou de idade.
• Falta uma chamada específica: pode ser que a gravação dela não esteja disponível do lado do Neotel. Consulte quem o administra.

---

API Externa

API Externa é a via para que um sistema que você já tem -um gravador, um CRM, uma aplicação própria- envie áudios ao AuditorIA por conta própria, sem que ninguém os carregue à mão.

Ela se diferencia da Anura e do Net2Phone em um ponto. Nessas integrações, a plataforma externa avisa sozinha depois que você a configura com cliques. Aqui não há uma plataforma que se configure assim: o AuditorIA fornece o endereço, a credencial e o formato da mensagem, e o envio precisa ser programado no sistema que tem os áudios.

Quem faz esta integração

Esta é a única integração do manual que precisa que alguém escreva o envio: um desenvolvedor, ou o contato técnico do sistema que guarda as gravações. Os passos 1 e 2 são administrativos e qualquer pessoa faz pelo AuditorIA. O passo 3 é a parte que você repassa a essa pessoa.

Quando usar

Use quando você já tem os áudios em outro sistema e quer que eles entrem sozinhos no AuditorIA, mas esse sistema não é a Anura nem o Net2Phone. Por exemplo: um gravador próprio do call center, um CRM que guarda as chamadas, ou um processo que baixa gravações de outro lugar.

Se uma pessoa vai carregar os áudios pela tela do AuditorIA, você não precisa desta integração: use Interno.

Antes de começar

• Uma campanha de chamadas criada e salva no AuditorIA. Você vai precisar do número da campanha. Veja Configuração de campanhas.
• Uma planilha de qualidade associada a essa campanha, para poder auditar depois. Veja Planilhas de qualidade.
• Uma API Key do AuditorIA (a credencial que autoriza os envios).
• Os operadores dessa campanha já cadastrados, porque cada envio indica a que operador a chamada pertence. Veja Gerenciar operadores locais.
• A URL externa da API da sua instalação: o mesmo endereço base que o Net2Phone usa, sem a parte do webhook. Se você não a conhece, peça ao administrador do deploy. Não monte essa URL a partir do endereço onde você navega no AuditorIA, porque a API pode estar em outro domínio.

Passo 1 - No AuditorIA: escolher API Externa na campanha

1. No menu lateral, abra Campanhas > Configuração de campanhas > Chamadas.
2. Abra a campanha correspondente. Se for nova, salve-a primeiro.
3. Entre na aba Origens de Áudio.
4. Escolha API Externa e salve.

Diferente do Servidor SFTP ou do Net2Phone, esta tela não tem campos para preencher: ela é informativa. Mostra o link para a documentação técnica da API e lembra onde criar a API Key.

Passo 2 - Criar a API Key

1. Abra Configurações > API Keys (/dashboard/settings/api-keys).
2. Gere uma API Key e copie.

Guarde a API Key ao criá-la

É a credencial que autoriza cada envio. Guarde-a em local seguro assim que criar e compartilhe somente com quem vai programar a integração.

Passo 3 - Programar o envio dos áudios

Esta é a parte feita pelo sistema que tem as gravações. Cada áudio é enviado com uma mensagem (uma requisição HTTP) que leva três coisas: a credencial, o áudio e os dados da chamada.

A credencial

A API Key viaja como cabeçalho:

X-API-Key: <SUA_API_KEY>

A API Key é a única coisa que vai como cabeçalho

O resto dos dados, inclusive campaign_id, não são cabeçalhos: viajam dentro da mensagem. Se você mandar campaign_id como cabeçalho, o AuditorIA não vai lê-lo e o envio falha.

Escolher como enviar o áudio

Há três formas, conforme o modo como seu sistema tem o áudio. As três fazem a mesma coisa: criam a chamada no AuditorIA. Escolha a que for mais simples para você.

Se o seu sistema tem...	Forma	Endereço
o arquivo de áudio salvo	envio do arquivo	POST /upload
um link público para o áudio	envio por link	POST /upload/from-url
o áudio em memória, sem arquivo	envio em texto (base64)	POST /upload/from-base64

• Envio do arquivo (/upload): o áudio vai anexado e os dados como campos de formulário (multipart/form-data). É a forma clássica.
• Envio por link (/upload/from-url): em vez do áudio, você passa uma URL de onde o AuditorIA o baixa. Essa URL precisa abrir sem usuário nem senha.
• Envio em texto (/upload/from-base64): o áudio vai convertido em texto dentro da mensagem. É a forma recomendada quando o sistema não consegue mandar arquivos anexados.

O endereço completo é a URL externa da API mais esse caminho. Por exemplo: https://api.seu-dominio-de-auditoria/upload/from-url.

Os dados da chamada

Viajam dentro da mensagem: como campos de formulário no envio do arquivo, e dentro do JSON nas outras duas formas.

Dado	Obrigatório	O que é
campaign_id	Sim	Número da campanha no AuditorIA. Você o vê no cabeçalho da campanha como ID da campanha #N.
username	Sim	Usuário que fica registrado como responsável pelo envio.
operator_id	Sim	Número do operador a que a chamada pertence.
call_start_date	Não	Data e hora de início, no formato YYYY-MM-DD HH:MM:SS (por exemplo 2026-04-06 11:18:56). Se você não mandar, é usada a hora do servidor.
language	Não	Idioma do áudio. Por padrão es.
model	Não	Modelo de transcrição. Por padrão nova-3.
ani_tel	Não	Telefone do cliente, até 30 caracteres.
direction	Não	Sentido da chamada: inbound ou outbound.

Além disso, cada forma pede o seu: /upload o arquivo no campo file; /upload/from-url a url do áudio; /upload/from-base64 o áudio em audio_base64 e o nome em file_name, com extensão (por exemplo gravacao.mp3).

ani_tel e direction só vão por link ou por texto

O envio do arquivo (/upload) não aceita ani_tel nem direction. Se você precisa guardar o telefone do cliente ou o sentido da chamada, use o envio por link ou o envio em texto.

Limites do áudio

• Formatos aceitos: mp3, wav, ogg, m4a, flac, aac.
• Tamanho máximo: 50 MB por áudio (valor padrão do deploy).
• Até 10 envios por minuto. Se você mandar mais, os seguintes são rejeitados até o minuto seguinte.

Exemplos

Envio por link:

curl -X POST "https://api.seu-dominio-de-auditoria/upload/from-url" \
  -H "X-API-Key: <SUA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema/gravacoes/chamada-123.mp3",
    "campaign_id": 12,
    "username": "integracao-crm",
    "operator_id": 45,
    "ani_tel": "1122334455",
    "direction": "outbound",
    "call_start_date": "2026-04-06 11:18:56"
  }'

Envio do arquivo:

curl -X POST "https://api.seu-dominio-de-auditoria/upload" \
  -H "X-API-Key: <SUA_API_KEY>" \
  -F "file=@chamada-123.mp3" \
  -F "campaign_id=12" \
  -F "username=integracao-crm" \
  -F "operator_id=45"

Envio em texto (base64):

curl -X POST "https://api.seu-dominio-de-auditoria/upload/from-base64" \
  -H "X-API-Key: <SUA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_base64": "<AUDIO_EM_BASE64>",
    "file_name": "chamada-123.mp3",
    "campaign_id": 12,
    "username": "integracao-crm",
    "operator_id": 45
  }'

Substitua 12 e 45 pelo número da sua campanha e pelo do seu operador.

O que o AuditorIA responde

Se o envio for aceito, a resposta confirma que a chamada ficou na fila:

{
  "task_id": "8f3c1a2e-...",
  "status": "queued",
  "message": "File downloaded and queued successfully"
}

Guarde o task_id se você quiser rastrear essa chamada depois.

A API tem a própria documentação navegável

Sobre a URL externa da API, o caminho /docs abre uma página onde se veem todos os campos e é possível testar os envios (por exemplo https://api.seu-dominio-de-auditoria/docs). O envio do arquivo (/upload) não aparece nessa página; as outras duas formas sim.

Como conferir se ficou funcionando

Envie um áudio curto de teste e verifique se aparece uma tarefa nova em Buscar e trabalhar com tarefas, dentro da campanha que você indicou.

O botão Testar desta tela não verifica a integração

Ao escolher API Externa, a aba Origens de Áudio mostra um botão Testar. Hoje esse botão não confere nada: dá erro mesmo com tudo bem configurado. Não tome isso como sinal de que algo está falhando. A forma válida de verificar é enviar um áudio real.

O que acontece depois

Quando o AuditorIA aceita o envio:

1. Guarda o áudio e cria a tarefa e o registro da chamada.
2. A tarefa entra no fluxo normal: aparece em Buscar e trabalhar com tarefas, é transcrita e fica pronta para revisar e auditar.

Não depende do despacho automático da campanha: a tarefa é criada junto com o envio.

Problemas frequentes

• Responde que falta autenticação (401): o envio não leva a API Key. Verifique se o cabeçalho se chama X-API-Key.
• Responde que a API Key é inválida (403): a chave foi copiada errado ou foi desativada. Gere uma nova em Configurações > API Keys.
• Responde que não encontra a campanha (404): o campaign_id não corresponde a nenhuma campanha. Verifique o número no cabeçalho da campanha e se a campanha está salva.
• Responde que o arquivo já foi enviado (409): já entrou um áudio com esse mesmo nome de arquivo para esse mesmo username. Mude o nome do arquivo ou use outro usuário de envio.
• Responde que o arquivo é muito grande (413): o áudio passa do limite de 50 MB.
• Responde que os dados são inválidos (422): verifique o formato de call_start_date, se a extensão do arquivo está entre as aceitas e, se você enviou por link, se a URL abre sem usuário nem senha.
• Responde que há envios demais (429): o limite de 10 envios por minuto foi ultrapassado. Espace os envios.
• O envio é aceito, mas a chamada não aparece onde você esperava: verifique se campaign_id e operator_id estão corretos.

---

Servidor SFTP

Conecte um servidor SFTP para que as gravações que o seu sistema deixa lá entrem sozinhas no AuditorIA, sem que ninguém precise enviá-las manualmente.

É a origem indicada quando a sua central telefônica, o seu gravador ou algum processo interno já deixa os áudios em uma pasta de um servidor, e só falta o AuditorIA buscá-los.

Como funciona

De tempos em tempos, um serviço de sincronização entra no servidor com os dados que você cadastrar, verifica a pasta indicada e baixa as gravações novas. De cada arquivo ele identifica quem atendeu a ligação (pelo nome do arquivo ou pela pasta em que está guardado) e o entrega ao AuditorIA, que cria a tarefa e a deixa pronta para auditar.

Você precisa do serviço de sincronização ativo

A conexão é configurada pelo AuditorIA, mas quem baixa os áudios é um serviço à parte que a sua instalação precisa ter em funcionamento. Confirme isso com quem administra a sua implantação antes de começar: se esse serviço não estiver ativo, você vai conseguir salvar a configuração e o teste de conexão vai passar, mas nenhum áudio vai entrar.

Antes de começar

Reúna estes dados:

• Uma campanha de ligações criada e salva no AuditorIA. Veja Configuração de campanhas.
• O endereço do servidor (host) e a porta (normalmente 22).
• O usuário e a sua senha, ou a chave privada se o servidor usar chave em vez de senha.
• O caminho da pasta onde as gravações são guardadas, por exemplo /gravacoes/.
• Saber como os arquivos são nomeados e como estão organizados em pastas. É isso que você vai explicar ao AuditorIA para que ele saiba de quem é cada ligação.

Passo 1 - Escolher Servidor SFTP na campanha

1. No menu lateral, abra Campanhas > Configuração de campanhas > Ligações.
2. Abra a campanha desejada. Se for nova, salve-a primeiro.
3. Entre na aba Origens de Áudio.
4. Escolha Servidor SFTP.

Passo 2 - Preencher os dados do servidor

Preencha os campos com os dados que você reuniu:

Campo	O que preencher
Host	O endereço do servidor, por exemplo sftp.minhaempresa.com, ou o seu IP.
Porta	A porta do servidor. Se não indicaram outra, é 22.
Usuário	O usuário com o qual se entra no servidor.
Password / Key	A senha desse usuário. Se o seu servidor usar chave privada em vez de senha, cole a chave completa neste mesmo campo.
Caminho Remoto	A pasta onde estão as gravações, por exemplo /gravacoes/.

A senha é guardada protegida

O AuditorIA guarda a senha (ou a chave) criptografada. Quando você reabrir a tela, vai ver o campo com asteriscos: isso é normal. Se precisar alterá-la, digite a nova por cima; se for deixá-la como está, não a toque.

Passo 3 - Testar a conexão

Antes de seguir, clique em Testar. O AuditorIA tenta entrar no servidor naquele momento com os dados que você preencheu.

• Conectado: o endereço, o usuário e a senha estão corretos.
• Erro: a mensagem indica o que falhou. Quase sempre é um dado digitado errado, o servidor fora do ar ou um firewall bloqueando a conexão.
• Pendente: a conexão ainda não foi testada desde que você preencheu ou alterou os dados.

O que o teste comprova e o que não comprova

O teste confirma que o AuditorIA consegue entrar no servidor com aquele usuário. Ele não comprova que o Caminho Remoto existe nem que há áudios lá dentro, e também não baixa nenhum arquivo. Se o teste passar mas nenhuma gravação entrar, verifique o caminho.

Se a mensagem avisar que a senha está mascarada, digite-a novamente e teste outra vez: por segurança, o AuditorIA não usa o valor com asteriscos no teste.

Passo 4 - Explicar ao AuditorIA como ler os seus arquivos

Abaixo dos dados de conexão está a seção Processamento de arquivos. É aqui que você diz ao AuditorIA como interpretar cada gravação que ele baixar. As alterações feitas neste bloco podem levar até 5 minutos para entrar em vigor.

Quem atendeu cada ligação

Toda ligação precisa ficar atribuída a um operador. Isso é definido em três partes.

1. Operador padrão. É o operador usado quando não é possível saber quem atendeu. Escolha-o no campo de busca.

Se você deixá-lo vazio, as gravações sem operador identificável não são processadas e ficam como falhas.

2. De onde vem o operador. Escolha uma das duas opções:

• Do nome do arquivo: o nome da gravação inclui quem atendeu. É lido conforme o formato que você definir abaixo.
• Da pasta que o contém: o operador é o nome da pasta em que o áudio está. Por exemplo, em /gravacoes/2026/07/20/Juan Perez/ligacao.mp3 o operador é Juan Perez. É conveniente quando o nome do arquivo é usado para outros dados, como a data ou o cliente. Se a pasta for um número, ele é tomado como ID externo do operador em vez do nome.

3. Como são atribuídos. Escolha uma das três opções:

• Detectar o operador e criá-lo se não existir: se o operador ainda não estiver cadastrado no AuditorIA, ele é criado automaticamente. Use quando os nomes dos seus arquivos ou pastas forem confiáveis.
• Usar apenas operadores existentes: se o operador que vem no arquivo já estiver no AuditorIA, a ligação é atribuída a ele; se não, é usado o operador padrão. Nunca são criados operadores novos.
• Atribuir tudo ao operador padrão: todas as ligações desta origem vão para o operador padrão, independentemente do que o arquivo indicar.

As duas últimas opções precisam de um operador padrão

Se você escolher Usar apenas operadores existentes ou Atribuir tudo ao operador padrão, precisa ter escolhido um operador padrão acima. O AuditorIA avisa antes de salvar.

Se você não souber qual escolher

Comece com Detectar o operador e criá-lo se não existir. Se com o tempo você notar operadores repetidos ou com nomes estranhos, mude para Usar apenas operadores existentes.

Como os seus arquivos são nomeados

Se as suas gravações seguem um formato fixo de nome, o AuditorIA pode lê-lo e preencher sozinho a data da ligação, o operador, o cliente e outros dados.

Você tem dois caminhos:

• Usar a nomenclatura da campanha: se a campanha já tem um formato definido na aba Automação, ative a chave e esse mesmo formato é reaproveitado. É o mais simples.
• Definir um formato próprio para esta origem: desative essa chave e monte-o aqui. Serve quando os arquivos do servidor são nomeados de forma diferente dos que são enviados manualmente.

Para montá-lo, adicione as partes na mesma ordem em que aparecem no nome do arquivo, e escolha o separador que as divide (normalmente _).

As partes disponíveis são:

Parte	O que representa
ID Operador	O número do operador.
Nome Operador	O nome de quem atendeu.
Data da Ligação	A data da ligação. Você escolhe em que formato ela está escrita.
Nome Cliente	O nome do cliente.
Telefone do Cliente	O número do cliente. É salvo como telefone da ligação.
Documento Cliente	O documento do cliente. Você escolhe o tipo (RG, passaporte, etc.).
ID Campanha	O número da campanha.
Direção	Se a ligação foi de entrada ou de saída.
Ignorar	Uma parte que aparece no nome mas que não interessa.

Por exemplo, com o separador _ e as partes ID Operador, Documento Cliente, Nome Operador, Data da Ligação e ID Campanha, um arquivo chamado 2060_DNI12345678_Ramiro Gumma_27052026_10.mp3 é lido assim: operador 2060, cliente com documento DNI 12345678, atendido por Ramiro Gumma, ligação de 27/05/2026, campanha 10.

A tela mostra um exemplo montado com as partes que você for escolhendo e, abaixo, os valores extraídos. Em Testar com um nome de arquivo você pode colar o nome de uma gravação real para ver quais dados o AuditorIA extrai (ou por que não corresponde) antes de salvar.

Quando uma parte traz algo colado na frente

Às vezes uma parte do nome vem com um dado extra colado na frente, sem o separador principal no meio. Por exemplo, em

1161967164_99_2811-Rodrigo Benitez_20260924-141636.WAV

a terceira parte é 2811-Rodrigo Benitez: o ramal (2811) e o vendedor juntos. Lida como está, a mesma pessoa em outro ramal (2823-Rodrigo Benitez) vira outro operador.

Para ficar só com o nome, preencha Descartar o anterior a nessa parte com o caractere que separa o que sobra (aqui, -). O AuditorIA descarta tudo até a primeira ocorrência desse caractere:

Parte no arquivo	É lida como
2811-Rodrigo Benitez	Rodrigo Benitez
2823-Rodrigo Benitez	Rodrigo Benitez (o mesmo operador)
2811-María-José Pérez	María-José Pérez (o nome pode ter hífens)

O que é descartado não é salvo em lugar nenhum. Leve em conta que:

• Se uma gravação não traz esse caractere nessa parte, ou não sobra nada depois dele (2811-), o arquivo conta como não correspondente e vale o que você escolher em O que acontece se um arquivo não corresponder.
• Não pode ser o separador principal nem contê-lo, e aceita até 3 caracteres.
• Funciona em qualquer parte (não só no nome do operador), exceto em Ignorar. Deixar vazio é não usar: o formato é lido como sempre.

Para esse exemplo, o formato completo é: separador _, partes Telefone do Cliente, Ignorar (linha), Nome Operador com Descartar o anterior a -, e Data da Ligação no formato YYYYMMDD-HHmmss. São salvos o telefone 1161967164, o vendedor Rodrigo Benitez e a data 24/09/2026 14:16:36; a linha e o ramal são descartados.

Arquivos reprocessados com texto extra no final

Se o servidor deixa cópias com algo acrescentado no final (..._20260908-153228_233014_ttjdse.WAV), a última parte absorve esse texto e a data não pode ser lida: esses arquivos contam como não correspondentes (operador incluído) e seguem a opção de O que acontece se um arquivo não corresponder. O telefone é mantido se Telefone do Cliente for a primeira parte do formato.

O telefone do cliente

Se a origem tem um formato de nomes, o telefone é lido só da parte Telefone do Cliente: se o formato não a tiver, a ligação fica sem telefone. Sem formato de nomes, continua sendo lido o número com que começa o nome do arquivo, como sempre. Por isso, se os seus arquivos começam com outro número (um ID de operador, por exemplo), definir o formato evita que esse número seja salvo como telefone.

Se você escolheu identificar o operador pela pasta

As partes de operador do nome do arquivo são ignoradas: a pasta prevalece. O restante (data, cliente, direção) continua sendo lido do nome do arquivo.

Se você não definir nenhum formato, as gravações são processadas do mesmo jeito, mas o AuditorIA não vai conseguir preencher esses dados sozinho.

O que acontece se um arquivo não corresponder

Sempre aparece algum arquivo com um nome diferente do esperado. Escolha o que fazer com eles:

• Processar mesmo assim, com valores padrão (recomendada): o áudio é transcrito do mesmo jeito. É atribuído o operador padrão e os demais dados ficam vazios.
• Ignorar o arquivo: o áudio não é processado. Se mais adiante você corrigir o nome no servidor, ele entra na próxima passagem.

Passo 5 - Salvar

Clique em Salvar. As alterações podem levar alguns minutos para fazer efeito: o serviço de sincronização as aplica na próxima passagem.

O que acontece depois

Com tudo configurado, cada gravação nova que aparecer na pasta do servidor:

1. É baixada pelo serviço de sincronização.
2. Fica atribuída a um operador, conforme o que você definiu.
3. Entra no AuditorIA como mais uma tarefa: aparece em Buscar e trabalhar com tarefas, é transcrita e fica pronta para revisar e auditar.

Para confirmar que ficou funcionando, aguarde alguns minutos e veja se aparecem tarefas novas nessa campanha.

Problemas frequentes

• O teste de conexão dá erro: verifique o endereço, a porta, o usuário e a senha. Se os dados estiverem corretos, consulte quem administra o servidor sobre se ele permite conexões do AuditorIA.
• O teste passa mas nenhum áudio entra: verifique o Caminho Remoto, já que o teste não o valida. Depois, confirme com quem administra a sua instalação que o serviço de sincronização está ativo.
• Os áudios entram com o operador errado: verifique de onde você indicou que ele deve tirar o operador (nome do arquivo ou pasta) e se o formato do nome corresponde aos seus arquivos reais.
• Foram criados operadores repetidos: acontece quando os nomes dos arquivos não coincidem com os operadores já cadastrados. Mude para Usar apenas operadores existentes e revise Gerenciar operadores locais.
• Faltam gravações: se você escolheu Ignorar o arquivo, as que não correspondem ao formato ficam de fora. Corrija o nome no servidor ou mude para Processar mesmo assim, com valores padrão.

Monitorar o serviço

Se o seu perfil tiver acesso, em Analytics > Serviço SFTP há um painel com o estado do serviço de sincronização. Serve para ver se ele está funcionando quando as gravações não entram.