📄Gerenciamento de Filas de Atendimento

📄 API Reference: Manage Queue (Gerenciamento de Filas de Atendimento)

Esta API permite a consulta, criação, atualização e exclusão de Filas de Atendimento (Queues) no sistema Voipper, incluindo o gerenciamento dos ramais (devices/membros) atrelados a cada fila.

🔐 Autenticação e Permissões

Todas as requisições requerem autenticação válida (via Token/Key na URL ou Header).

Regras de Hierarquia:

Nível 4 (Assinantes): Têm acesso restrito apenas às filas da sua própria conta. O sistema ignora IDs de clientes de terceiros informados na URL ou no corpo da requisição.
Nível 2 (Revendas): Podem interagir com filas dos clientes atrelados à sua hierarquia.

📍 Endpoints e Parâmetros de Rota

Diferente de outras APIs do sistema, o parâmetro principal na URL ({id}) refere-se ao ID do Cliente (Assinante), enquanto o ID da Fila específica deve ser passado como um parâmetro de query (?id_record=).


Método	Endpoint	Descrição
GET	`/api/manageQueue/{id_cliente}?id_record={id_fila}`	Lista todas as filas do cliente ou uma fila específica.
PUT	`/api/manageQueue/{id_cliente}`	Cria uma nova Fila de Atendimento.
POST	`/api/manageQueue/{id_cliente}?id_record={id_fila}`	Atualiza uma Fila de Atendimento existente.
DELETE	`/api/manageQueue/{id_cliente}?id_record={id_fila}`	Exclui uma Fila de Atendimento.

(Nota: Para Assinantes / Nível 4, o {id_cliente} na URL pode ser preenchido com 0, pois o sistema detectará automaticamente o ID da própria conta logada).

📥 1. Consultar Filas (GET)

Retorna a listagem de Filas de Atendimento e os detalhes dos ramais que são membros delas.

Parâmetro de URL: id_cliente (Obrigatório para Admin/Revenda. Opcional para Assinante).
Parâmetro de Query: id_record (Opcional. Se não for enviado, listará todas as filas do cliente).

Exemplo de Retorno (Sucesso)

{
   "error": 0,
   "reason": "OK",
   "records": 1,
   "data": [
      {
         "id": 943,
         "id_cliente": 119,
         "descricao": "Atendimento Comercial",
         "strategy": "ringall",
         "musiconhold": "custom",
         "announce": {
            "id": 903,
            "descricao": "Bem-vindo_Comercial"
         },
         "announce_frequency": 0,
         "timeout": 3600,
         "queue_type": 0,
         "id_backup1": 919,
         "status": 1,
         "devices": [
            {
               "id_ramal": "920",
               "ramal": "PJSIP/ramal1001",
               "status_ramal": "1"
            }
         ]
      }
   ]
}

📤 2. Criar ou Atualizar Fila (PUT / POST)

O payload deve ser enviado em formato JSON.

O método PUT exige os dados mínimos para criação (como descricao).
O método POST permite a atualização parcial de campos isolados.

📋 Dicionário de Dados (Payload JSON)

Identificação e Estratégia


Campo	Tipo	Obrigatório (PUT)?	Descrição
`id_cliente`	Inteiro	Sim (p/ Admin/Revenda)	ID do assinante dono da fila.
`descricao`	String	Sim	Nome da Fila (Ex: "Suporte N1").
`strategy`	String	Não	Estratégia de distribuição. Valores suportados: `ringall`, `leastrecent`, `fewestcalls`, `random`, `rrmemory`. Padrão: `random`.
`queue_type`	Inteiro	Não	Tipo de membros: `1` (Ramais Locais) ou `2` (Agentes Dinâmicos).

Áudios e Anúncios


Campo	Tipo	Descrição
`musiconhold`	String	Música de espera da fila. Envie `"custom"` para usar a playlist do cliente ou `"default"` para a música do sistema.
`announce`	Objeto	Áudio de entrada da fila. Obrigatório o envio no formato de objeto com a chave id: `{"id": ID_DO_AUDIO}`.
`announce_frequency`	Inteiro	Frequência (em segundos) que a posição ou tempo será anunciada.
`announce_holdtime`	Inteiro	Anunciar o tempo estimado de espera? (`0` = Não, `1` = Sim).
`announce_position`	Inteiro	Anunciar a posição do cliente na fila? (`0` = Não, `1` = Sim).
`play_agent_audio`	Inteiro	ID de um áudio (Sussurro) tocado para o agente antes de conectar a chamada ao cliente.

Tempos e Regras (Timers)


Campo	Tipo	Descrição
`timeout`	Inteiro	Tempo máximo de espera na fila (em segundos) antes do transbordo.
`retry`	Inteiro	Tempo de pausa entre tentativas de chamar os ramais (em segundos).
`wrapuptime`	Inteiro	Tempo de "respiro" do agente após finalizar uma chamada (em segundos).
`reportholdtime`	Inteiro	O agente ouvirá o tempo que o cliente esperou? (`0` ou `1`).
`ringinuse`	Inteiro	Tocar para o ramal mesmo que ele já esteja em uso? (`0` ou `1`).

Transbordo, Membros e Status


Campo	Tipo	Descrição
`id_backup1`	Inteiro	ID de outra Fila para usar como Transbordo (caso o cliente atinja o `timeout` sem atendimento).
`devices`	Array de Int	Lista de IDs dos ramais que fazem parte da fila. (Nota: no Update, a API substitui a lista inteira pelos IDs informados neste array).
`status`	Inteiro	Status da Fila (`0` = Inativa, `1` = Ativa). Padrão: `1`.

Exemplo de Payload de Criação (PUT) ou Atualização (POST)

{
   "descricao": "Atendimento Comercial",
   "strategy": "ringall",
   "musiconhold": "custom",
   "announce": {
      "id": 903
   },
   "timeout": 120,
   "retry": 15,
   "wrapuptime": 5,
   "id_backup1": 919,
   "devices": [920, 921, 925],
   "status": 1
}

❌ 3. Excluir Fila (DELETE)

Remove permanentemente a Fila de Atendimento do sistema.

Parâmetro de Rota ({id}): ID do cliente (Obrigatório, use 0 se a API for chamada por credencial de Assinante).
Parâmetro de Query (?id_record=): Obrigatório - ID interno da Fila a ser deletada.

Exemplo de Chamada de Exclusão: DELETE /api/manageQueue/119?id_record=943

⚠️ Códigos de Retorno e Erros Comuns

As respostas de erro seguem o padrão JSON abaixo:

{
   "error": 1,
   "reason": "CODIGO_DO_ERRO",
   "message": "Descrição amigável do erro."
}


Código (reason)	Motivo	Resolução
`RECORD_NOT_FOUND`	A Fila informada não foi encontrada ou não pertence ao cliente.	Verifique se você passou o `?id_record=` na URL para métodos POST, GET ou DELETE.
`INVALID_CUSTOMER`	ID do cliente não foi enviado na rota (Admin/Revenda).	Passe o ID do cliente na rota `{id_cliente}` ou no payload.
`CUSTOMER_NOT_FOUND`	Cliente / Assinante informado na criação não foi encontrado.	Valide o `customer_id`.
`INVALID_DATA`	Dados obrigatórios ausentes.	Certifique-se de enviar o campo `descricao` no PUT.
`MALFORMED_REQUEST`	Sintaxe JSON incorreta ou tipos de dados inválidos.	Verifique se Arrays e Objetos (como o `announce`) foram passados corretamente.

Notas de Sistema (Comportamento Automático): > * Reload do Asterisk: Qualquer alteração, inserção de membros (devices) ou exclusão na fila executará o comando queue reload all no sistema para aplicar as regras em tempo real no PBX.

Sobrescrita de Membros: Ao atualizar os membros da fila via POST, o array devices substitui integralmente a configuração anterior. Se desejar adicionar um ramal, você deve enviar o array contendo os ramais existentes + o ramal novo.

Auditoria: Todas as mudanças disparam um log de segurança no módulo "API - Gerenciar Filas de Atendimento".