VoIP Client SDK

Cliente Python para a API interna (Laravel Nova) de painéis VoIP. Permite realizar automações de CRUD de usuários, ramais (subscribers), busca de DIDs, e extração de dados do dashboard.

Estrutura do Projeto

O repositório está organizado de forma a separar o código da biblioteca dos artefatos de apoio e desenvolvimento:

voip_client/
├── voip_client/                  ← O pacote Python (código-fonte da biblioteca)
│   ├── __init__.py
│   ├── __main__.py
│   ├── client.py
│   ├── auth.py
│   ├── transport.py
│   ├── resources.py
│   ├── users.py
│   ├── subscribers.py
│   ├── dids.py
│   ├── dashboard.py
│   ├── exceptions.py
│   ├── py.typed
│   └── cli.py
│
├── tests/                        ← Testes automatizados e smoke test
│   ├── test_voip_client.py
│   └── smoke_test.py
│
├── examples/                     ← Scripts de exemplo de uso
│   └── basic_usage.py
│
├── pyproject.toml                ← Metadados e dependências do pacote
├── requirements.txt               ← Alternativa simples de dependências
├── INSTRUCOES_ATUALIZACAO.md      ← Guia de manutenção, testes e release
├── README.md                     ← Esta documentação
├── .gitlab-ci.yml                 ← Pipeline CI/CD GitLab
├── .gitignore                     ← Arquivos ignorados pelo Git
└── .env.example                    ← Modelo de variáveis de ambiente

Instalação

Instalação via PyPI

pip install voip-client-sdk

Instalação de Desenvolvimento

Para instalar o pacote em modo editável junto com as dependências de teste e desenvolvimento:

pip install -e ".[dev]"

Instalação Simples

Para instalar apenas as dependências de execução básicas:

pip install -r requirements.txt

Configuração

Copie o arquivo .env.example para .env e preencha as variáveis de ambiente necessárias:

cp .env.example .env

Edite o arquivo .env:

VOIP_BASE_URL=https://voip.suaempresa.com.br
VOIP_EMAIL=seu_email@empresa.com.br
VOIP_PASSWORD=sua_senha_secreta

Como Usar

Biblioteca Python

Você pode importar e utilizar o cliente em seus scripts Python. Veja o exemplo em examples/basic_usage.py para uma demonstração completa:

import os
from voip_client import VoipClient

# Conectar e autenticar (lê automaticamente VOIP_EMAIL e VOIP_PASSWORD das env vars)
with VoipClient(base_url="https://voip.suaempresa.com.br") as client:
    # Buscar dados do dashboard
    dados = client.get_dashboard(range_days=30)
    print(dados)

Manipulação de Cookies (Ex.: Banco de Dados)

Se você preferir persistir a sessão em um banco de dados em vez do arquivo cookies.txt, o cliente expõe a propriedade cookies e aceita o parâmetro initial_cookies:

from voip_client import VoipClient

# Carrega cookies previamente salvos do seu banco de dados
cookies_salvos = obter_cookies_do_banco()  # Deve retornar um Dict[str, str] ou None

with VoipClient(
    base_url="https://voip.suaempresa.com.br",
    initial_cookies=cookies_salvos,
) as client:
    # O cliente usará os cookies informados. Se forem válidos, não realizará login de novo.
    dados = client.get_dashboard()
    
    # Ao final da execução, armazene os cookies atualizados no banco
    cookies_atualizados = client.cookies
    salvar_cookies_no_banco(cookies_atualizados)

Interface de Linha de Comando (CLI)

O pacote também pode ser executado diretamente via terminal:

# Ajuda geral
voip-client --help

# Efetuar login e gerar/atualizar cookies.txt
voip-client --base-url "https://voip.suaempresa.com.br" login

# Consultar o dashboard
voip-client --base-url "https://voip.suaempresa.com.br" dashboard --range 30

# Rodar um teste CRUD completo (Smoke Test) contra o painel
voip-client --base-url "https://voip.suaempresa.com.br" crud-test --did-mask "0113"

Executando os Testes

Os testes unitários utilizam mocks para evitar chamadas de rede reais, rodando instantaneamente:

pytest tests/

⚠️ Aviso de Segurança

verify_ssl

O parâmetro verify_ssl controla se o certificado TLS do servidor é validado. O padrão é True (seguro). Use verify_ssl=False somente em ambientes de homologação com certificado autoassinado e nunca em produção — desabilitar a validação expõe credenciais de login e cookies de sessão a ataques MITM.

# ✅ Produção (padrão seguro)
client = VoipClient(base_url="https://voip.empresa.com.br")

# ⚠️  Homologação com certificado autoassinado
client = VoipClient(base_url="https://homolog.empresa.com.br", verify_ssl=False)

Senhas de ramais no dashboard

O método get_dashboard() não inclui senhas de ramais por padrão. Para obter as senhas, passe include_passwords=True explicitamente:

# Padrão: sem senhas (recomendado para uso geral / logging)
dados = client.get_dashboard()

# Com senhas: use somente quando necessário e nunca logue o resultado
dados_com_senhas = client.get_dashboard(include_passwords=True)

Dados sensíveis em logs

Campos como password e cpf são automaticamente mascarados (***) nas mensagens de erro geradas pelo cliente. Ainda assim, evite logar em nível DEBUG em produção, pois outros dados de resposta (como tokens) podem aparecer.