KatoCall logoKatoCall logoKatoCall EnglishEspañolPortuguêsFrançaisDeutschРусский中文日本語हिन्दीالعربية

O manual completo

Instale e configure para cursar chamadas

Um guia em linguagem simples para instalar o KatoCall num servidor e pô-lo a faturar chamadas reais. Siga as partes por ordem — não é preciso experiência em telecomunicações.

Versão 1.0.0Para servidores Debian 12~30–45 min até à primeira chamada

Comece aqui

Como o KatoCall funciona, em dois minutos

O KatoCall é uma central telefónica com um motor de faturação embutido. Os seus clientes fazem chamadas através dele; ele verifica o saldo, escolhe a rota de saída mais barata, cronometra a chamada e fatura-a — automaticamente.

O seu cliente faz uma chamada KatoCall verifica o saldo, escolhe a rota mais barata, cronometra e fatura A sua operadora (tronco SIP) Qualquer um marca encaminha As chamadas recebidas funcionam da mesma forma ao contrário: um número (um DID) toca e é reencaminhado para um cliente.
Toda chamada — recebida ou efetuada — passa pelo KatoCall, onde ocorre a faturação.

De onde vem o seu lucro

Compra minutos a uma operadora a um preço e vende-os aos clientes por um preço maior. O KatoCall guarda ambos e mantém a diferença em cada chamada.

Paga à operadora
$0.0090
tarifa do fornecedor, por minuto
Cobra ao cliente
$0.0150
tarifa do cliente, por minuto
Fica com
$0.0060
a sua margem, automaticamente

Bom saber: O KatoCall não converte moedas. Escolha uma moeda em Definições (o dólar americano é a predefinida) e use-a para comprar e vender, para que cada margem seja uma simples subtração.

Parte 1

Instale num servidor

Faz-se uma só vez, num servidor novo. Se alguém técnico preparar o servidor por si, entregue-lhe esta parte.

O que precisa primeiro

Um servidorDebian 12 (Bookworm), 64 bits — acabado de instalar. Serve qualquer VPS decente (OVH, Hetzner, DigitalOcean, Vultr).
Tamanho2 núcleos de CPU, 4 GB de RAM, 20 GB de disco. 2 GB de RAM é o mínimo.
Um IP públicoO servidor precisa do seu próprio endereço na internet — a sua fornecedora dá-lho.
Acesso ao servidorA palavra-passe de root, ou um utilizador com sudo.
Da sua operadoraUm tronco SIP (o host, e um IP autorizado ou um utilizador/palavra-passe), mais os números (DID) que tiver.
Um nome de domínio (opcional)Só se quiser o cadeado https. Pode começar sem um e adicioná-lo depois.

Faça a instalação

Copie katocall-1.0.0.tar.gz para o servidor e execute estes comandos um a um. Cada um mostra o que faz e para com uma mensagem clara se faltar algo.

  1. Descompacte e verifique o servidor

    O primeiro comando não altera nada — confirma que o servidor está pronto e avisa se faltar algo.

    root@your-server
    # unpack the package
tar -xzf katocall-1.0.0.tar.gz
cd katocall-1.0.0

# verifica o servidor (seguro — não altera nada)
sudo bash install/00-preflight.sh

  2. Execute os scripts de instalação por ordem

    Execute-os um a um. O número 01 compila o motor telefónico e demora 10–20 minutos; os restantes são rápidos.

    root@your-server
    sudo bash install/01-install-asterisk.sh   # o motor telefónico (10–20 min)
sudo bash install/02-install-base-stack.sh
sudo bash install/03-setup-admin-panel.sh
sudo bash install/04-configure-ami.sh
sudo bash install/05-production-hardening.sh
sudo bash install/06-configure-did-forwarding.sh
sudo bash install/07-configure-fail2ban.sh
sudo bash install/08-configure-nat.sh
sudo bash install/09-configure-outbound.sh
sudo bash install/11-configure-backups.sh
sudo bash install/12-configure-dialer.sh   # só se quiser o discador

    Do 01 ao 09 são obrigatórios. O passo 12 é só para o discador — ignore-o e tudo o resto continua a funcionar.

  3. Confirme que está tudo saudável

    Corre cerca de 65 verificações — cada serviço, a firewall, os backups, a segurança — e indica o que corrigir no que falhar.

    root@your-server
    sudo bash install/verify.sh

PASS 66   WARN 1   FAIL 0

  4. Entre pela primeira vez

    Abra o endereço do servidor num navegador e inicie sessão. Obriga a mudar a palavra-passe de imediato — nada funciona até a definir.

    • Endereço: http://your-server-address/
    • Utilizador: admin
    • Palavra-passe (tem de a mudar já): Katocall

Antes de chamadas reais: ative o HTTPS. Até o fazer, o painel usa http sem cifra e o seu login viaja pela internet desprotegido. Quando um domínio apontar para o servidor, execute:

sudo bash install/10-configure-tls.sh panel.yourcompany.com you@yourcompany.com

Parte 2

Configure para cursar chamadas

Já está no painel. Crie estas seis coisas por esta ordem — cada uma usa a anterior. Está tudo no menu à esquerda.

1SuppliersA quem compra minutos
2Rate CardsOs seus preços de compra e venda
3TrunksA linha com a sua operadora
4Routing GroupsQue linha para cada chamada
5AccountsOs seus clientes
6DIDsNúmeros recebidos

  1. Suppliers — a quem compra minutos

    Um fornecedor (Supplier) é uma operadora a quem compra minutos. Comece aqui porque tudo o resto aponta para ele. Abra Suppliers → New Supplier e dê-lhe um nome.

    DashboardSuppliersRatesTrunksAccounts
    Suppliers+ New Supplier
    e.g. IDT Gold
    USD — $ US Dollar▾
    Account manager, contract terms…
    Suppliers → New Supplier

  2. Rate Cards — os seus preços de compra e venda

    Uma tabela de tarifas (Rate Card) é uma lista de preços, uma linha por destino (um prefixo como 1 para os EUA ou 44 para o Reino Unido). Crie dois tipos:

    • Provider Rates — o que o seu fornecedor lhe cobra.
    • Customer Rates — o que cobra aos clientes (mais alto — essa diferença é o seu lucro).

    Não escreva centenas de prefixos: abra a tabela e clique em Import CSV para carregar o ficheiro de preços da operadora de uma vez.

    DashboardSuppliersRatesTrunksAccounts
    USA Wholesale — ProviderImport CSV
    DestinationPrefixPer min
    United States1$0.0090
    United Kingdom44$0.0110
    Mexico Mobile521$0.0180
    Rates → Import CSV

    Bom saber: As tarifas são guardadas com 4 casas decimais; um ficheiro com 5 casas é arredondado na importação.

  3. Trunks — a linha real com a sua operadora

    Um tronco (Trunk) é a ligação ativa a um fornecedor. Abra Trunks → New Trunk. Importam duas coisas:

    • Direction — Outbound (saída), Inbound (entrada) ou Both (ambas).
    • Authentication — IP-based (confiam no endereço do seu servidor) ou Username/Password (deram-lhe dados de acesso SIP).

    Depois de guardar, use Test Call para confirmar que marca antes de encaminhar clientes para ele.

    DashboardSuppliersRatesTrunksAccounts
    New TrunkSave
    IDT-GOLD
    Outbound▾
    IP-based▾
    sip.idtgold.com
    30
    Trunks → New Trunk

    O nome de um tronco não pode ter espaços — use IDT-GOLD, não IDT GOLD.

  4. Routing Groups — que linha para cada chamada

    Um grupo de encaminhamento diz: para este tipo de número, tenta estes troncos, por esta ordem. Dois ajustes:

    • Priority — o mais baixo é tentado primeiro. Ponha a operadora mais barata na prioridade 1.
    • Weight — reparte o tráfego entre troncos com a mesma prioridade.

    Se o primeiro tronco estiver ocupado ou falhar, o KatoCall passa ao seguinte. Use Preview para escrever um número e ver que tronco usaria.

    DashboardTrunksRouting GroupsAccounts
    Standard LCR+ Add Route
    TrunkPriorityWeight
    IDT-GOLD1 first100
    Backup-Carrier2100
    Routing Groups → Add Route

  5. Accounts — os seus clientes

    Uma conta (Account) é um cliente. Abra Accounts → New Account. As escolhas importantes:

    • Billing Type — Prepaid (carregam saldo; as chamadas param a zero) ou Postpaid (faturado depois).
    • Rate Card — a lista de preços de cliente do passo 2.
    • Routing Group — como saem as chamadas, do passo 4.
    • Como se ligam — um IP autorizado, ou um utilizador e palavra-passe para o telefone/PBX.
    DashboardTrunksRouting GroupsAccounts
    New AccountSave
    Acme Telecom
    Prepaid▾
    $250.00
    USA Retail▾
    Standard LCR▾
    Accounts → New Account

    Bom saber: Toda conta que faz chamadas de saída precisa de uma Rate Card de cliente que cubra os prefixos que vende — caso contrário essas chamadas são recusadas (nunca faturadas a zero).

  6. DIDs — números que tocam para dentro

    Um DID é um número para o qual as pessoas ligam para contactar um dos seus clientes. Abra a conta, vá a DIDs → Add DID, escreva o número e para onde reencaminha. (Guarde a conta primeiro.)

    DashboardTrunksAccountsSettings
    Acme Telecom · DIDs+ Add DID
    DID NumberForwards To
    +1 305 555 0100Acme main lineactive
    Accounts → DIDs → Add DID

Cada campo do painel tem um pequeno ? ao lado que explica para que serve, nos dez idiomas. Settings → Network envia a sua configuração para o motor telefónico após grandes alterações.

Parte 3

Execute uma campanha do discador

O discador liga para uma lista de números, reproduz uma mensagem gravada e deixa as pessoas premir uma tecla para serem ligadas, pedir retorno de chamada ou sair. É preciso fazer antes o passo 12 da instalação.

Perceba o que é: é um discador de potência (power dialer), não preditivo. Sem deteção de atendedor de chamadas (o voicemail conta como atendido) e sem ritmo automático — você define um número fixo de chamadas simultâneas. Funciona num servidor de cada vez.

  1. Crie a campanha

    Abra Dialer Campaigns → New Campaign. Escolha a conta a que fatura, dê-lhe um nome e defina o ritmo: Max Concurrent Calls, Max Attempts e o Retry gap.

    DashboardAccountsDialer CampaignsAgents
    New CampaignSave
    Acme Telecom▾
    10
    3
    Upload a .wav / .mp3…
    Dialer Campaigns → New Campaign

  2. Adicione a mensagem e o menu

    Carregue a Prerecorded Message que toca ao atender. Depois monte o IVR Menu — o que cada tecla faz:

    • Premir 1 → transferir para um agente
    • Premir 2 → pedir retorno de chamada
    • Premir 9 → adicionar a Do-Not-Call (nunca mais marcado)

  3. Carregue os seus contactos

    Na secção Contacts da campanha, clique em Upload CSV — um ficheiro simples de números de telefone.

  4. Prima Start — e leia os resultados

    Prima Start e começa a marcar em segundos; Pause para tão depressa. No fim, Download Results dá um ficheiro com o que aconteceu a cada número.

    DashboardAccountsDialer CampaignsAgents
    Spring PromoStart
    Phone NumberAttemptsResult
    +1 305 555 00001answered
    +1 305 555 00012no answer
    +1 305 555 00021transferred
    A campanha preenche um resultado para cada número.

Parte 4

Operação diária

Quatro comandos cobrem quase tudo o que fará no servidor.

root@your-server
sudo bash install/verify.sh            # está tudo saudável?
sudo /usr/local/sbin/katocall-backup    # faça um backup agora
sudo bash install/upgrade.sh           # aplique uma versão mais recente
sudo bash install/uninstall.sh         # remova-o (mantém os dados)

Os seus backups estão no mesmo disco que protegem. Copie-os para outro lado com regularidade, ou uma falha de disco leva os dados e o único backup juntos.

Antes de confiar num relatório de receitas, pode provar que as contas batem certo ao cêntimo:

sudo -u softswitch admin/backend/venv/bin/python admin/backend/manage.py verify_ledger

Parte 5

Quando algo corre mal

«Não foi possível contactar o servidor» ao iniciar sessão.
Um serviço pode estar a reiniciar. Espere e recarregue. Se persistir, execute install/verify.sh — aponta o serviço exato que está em baixo.
Uma chamada não liga.
Verifique três coisas por ordem: a Account tem saldo e Rate Card; o Routing Group tem um tronco para esse destino (use Preview); o Test Call do tronco funciona.
Fui bloqueado depois de errar a palavra-passe.
O KatoCall bloqueia um endereço após várias falhas, de propósito. Espere que o bloqueio expire, ou remova-o na página IP Bans a partir de outro dispositivo.
O meu discador diz «Running» mas não marca nada.
Provavelmente saltou o passo 12 da instalação. Execute install/12-configure-dialer.sh e depois install/verify.sh.
A coluna de margem está vazia.
A moeda do cliente e a do tronco diferem. O KatoCall não converte moedas — compre e venda numa só moeda e a margem aparece.

Seja qual for o problema, sudo bash install/verify.sh é a primeira coisa a executar. Verifica ~65 coisas e indica o script a re-executar.