Relatório de Erros de Chamada (CDR Error)

Esta documentação descreve o endpoint /api/cdrError/{id}, responsável por fornecer o Relatório de Registro de Detalhes de Chamadas (CDR) com foco exclusivo nas ligações que falharam ou geraram erros de entrega.

O endpoint fornece uma listagem detalhada de cada tentativa de chamada frustrada, além de um bloco contendo os totais agregados (estatísticas) do período consultado.

🔐 Autenticação e Visibilidade

Autenticação Obrigatória: A requisição será recusada (NO_AUTH) se não houver um token/sessão válida.
Controle de Acesso Hierárquico: O banco de dados filtra automaticamente os registros com base no nível do usuário que faz a chamada:
- Nível 4 (Assinante): Só tem acesso às suas próprias ligações com erro.
- Nível 2 (Revenda): Acesso a todos os clientes vinculados à sua revenda. Pode filtrar por um cliente específico.
- Nível 1 (Master/Admin): Acesso total. Pode filtrar por qualquer cliente ou provedor (rota).

📍 Endpoint

Método	Rota	Descrição
GET	`/api/cdrError/{id}`	Retorna as estatísticas e listagem de chamadas com erro.

(Nota: O parâmetro {id} na URL refere-se ao ID do Cliente que se deseja filtrar).

📥 Parâmetros da Requisição

Os parâmetros de filtro são enviados através da Query String (URL) ou Path. Caso as datas não sejam informadas, a API assumirá, por padrão, as chamadas do dia de hoje (de 00:00:00 a 23:59:59).

Parâmetros de Rota (Path)

Campo	Tipo	Descrição
`id`	Inteiro	ID do Cliente (Assinante). Envie `0` para buscar todos os clientes permitidos no seu nível, ou o ID específico para filtrar. (Ignorado para Nível 4).

Parâmetros de Filtro (Query String)

Campo	Tipo	Padrão	Descrição
`id_provider`	Inteiro	`0`	Filtra por ID do Provedor (Rota). Disponível apenas para Nível 1 (Master).
`date_ini`	String	Data de hoje	Data inicial da busca no formato `YYYY-MM-DD`.
`date_end`	String	Data de hoje	Data final da busca no formato `YYYY-MM-DD`.
`time_ini`	String	`00:00:00`	Hora inicial da busca no formato `HH:MM:SS`.
`time_end`	String	`23:59:59`	Hora final da busca no formato `HH:MM:SS`.
`limit`	Inteiro	Padrão da API	Limite de registros a serem retornados na paginação.
`offset`	Inteiro	`0`	Ponto de partida para a paginação (salto de registros).

📤 Estrutura de Resposta (Response)

O retorno, em formato JSON, é dividido em duas partes principais:

totals: Um bloco estatístico do período consultado.
data: O array contendo a lista dos registros com suas respectivas causas de desconexão.

Exemplo de Resposta (Sucesso - HTTP 200)

{
  "error": 0,
  "reason": "OK",
  "limit": 100,
  "offset": 0,
  "records": 2,
  "totals": {
    "total_records": 150,
    "total_404": 12,
    "total_noanswer": 45,
    "total_busy": 60,
    "total_cancel": 13,
    "total_congestion": 20
  },
  "data": [
    {
      "id": 84592,
      "customer_id": 15,
      "provider_id": 3,
      "calldate": "2023-10-25 14:32:01",
      "callerid": "1001",
      "source": "1001",
      "destination": "5511999999999",
      "city": "SÃO PAULO",
      "type": "Movel Local",
      "disposition": "BUSY",
      "hangup_desc": "User busy",
      "is_404": 0,
      "ip_address": "192.168.1.50",
      "useragent": "Grandstream GXP1625"
    },
    {
      "id": 84593,
      "customer_id": 15,
      "provider_id": 3,
      "calldate": "2023-10-25 14:45:10",
      "callerid": "1002",
      "source": "1002",
      "destination": "5511000000000",
      "city": "SÃO PAULO",
      "type": "Fixo Local",
      "disposition": "404 NOT FOUND",
      "hangup_desc": "Unallocated (unassigned) number",
      "is_404": 1,
      "ip_address": "192.168.1.51",
      "useragent": "Zoiper"
    }
  ]
}

📋 Dicionário de Dados do Retorno

Bloco `totals` (Estatísticas do Período)

Representa a soma agregada de todos os erros que ocorreram no período filtrado, independentemente da paginação.

total_records: Quantidade total de chamadas com erro.
total_404: Soma de chamadas não encontradas / número inexistente (Erro 404).
total_noanswer: Soma de chamadas não atendidas.
total_busy: Soma de chamadas onde o destino estava ocupado.
total_cancel: Soma de chamadas canceladas pelo originador antes do atendimento.
total_congestion: Soma de chamadas perdidas por problemas de rota, falha de infraestrutura ou congestionamento.

Bloco `data` (Detalhes da Chamada)

id (int): ID único do registro de erro.
customer_id (int): ID do cliente/assinante associado à chamada.
provider_id (int): ID da rota/provedor utilizada (se aplicável).
calldate (string): Data e hora da ocorrência (YYYY-MM-DD HH:MM:SS).
callerid (string): Bina / Nome de quem originou a chamada (codificado em HTML entities).
source (string): Número ou ramal de origem.
destination (string): Número de destino (limpo, sem formatações).
city (string): Cidade do destino da chamada.
type (string): Tipo de tarifação identificada (Ex: Fixo Local, Movel LDN).
disposition (string): Status SIP macro. Se a flag is_404 for verdadeira, a API força o valor "404 NOT FOUND", caso contrário exibe o status bruto (ex: "BUSY", "NOANSWER", "CANCEL").
hangup_desc (string): Motivo textual detalhado do desligamento / Código Q.850 de ISDN.
is_404 (int): Retorna 1 caso seja um número não alocado/inexistente, e 0 para outros motivos.
ip_address (string): Endereço IP público do equipamento que gerou a ligação.
useragent (string): Identificação do equipamento ou softphone utilizado.