API de Configuração 3CX

O Que é a API de Configuração?

A API de Configuração 3CX (XAPI), introduzida na Versão 20 do 3CX, oferece uma interface baseada em REST que permite o controle programático de quase todos os aspectos de configuração do sistema telefônico 3CX, replicando os recursos normalmente acessados por meio do console de administração. Criada com base nos padrões OData e nas especificações OpenAPI, essa API permite que os desenvolvedores integrem, automatizem e personalizem o ambiente 3CX com eficiência.

Principais Recursos da API de Configuração

  • Gerenciamento Abrangente: Com pontos de extremidade para gerenciar departamentos, usuários, encaminhamento de chamadas, ramais do sistema e outras configurações, a API permite que os usuários executem quase todas as ações administrativas de forma programática. Desde verificar se um departamento existe até configurar vagas de estacionamento compartilhadas, quase todos os elementos do 3CX podem ser gerenciados por meio de código.
  • Automação: A API permite a automação de tarefas administrativas comuns, como a criação de departamentos, a atribuição de funções de usuário e o gerenciamento de ramais. Isso reduz a necessidade de intervenção manual no console de administração, economizando tempo e minimizando a chance de erros.
  • Integração: A API facilita a integração perfeita do sistema telefônico 3CX com outros aplicativos comerciais. Você pode usá-la para sincronizar os dados do usuário, gerenciar departamentos e configurar o encaminhamento de chamadas para garantir uma interoperabilidade perfeita entre o 3CX e os serviços externos. A integração do 3CX em fluxos de trabalho mais amplos melhora a comunicação e a produtividade sem exigir sincronização manual.
  • Escalabilidade: Projetada com a escalabilidade em mente, a API permite o gerenciamento eficiente das configurações à medida que as organizações crescem, permitindo a fácil expansão de usuários, departamentos e outras entidades sem sobrecarga administrativa.

Configuração da Integração da API

No Admin Console do Cliente Web 3CX, vá para Integrações > API:

  1. Pressione o botão Add (Adicionar) para criar uma nova aplicação cliente.
  2. Especifique o ID do Cliente (DN para acessar o ponto de rota, que também é necessário para autorização).
  3. Se estiver usando o escopo de Configuração, marque a caixa de seleção Acesso à API de Configuração do 3CX para este aplicativo.
  4. Especifique o Departamento e a função do Diretório de Serviços, para obter o nível de acesso à API apropriado.
  5. Depois de criar com êxito uma nova instância de API, você receberá uma chave de API para seus aplicativos de terceiros. Essa chave será exibida apenas uma vez, portanto, não se esqueça de salvá-la para uso futuro.

Pronto! Você concluiu com êxito a configuração do PABX.

Observação: É necessário possuir uma licença IA de nível 8SC ou superior para utilizar a API de Configuração do 3CX.

Como Funciona

API RESTful

A API de Configuração do 3CX é uma API da Web RESTful criada com base no protocolo OData, oferecendo pontos de extremidade seguros e versáteis para gerenciar e configurar quase todos os aspectos do sistema 3CX. Essa API espelha a funcionalidade disponível no console de administração do 3CX, permitindo o controle programático sobre o gerenciamento de usuários, a configuração de departamentos, o encaminhamento de chamadas, os ramais do sistema e muito mais. Todos os pontos de extremidade são projetados para serem seguros e confiáveis, garantindo que não interfiram nas funções principais do PABX nem comprometam a estabilidade do sistema.

Para obter mais detalhes, consulte a Configuração 3CX da Especificação do Ponto de Extremidade da API.

Tokens de Autenticação

A API de Configuração oferece suporte a dois tipos de tokens para acesso seguro:

  • Tokens de Administrador de Várias Empresas: Permitir acesso total para gerenciar todos os departamentos e entidades no sistema 3CX, adequado para administradores em ambientes com várias empresas.
  • Tokens de Usuário: Conceder acesso limitado às funções atribuídas ao usuário e às permissões departamentais, fornecendo acesso controlado a tarefas de configuração específicas.

JSON e OpenAPI

Com sua especificação OpenAPI, a API de Configuração do 3CX é compatível com várias ferramentas de desenvolvimento, incluindo o Postman, para uma integração direta. A API aceita solicitações e respostas no formato JSON, o que facilita o trabalho dos desenvolvedores e a automatização das tarefas de configuração.

Processo de Autenticação

A API de Configuração do 3CX oferece suporte ao acesso seguro por meio de dois tipos de tokens de autenticação: Tokens de Administrador de Várias Empresas e Tokens de Usuário. Cada tipo de token fornece diferentes níveis de acesso, permitindo flexibilidade no gerenciamento de permissões em várias funções e departamentos dentro do ambiente 3CX.

Tokens

  • Especifique o Departamento e a Função nas suas Configurações Principais do Serviço. Definir uma função como “Proprietário do Sistema” ou “Administrador do Sistema” concederá direitos em todo o sistema. Outras funções terão direitos correspondentes.
  • Especifique o Departamento e a Função nas Configurações do Diretório de Serviços. Definir uma função como “Proprietário do Sistema” ou “Administrador do Sistema” concederá direitos em todo o sistema. Outras funções terão direitos correspondentes.
  • Como Obter:
  • Chame o ponto de extremidade /connect/token com uma solicitação POST com o tipo MIME application/x-www-form-urlencoded.

O corpo da solicitação deve conter:

client_id=[client_id_of_your_service_principal]

client_secret=[api_key_of_of_your_service_principal]

grant_type=client_credentials

Após a autenticação bem-sucedida, um token de acesso será retornado na resposta, que poderá ser usado para solicitações de API subsequentes.

  • Validade do Token: O token é válido por 60 minutos, após o qual precisará ser atualizado ou obtido novamente.

Uso de Tokens de Acesso

Depois de obter um token de acesso, inclua-o no cabeçalho Autorização de suas solicitações de API como um token Bearer:

Autorização: Bearer ACCESS_TOKEN

Teste Rápido - Validando a Autenticação por Token

Para verificar rapidamente se o token é válido e se a conexão com a API foi estabelecida corretamente, use o ponto de extremidade “Teste Rápido”:

  • Ponto de Extremidade: GET /xapi/v1/Defs?$select=Id
  • Resposta: Uma resposta 200 OK confirma a autenticação válida, e os cabeçalhos conterão a versão do sistema 3CX.

Notas Importantes

  • Expiração do Token: Todos os tokens de acesso expiram após uma hora. Os aplicativos devem lidar com a expiração do token reautenticando ou atualizando o token para manter uma conexão contínua.
  • Segurança: Sempre manuseie os tokens com segurança e evite expô-los no código do lado do cliente ou em locais de armazenamento não seguros.

Exemplo de Aplicação XAPI

Para obter etapas detalhadas sobre a Configuração de uma aplicação XAPI com a API de Configuração do PABX, consulte o Tutorial XAPI no repositório do Github. O exemplo abrange a funcionalidade básica e a demonstração das chamadas de API.

Veja também

Última Atualização

Este documento foi atualizado pela última vez em 23 de abril de 2026

https://www.3cx.com.br/docs/configuracao-api-3cx/