Clientes API
Introdução
O Cliente de API do IXC ACS permite integrar a plataforma a sistemas externos, como ERPs, viabilizando automações e a troca de informações.
Além da integração genérica, também há uma integração específica com o IXC Provedor, voltada aos fluxos mais comuns, permitindo o envio de dados como PPPoE e informações de Wi-Fi.
Após o cadastro e a finalização da integração, a comunicação entre os sistemas ocorre de forma automática.
🔥 Gerenciamento sem Mistério
O que é um Cliente API?
API (Interface de Programação de Aplicações) é um conjunto de regras que permite que sistemas se comuniquem entre si de forma automática.
No IXC ACS, o Cliente API representa essa “ponte” de comunicação entre o ACS e outros sistemas, como ERPs, plataformas externas ou o próprio IXC Provedor.
Atenção
Para a integração com o IXC Provedor, é importante destacar que o cadastro do Cliente API no IXC ACS é apenas a primeira etapa do processo. Outras configurações são necessárias para que a integração funcione corretamente.
Acesso à funcionalidade
Caminho: Menu Ferramentas > Clientes API > Novo Cliente API
Configuração
Ao acessar a opção Novo Cliente API, será exibido um modal de configuração onde você define como o IXC ACS irá se comunicar com outro sistema.
Tipos de integração do Cliente API
Nesta etapa, você define com qual sistema o ACS irá se integrar. Atualmente, existem dois tipos de integração disponíveis:
1. Genérica
Utilizada quando o IXC ACS será integrado a sistemas de terceiros (exceto IXC Provedor), como ERPs ou plataformas externas. Nesse modelo, o sistema externo será responsável por consumir a API do ACS e receber os webhooks configurados.
Antes do passo a passo, veja abaixo os campos utilizados na criação do Cliente API genérico:
| Campo | Descrição |
|---|---|
| Nome | Identificação do Cliente API |
| Expiração do token | Tempo de validade do token em segundos. Após esse período, será necessário gerar um novo token para continuar utilizando a API |
| Requisições por minuto | Limite de chamadas à API permitidas por minuto |
| Requisições por dia | Limite de chamadas à API permitidas por dia |
| Webhook URL | Endereço do sistema externo que receberá as notificações do ACS |
| Certificado inválido | Define se o ACS aceitará enviar webhooks para uma URL com certificado SSL inválido |
| Webhooks emitidos | |
| Os webhooks representam eventos que o ACS envia automaticamente ao sistema externo quando algo acontece. Exemplos: | |
| • dispositivo adicionado ou removido | |
| • alteração de parâmetros do dispositivo | |
| • reset ou reboot | |
| • finalização de diagnóstico |
Por exemplo:
se um reboot for solicitado via API, quando o dispositivo reiniciar, o ACS enviará um webhook notificando o sistema externo. O mesmo conceito se aplica aos demais eventos.
Selecionar apenas os eventos necessários ajuda a reduzir tráfego e tornar a integração mais eficiente.
Configuração da integração de Cliente API genérica
-
No modal Criar Cliente API, selecione o tipo Genérica
-
Preencha o nome de identificação
-
Defina o tempo de expiração do token
-
Configure os limites de requisições por minuto e por dia
-
Ative o webhook e informe a URL do sistema externo
• Caso a URL utilize certificado SSL inválido, habilite a opção Certificado inválido -
Selecione os webhooks que serão emitidos
-
Clique em Criar Cliente API
Após a criação, é possível editar o Cliente API e definir suas permissões. Para isso, clique nos três pontos à direita do cliente criado e ajuste quais recursos da API ele poderá acessar.
2. IXC Provedor
A integração com o IXC Provedor exige configurações no IXC ACS e no IXC Provedor, realizadas em conjunto.
No IXC ACS
-
No modal Criar Cliente API, selecione o tipo IXC Provedor
-
Em Nome, informe algo que identifique claramente a integração, por exemplo: Integração IXC Provedor
-
No campo Chave pública, será necessário colar a chave que será gerada no IXC Provedor (veja os passos abaixo)
No IXC Provedor
-
Acesse Menu Sistema > Provedor > ACS > Integrações
-
Clique em Novo
-
Selecione a opção IXC ACS
-
Em nome, informe um identificador do ACS
-
Deixe o campo Usuário API em branco neste momento
-
Informe o domínio do servidor ACS (utilizando http)
-
Clique em Salvar
-
A chave pública será gerada. Copie essa chave
Retornando ao IXC ACS
-
Cole a chave pública no campo correspondente
-
No campo Webhook URI, informe o domínio do provedor seguido de
/api-module/acs/webhook
Exemplo:http://seuprovedor/api-module/acs/webhook -
Caso o certificado SSL seja inválido, habilite Certificado inválido
-
Clique em Criar Cliente API
-
Copie o ID do Cliente API gerado
Finalizando no IXC Provedor
-
Edite a integração criada
-
No campo Usuário API, cole o ID do Cliente API
-
Salve a configuração
Com essa etapa concluída, você poderá seguir para as próximas configurações da integração entre o IXC ACS e o IXC Provedor.
Para concluir a integração, acesse o conteúdo
Integração do IXC ACS com o IXC Provedor via API na Central de Ajuda.
Sobre a chave pública
Diferente do token, a chave pública não expira rapidamente e é utilizada para identificar o sistema parceiro durante a integração.
Glossário
| Termo | Descrição |
|---|---|
| Token | Chave de autenticação temporária utilizada para acessar a API |
| ERP | Sistema de gestão empresarial |
| Requisição | Cada chamada feita à API para enviar ou consultar informações |
| Webhook | Notificação automática enviada do ACS para outro sistema quando um evento ocorre |
| Webhook URI | Endereço que receberá as notificações do ACS |
| Certificado inválido | Permite que o ACS envie webhooks mesmo quando o certificado SSL do sistema externo não é válido |
Considerações finais
O Cliente API é a base para qualquer integração do IXC ACS com sistemas externos ou com o IXC Provedor. Ao configurar corretamente essa etapa inicial, você garante uma comunicação automática, segura e eficiente entre as plataformas, preparando o ambiente para as demais configurações da integração.