Invertus · v1 · setembro 2026

API de Ligações Invertus

Consulta das ligações atendidas e download das gravações, com metadados de agente, resultado e duração.

Visão geral

Uma API REST, respostas em JSON, autenticada por token. Cada ligação atendida e classificada por um de nossos agentes vira um registro aqui, junto com o áudio da conversa.

Há dois modos de trabalho, que podem ser usados juntos: consulta (você chama esta API quando quiser) e push (nós chamamos a sua API assim que a ligação fica pronta). Esta documentação cobre o modo de consulta; o push está descrito ao final.

URL base

https://api.ipbox.corpdata.com.br

Formato

JSON · UTF-8

Fuso dos horários

America/Sao_Paulo (UTC−3)

Janela disponível

Últimos 7 dias

Mantenha a URL base em configuração

Um segundo endereço deve ser ativado mais adiante para a mesma API. Nada além do host muda — token, endpoints e formato das respostas permanecem idênticos —, mas a troca fica mais simples se a URL base não estiver espalhada pelo código.

Autenticação

Todo pedido leva o token no cabeçalho Authorization, no esquema Bearer:

Authorization: Bearer <SEU_TOKEN>

O token é exclusivo da sua integração, entregue por canal separado desta documentação, e não expira. Ele dá acesso somente de leitura ao namespace /v1.

Guarde o token fora do código

Use variável de ambiente ou cofre de segredos. Ele identifica sua integração: se vazar, avise-nos e emitimos outro na hora — o antigo é revogado no mesmo instante.

Sem token, com token inválido, ou com token de outro escopo, a resposta é 401:

{
  "erro": "nao_autorizado",
  "mensagem": "Envie o cabeçalho Authorization: Bearer <token>."
}

Convenções

Identificador da ligação

O campo id é o protocolo gerado pela nossa central. É único, imutável e nunca reaproveitado — use-o como chave de deduplicação do seu lado. Exemplo: 1780000000000001.

Datas e horários

Todos os horários vêm no formato AAAA-MM-DDTHH:MM:SS, sem indicador de fuso, sempre em horário de Brasília (UTC−3). Não há horário de verão no Brasil desde 2019, então o deslocamento é fixo.

Nos parâmetros de filtro (desde, ate) aceitamos ISO 8601 com ou sem fuso; sem fuso, assumimos Brasília.

Três horários diferentes

Campo	Significa
`horario_inicio`	Momento em que a chamada foi atendida e a gravação começou
`horario_fim`	Fim da conversa — `horario_inicio` mais a duração
`datahistorico`	Momento em que o agente registrou o resultado, alguns segundos após o fim

Listar ligações

GET/v1/ligacoes

Devolve as ligações em ordem decrescente de datahistorico — mais recentes primeiro. Só entram ligações cuja gravação já está arquivada e pronta para download.

Parâmetros de consulta

Parâmetro	Obrig.	Descrição
`limite`	não	Itens por página. Padrão `50`, máximo `200`.
`cursor`	não	Cursor da página seguinte, copiado de `paginacao.proximo_cursor`.
`desde`	não	Só ligações a partir desta data/hora. Ex.: `2026-09-08T00:00:00`.
`ate`	não	Só ligações até esta data/hora.
`agente`	não	Login do agente. Ex.: `ana.ribeiro`.
`fila`	não	Nome exato da fila. Ex.: `Vendas Ativo`.
`resultado`	não	Descrição exata do resultado. Ex.: `Sem Interesse`.

Os filtros combinam entre si com e lógico. Comparações de texto são exatas, sem curinga.

Exemplo

curl -H "Authorization: Bearer <SEU_TOKEN>" \
  "https://api.ipbox.corpdata.com.br/v1/ligacoes?limite=2"

Resposta `200`

Os valores abaixo são fictícios, para ilustrar o formato.

{
  "ligacoes": [
    {
      "metadata": {
        "id": "1780000000000001",
        "id_ocorrencia": "1780000000000001",
        "funcionario_id": "42",
        "funcionario_nome": "Ana Ribeiro",
        "funcionario_email": null,
        "url_gravacao": "https://api.ipbox.corpdata.com.br/gravacao/1780000000000001?t=a1b2c3d4…",
        "datahistorico": "2026-09-08T17:48:11",
        "horario_inicio": "2026-09-08T17:47:33",
        "horario_fim": "2026-09-08T17:48:04",
        "duracao_gravacao": 31,
        "ocorrencia_codigo": "77",
        "ocorrencia_descricao": "Sem Interesse"
      }
    }
  ],
  "paginacao": {
    "limite": 2,
    "retornados": 2,
    "proximo_cursor": "MjAyNi0wOS0wOFQyMDo0Nzo0OS4wMDBafDE3ODAwMDAwMDAwMDAwMDI"
  },
  "retencao_dias": 7
}

Buscar uma ligação

GET/v1/ligacoes/{id}

Devolve uma única ligação, no mesmo formato { "metadata": { … } } — sem o envelope de lista.

curl -H "Authorization: Bearer <SEU_TOKEN>" \
  https://api.ipbox.corpdata.com.br/v1/ligacoes/1780000000000001

Responde 404 quando o id não existe ou já saiu da janela de 7 dias. Repare que a gravação continua acessível mesmo nesse caso — veja Gravações.

Baixar a gravação

GET/v1/ligacoes/{id}/audio

Responde 302 com um Location temporário apontando para o arquivo. Seu cliente HTTP precisa seguir redirecionamentos — no curl, a opção -L.

curl -L -H "Authorization: Bearer <SEU_TOKEN>" \
  https://api.ipbox.corpdata.com.br/v1/ligacoes/1780000000000001/audio \
  -o gravacao.wav

A URL de destino vale 1 hora e é gerada nova a cada chamada. Não a armazene: guarde o id e peça de novo quando precisar.

Não repasse o cabeçalho de autenticação no redirecionamento

A URL final é assinada e não deve receber o seu token. Algumas bibliotecas repassam cabeçalhos automaticamente ao seguir 302 — se a sua fizer isso, o armazenamento pode recusar a requisição. Configure para não propagar Authorization entre hosts diferentes.

Dados brutos da central

Para quem prefere processar por conta própria, estes endpoints entregam o registro como a central telefônica devolveu, sem a normalização aplicada em /v1/ligacoes. São treze campos, alguns sem equivalente no formato normalizado — código e CPF do cliente, número discado, lote de discagem e data de agendamento.

Um campo é reescrito, e o retorno avisa

O campo arquivo vem da central como uma URL que responde sem autenticação. Nós o substituímos pela URL assinada equivalente, que aponta para a mesma gravação sob nosso controle de acesso. Todos os demais campos vêm exatamente como a origem produziu, e a resposta declara a substituição no campo observacao.

GET/v1/brutos

Aceita os mesmos filtros de /v1/ligacoes — desde, ate, agente, fila, resultado, limite, cursor — mais audio_status.

Diferença importante: ao contrário de /v1/ligacoes, este endpoint não exige que a gravação já esteja arquivada. O registro da ligação existe mesmo quando o áudio ainda não foi baixado, e retê-lo por isso esconderia dado já disponível. Use arquivamento.disponivel para saber se o áudio pode ser buscado.

curl -H "Authorization: Bearer <SEU_TOKEN>" \
  "https://api.ipbox.corpdata.com.br/v1/brutos?limite=1"

{
  "origem": "IPBoX · relatório RQ4 (Resultado de Classificação de Chamadas)",
  "observacao": "O campo `arquivo` foi reescrito para uma URL assinada nossa; os demais vêm exatamente como a central devolveu.",
  "registros": [
    {
      "protocolo": "1780000000000001",
      "bruto": {
        "protocolo": "1780000000000001",
        "datahora": "08/09/2026 17:48:11",
        "agente": "ana.ribeiro",
        "fila": "Vendas Ativo",
        "lote": "LOTE 02",
        "nome": "EMPRESA EXEMPLO LTDA",
        "codigo": "00000000000191",
        "cpf": "",
        "numero": "51-90000-0000",
        "duracao": "00:00:31",
        "resultado": "Sem Interesse",
        "ficha_no": "",
        "data_agendamento": "",
        "arquivo": "https://api.ipbox.corpdata.com.br/gravacao/1780000000000001?t=a1b2c3d4…"
      },
      "arquivamento": { "status": "stored", "bytes": 493484, "disponivel": true },
      "coletado_em": "2026-09-09T13:02:11.482Z",
      "atualizado_em": "2026-09-09T13:02:11.482Z"
    }
  ],
  "paginacao": { "limite": 1, "retornados": 1, "proximo_cursor": "MjAyNi0wOS0w…" },
  "retencao_dias": 7
}

Os campos da origem

Campo	Descrição
`protocolo`	Identificador da ligação na central.
`datahora`	Classificação, no formato `DD/MM/AAAA HH:MM:SS` — note que difere do ISO usado no formato normalizado.
`agente`	Login do operador.
`fila`	Fila de atendimento.
`lote`	Lote de discagem (mailing) de onde veio o contato.
`nome`	Nome do cliente cadastrado.
`codigo`	Código do cliente no mailing — costuma ser CPF ou CNPJ.
`cpf`	CPF, quando cadastrado à parte.
`numero`	Número discado, formatado.
`duracao`	Duração como `HH:MM:SS`, não em segundos.
`resultado`	Classificação escolhida pelo agente.
`ficha_no`	Número da ficha, quando houver.
`data_agendamento`	Agendamento de retorno, quando houver.
`arquivo`	URL da gravação — reescrita, conforme a nota acima.

GET/v1/ligacoes/{id}/bruto

O mesmo registro, para uma ligação específica.

curl -H "Authorization: Bearer <SEU_TOKEN>" \
  https://api.ipbox.corpdata.com.br/v1/ligacoes/1780000000000001/bruto

Catálogos de referência

GET/v1/catalogos

As tabelas necessárias para interpretar o dado bruto: filas em operação, cadastro de agentes e o de-para de resultados.

O código do resultado depende da fila

Cada fila tem seu próprio catálogo, então a mesma descrição tem um código diferente em cada uma — Caixa Postal, por exemplo, tem doze códigos distintos. A chave é sempre o par (fila, descricao), nunca a descrição sozinha.

{
  "filas": ["Vendas Ativo", "Contatos", "URA Repescagem"],
  "resultados": [
    { "fila": "Vendas Ativo", "descricao": "Caixa Postal",
      "codigo": "104", "acao": "EX_PROSPECT" }
  ],
  "agentes": [
    { "login": "ana.ribeiro", "id_ipbox": "42", "nome": "Ana Ribeiro",
      "ramal": "6007", "tipo": "agente", "ativo": "Y" }
  ]
}

O catálogo é atualizado de hora em hora a partir da central.

O objeto ligação

Campo	Tipo	Descrição
`id`	string	Protocolo da ligação. Único e imutável — use como chave de deduplicação.
`id_ocorrencia`	string	Identificador do atendimento. Hoje repete o `id`; pode ser reconfigurado para o código do cliente ou o número da ficha, se preferirem.
`funcionario_id`	string · nulo	Id interno do agente. Nulo quando o agente já foi desligado e saiu do cadastro.
`funcionario_nome`	string · nulo	Nome do agente. Ver ressalvas.
`funcionario_email`	string · nulo	Hoje sempre nulo. Ver ressalvas.
`url_gravacao`	string	Link direto e permanente para o áudio, já assinado. Equivale ao endpoint `/audio` e dispensa token.
`datahistorico`	datetime	Momento do registro do resultado pelo agente.
`horario_inicio`	datetime	Início da conversa (atendimento).
`horario_fim`	datetime	Fim da conversa.
`duracao_gravacao`	inteiro	Duração em segundos.
`ocorrencia_codigo`	string · nulo	Código do resultado. Ver ressalvas.
`ocorrencia_descricao`	string	Resultado registrado pelo agente. Ex.: `Sem Interesse`, `Proposta Enviada`.

Campos podem ser acrescentados ao objeto sem aviso e sem mudança de versão. Ignore os que não conhecer, em vez de rejeitar a resposta inteira.

Paginação

A paginação é por cursor, não por página numerada. O motivo é prático: entram ligações novas a cada dois minutos, e no topo da lista. Com offset você pularia ou repetiria registros entre uma página e outra.

Cada resposta traz paginacao.proximo_cursor. Repasse-o como ?cursor= para pegar a página seguinte. Quando ele vier null, acabou.

# primeira página
GET /v1/ligacoes?limite=100

# seguintes, até proximo_cursor virar null
GET /v1/ligacoes?limite=100&cursor=MjAyNi0wOS0wOFQyMDo0Nzo0OS4wMDBafDE3ODAw…

Estratégia recomendada de sincronização

Guarde o datahistorico mais recente que você já processou. A cada ciclo, chame ?desde=<esse valor> e percorra os cursores até o fim. Deduplique por id: uma ligação pode reaparecer se o agente corrigir a classificação dentro da janela.

Erros

Erros têm sempre a mesma forma, com um erro estável para tratamento programático e uma mensagem legível.

{ "erro": "nao_encontrada", "mensagem": "Ligação 000000 não está na janela de 7 dias." }

HTTP	erro	Quando acontece	O que fazer
`401`	`nao_autorizado`	Token ausente, inválido ou de outro escopo	Conferir o cabeçalho. Não repetir sem corrigir.
`404`	`nao_encontrada`	Id inexistente ou fora da janela de 7 dias	Tratar como definitivo; não repetir.
`404`	`rota_inexistente`	Caminho ou método incorreto	Conferir a URL.
`409`	`indisponivel`	Gravação ainda em processo de arquivamento	Repetir em alguns minutos.
`5xx`	—	Falha nossa, temporária	Repetir com espera progressiva.

Gravações

Formato

WAV · PCM 16 bit

Amostragem

8 kHz · mono

Tamanho médio

≈ 1 MB por minuto

Disponibilidade

Permanente

É o áudio original da central telefônica, sem reprocessamento. A taxa de 8 kHz é o padrão da telefonia e serve bem para transcrição e análise de fala.

O áudio dura mais que o registro

Os metadados ficam disponíveis por 7 dias; a gravação, por tempo indeterminado. Uma url_gravacao recebida hoje continua funcionando depois que a ligação sai da listagem — inclusive meses depois.

Na prática: GET /v1/ligacoes/{id} passa a responder 404 após 7 dias, mas GET /v1/ligacoes/{id}/audio continua entregando o arquivo.

Se precisarem de MP3 ou Opus em vez de WAV — o que reduz o tamanho em cerca de dez vezes — conseguimos converter na origem. É só pedir.

Retenção e limites

Item	Valor	Observação
Janela de consulta	`7 dias`	Além disso, só o áudio permanece
Itens por página	`200`	Padrão 50
Validade do link de áudio	`1 hora`	Gerado novo a cada chamada
Atualização dos dados	`2 minutos`	Intervalo entre coletas na central
Limite de requisições	—	Sem limite fixo; avise-nos se for fazer volume alto

Uma ligação só existe depois de classificada

O registro aparece aqui quando o agente conclui o atendimento e escolhe o resultado — não quando a chamada termina. Se o agente demora a classificar, a ligação demora a aparecer. Isso é característica da central, não atraso da API.

Modo push

Em vez de vocês consultarem, nós entregamos: assim que a ligação é classificada e a gravação arquivada, fazemos um POST na URL que vocês indicarem, com exatamente o mesmo objeto metadata desta documentação — um por requisição.

POST https://api-de-voces.com.br/ligacoes
Content-Type: application/json
Authorization: Bearer <token de vocês>

{ "metadata": { /* mesmos campos da seção "O objeto ligação" */ } }

Latência típica de dois a três minutos após a classificação. Consideramos entregue qualquer resposta 2xx; qualquer outra coisa vira nova tentativa, com espera progressiva, até seis vezes. Requisições repetidas para o mesmo id são possíveis — trate a recepção como idempotente.

Para ligar, precisamos de: a URL de destino, o cabeçalho e o token de autenticação, e o comportamento esperado em caso de reenvio.

Campos com ressalva

Três campos do contrato não têm equivalente direto na central telefônica. Estão documentados aqui em vez de mascarados, porque afetam o que vocês recebem.

funcionario_email — sempre nulo

O cadastro da central tem o campo, mas ele está vazio para todos os agentes. Enquanto não for preenchido, não há origem para o dado. Duas saídas: preenchermos o cadastro na central, ou mantermos uma tabela de correspondência do nosso lado. Digam qual preferem.

funcionario_nome — derivado do login

A central guarda apenas o login (ana.ribeiro), não o nome completo. Formatamos para Ana Ribeiro, o que funciona bem na maioria dos casos mas não recupera nomes compostos nem acentuação. Se precisarem do nome exato, vale a mesma tabela de correspondência do item anterior.

ocorrencia_codigo — o código varia por fila

Na central, cada fila tem seu próprio catálogo de resultados. O mesmo resultado tem códigos diferentes conforme a fila: Caixa Postal, por exemplo, tem doze códigos distintos.

Hoje enviamos o código real da fila em que a ligação aconteceu — fiel à central. Se vocês esperam um catálogo estável, em que cada resultado tem um código só, conseguimos normalizar antes de enviar. É uma decisão de contrato e precisamos da resposta de vocês. Enquanto isso, ocorrencia_descricao é estável e serve como chave.

Aproximadamente 6% das ligações vêm com ocorrencia_codigo nulo — são as filas receptivas, que não expõem catálogo de resultados.

Suporte

Para dúvidas, mudança de contrato, rotação de token ou aumento de volume, falem com a equipe técnica da Invertus. Ao relatar um problema, incluam o id da ligação, o horário aproximado e a resposta completa que receberam — com isso rastreamos o caso ponta a ponta.