Referência da API de Integração Interaflow

Endereço e versão

A base da API de Integração é /api/v1/integracao/v1, na origem HTTPS do seu ambiente. Nos exemplos, IF_BASE_URL representa essa origem, sem barra final, e IF_API_KEY representa uma chave válida.

O contrato tem versão 1.0. Confirme os endpoints da versão instalada pelo OpenAPI do ambiente:

GET /api/v1/integracao/v1/openapi.json
GET /api/v1/integracao/v1/docs

Essas duas rotas de documentação não exigem chave e não retornam dados de atendimento. Os endpoints abaixo exigem autenticação.

Autenticação e escopos

Use X-API-Key: ik_... ou Authorization: Bearer ik_.... A API de Integração exige chave de API; JWT de usuário não autentica nesta superfície.

O recorte é a organização da chave. pii:read complementa o escopo do recurso; não o substitui. Esse escopo não representa uma anonimização geral dos demais campos: telefone e referências de atendentes podem estar presentes nas respostas autorizadas.

Endpoints

Todos os caminhos da tabela são relativos a /api/v1/integracao/v1 e usam GET.

Os cadastros apoiam a interpretação dos registros. O cadastro de motivos de pausa não é um relatório de pausas realizadas.

Período e filtros

/ura/sessoes, /ura/etapas e /chamadas exigem inicio e fim em ISO 8601. O filtro considera o início da sessão ou ligação, inclui inicio e exclui fim. A janela máxima é de 31 dias. Sem fuso explícito, o servidor interpreta a data como UTC; prefira sempre informar o fuso.

Em /chamadas, limite conta ligações, e cada ligação retorna seus trechos. A lista itens pode ter mais elementos que o valor de limite. O filtro agente_id seleciona os trechos do atendente informado.

curl --get "$IF_BASE_URL/api/v1/integracao/v1/ura/sessoes" \
  -H "X-API-Key: $IF_API_KEY" \
  --data-urlencode "inicio=2026-10-01T00:00:00-03:00" \
  --data-urlencode "fim=2026-10-02T00:00:00-03:00" \
  --data-urlencode "limite=100"

Exemplo ilustrativo de uma página sem resultados:

{
  "versao": "1.0",
  "proximo_cursor": null,
  "tem_mais": false,
  "itens": []
}

Enquanto tem_mais for true, envie proximo_cursor no parâmetro cursor da próxima consulta. Não construa nem altere o cursor.

Como relacionar os dados

Uma ligação transferida pode ter vários trechos. Para contar ligações, agrupe por ligacao_id; para analisar passagens por fila ou atendente, use os trechos. O session_id pode estar ausente em chamadas que não passaram pela URA.

As sessões incluem referências de fluxo e campanha, horários, desfecho, saída, transbordo, passagem por fila e gravação quando disponíveis. As etapas descrevem nós percorridos, entradas, falhas de validação, tentativas de integração e transições. Consulte o OpenAPI para os campos completos e GET /listas para interpretar os valores fechados.

Gravações e dados em processamento

O bloco gravacao, quando disponível, pode trazer url, audio_url e url_expira_em. O link assinado permite acesso sem chave e vale por 24 horas no contrato atual. Trate-o como uma credencial temporária: não o publique nem o inclua em logs abertos. No navegador, url abre o player; audio_url solicita diretamente o áudio.

O download por /gravacoes/{session_id} usa chave com recordings:read. Áudio bruto é convertido para WAV; confira o Content-Type da resposta para o formato efetivamente retornado.

Uma chamada em andamento pode ter horários finais nulos. Gravação e classificação de desfecho podem ficar disponíveis depois. Reconsulte uma janela recente e atualize pelos identificadores estáveis. O filtro por início não equivale a um feed de alterações.

Erros e limites

O limite de requisições depende da chave e da configuração do ambiente. Não presuma um valor universal. Veja como criar e administrar chaves.

Escopo desta referência

Este contrato cobre consultas de dados e áudio. Monitoramento ao vivo, relatórios agregados de desempenho de agentes e comandos de discagem não fazem parte dos endpoints listados. Para responder conversas ou transferir a partir de um robô, use o protocolo de agentes externos.