Dúvidas sobre API REST de Controle de Chamadas e API WebSocket na v20 Enterprise para Discador Externo

[Suporte03]

Olá comunidade 3CX,

Estamos desenvolvendo uma aplicação de discador externo em Node.js e precisamos de ajuda para integrar com nossa instância do 3CX Versão 20.0 Enterprise (20.0.0.6486)

Configuração Atual:

• Criamos uma "Aplicação API" no Admin Console do Web Client (Admin > Integrações > API).
• Client ID: 012987
• As caixas "Acesso à API de Configuração do 3CX (XAPI)" e "Acesso à API de Controle de Chamadas 3CX" estão marcadas.
• Função atribuída: Administrador do Sistema.
• Ramal associado (para Controle de Chamadas): 1007 (este é o ramal do nosso agente de teste).

O que já funciona:

1. Conseguimos obter um token Bearer de acesso via POST {{PBX_FQDN}}/connect/token (usando client_id e client_secret), conforme a documentação da XAPI de Configuração.
2. Este token nos permite acessar endpoints da XAPI, como GET /xapi/v1/Defs?$select=Id (retorna 200 OK).
3. Conseguimos estabelecer uma conexão WebSocket com wss://{{PBX_FQDN}}/callcontrol/ws utilizando o mesmo token Bearer da XAPI no header Authorization durante o handshake.

Desafios e Perguntas (Foco no Controle de Chamadas em Tempo Real):

Estamos tentando implementar um fluxo onde o discador liga para um cliente e, somente quando o cliente atende, a chamada é transferida para um ramal de agente. Para isso, e para monitoramento, temos as seguintes dúvidas:

1. Originar Chamada de um Route Point para Cliente Externo (via REST API):
   
   • Qual é o endpoint REST HTTP exato e o formato do corpo JSON para instruir o 3CX a iniciar uma chamada de um Route Point (ex: ramal virtual 888) para um número de cliente externo?
   • A autenticação para este endpoint é feita com o token Bearer da XAPI?
2. Obter deviceId de um Ramal de Agente (via REST API):
   
   • Para usar o endpoint POST /callcontrol/{dn}/devices/{deviceId}/makecall (mencionado em artigos do blog), precisamos do deviceId. Qual é o endpoint REST HTTP para listar os dispositivos de um ramal e obter seus device_id? Como ele é autenticado?
   • (Conseguimos fazer chamadas usando POST /callcontrol/{dn}/devices/{deviceId}/makecall quando tínhamos o deviceId e o token XAPI pareceu funcionar, mas obter o deviceId de forma programática é o desafio).
3. Transferir Chamada Ativa para Agente (via REST API):
   
   • Após a chamada (Route Point -> Cliente) ser atendida, qual é o endpoint REST HTTP e o formato do corpo JSON para transferir essa chamada para um ramal de agente? Autenticação?
4. Subscrição de Eventos WebSocket:
   
   • Nossa conexão WebSocket é estabelecida, mas ao tentar nos "inscrever" para eventos (ex: enviando { "RequestID": "...", "Path": "/callcontrol/888" } onde 888 é nosso Route Point), recebemos uma resposta do WebSocket com StatusCode: 403 (Forbidden).
   • Qual é o formato JSON exato da mensagem de subscrição para receber eventos de chamada de um DN específico (como um Route Point) ou de todas as chamadas?
   • O token XAPI é suficiente para autorizar essa subscrição, ou precisa de escopos/permissões adicionais, ou a mensagem de subscrição está incorreta?
5. Listar Todas as Chamadas Ativas (Snapshot via REST):
   
   • Tentamos GET {{PBX_FQDN}}/callcontrol com o token XAPI e recebemos 200 OK com uma lista de DNs e seus participantes. Isso é ótimo!
   • Tentamos GET {{PBX_FQDN}}/callcontrol/calls com o token XAPI e recebemos 403 Forbidden.
   • Existe um endpoint REST oficial e recomendado para obter um "snapshot" de todas as chamadas ativas (similar ao antigo /ActiveCalls da Call API da v18)? Ou o GET /callcontrol é a forma correta e o 403 no /calls indica que /calls não é o endpoint correto ou requer permissões diferentes?

Estamos procurando a "3CX Call Control API Endpoint Specification" para a v20 ou qualquer documentação/exemplo que detalhe a API REST para controle de chamadas em tempo real e a API WebSocket (especialmente autenticação, subscrição e formato de eventos).

Qualquer ajuda, link para documentação, ou exemplos de como interagir com essas funcionalidades na v20 usando um cliente HTTP externo (Node.js/JavaScript, cURL, Postman) seria imensamente apreciada!

Obrigado!

---