Roteiro: Criar plano com franquias/allowances (PlansView)¶
Perfil necessário: admin (viewer só consulta) Menus usados: Comercial Risco: baixo no plano em si, médio em faturamento: a combinação escopo + franquias define o abate do consumo das linhas vinculadas Rollback: editar o plano/desativar o toggle Ativo, ou remover a franquia; ciclos já fechados não retroagem
Pré-requisitos¶
- [ ] Buckets de tarifação ativos conhecidos (
LOC_FIX,LOC_MOB,LDN_FIX,VC2_MOB,VC3_MOB,LDI,INB_*etc.) — são as opções do seletor de franquia - [ ] Definição comercial: mensalidade, escopo da franquia (por cliente ou por linha) e minutos por bucket
- [ ] Decisão de tarifação reversa (0800/0300) para habilitar franquias inbound
Passo a passo¶
1. Abrir a criação do plano¶
Caminho: Comercial → Planos
Clique: [Novo Plano]

Resultado esperado: dialog Novo Plano com Nome, Mensalidade, Escopo de Franquia, Descrição e toggles. A seção Franquias do Plano só aparece no modo edição (plano já salvo).
2. Preencher os dados do plano e salvar¶
Caminho: dialog Novo Plano
Clique: [Criar]

Preencha:
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| Nome * | sim | PBX-Local-2000 |
identificação comercial do plano |
| Mensalidade (R$) * | sim | 99,90 (2 decimais, ≥ 0) |
assinatura cobrada por ciclo |
| Escopo de Franquia * | sim | Por Cliente (default) ou Por Linha |
Por Linha multiplica a franquia pelo número de linhas ativas com o plano; Por Cliente é pool único |
| Descrição | não | texto livre | detalhes do plano |
| Ativo | não | toggle, default ligado | plano disponível para novas linhas |
| Habilitar tarifação reversa inbound (0800/0300) | não | toggle | ativa o uso das franquias inbound nos DIDs 0800/0300 da linha |
Resultado esperado: toast Plano criado, plano listado com Status Ativo, Escopo e Mensalidade.
3. Abrir o plano em edição para cadastrar as franquias¶
Caminho: Comercial → Planos
Clique: [Editar] na linha do plano

Resultado esperado: dialog Editar Plano agora exibe a seção Franquias do Plano com as tabelas Outbound e Inbound e o botão Novo Allowance.
4. Criar a franquia (allowance)¶
Caminho: dialog Editar Plano → Franquias do Plano
Clique: [Novo Allowance]

Preencha:
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| Bucket de tarifação * | sim | Outbound · Local Fixo (LOC_FIX), Inbound · ... (INB_*) |
tipo de tráfego que a franquia cobre; direção inbound só tem efeito com reverso habilitado e DID 0800/0300 |
| Minutos incluídos * | sim | 2000 (inteiro ≥ 0) |
tamanho da franquia mensal |
| Tarifa por minuto (R$) * | sim | 0,0500 (4–6 decimais, ≥ 0) |
preço do excedente do bucket |
| Segundos grátis * | sim | 0 (inteiro ≥ 0) |
segundos iniciais não cobrados por chamada |
| Incremento Inicial (seg) * | sim | 30 (≥ 1) |
primeiro bloco de cobrança |
| Incremento Após (seg) * | sim | 6 (≥ 1) |
bloco das cobranças seguintes |
| Estimativa de reserva (seg) | não | 600 (≥ 1) |
reserva estimada de saldo para o engine de tarifação |
Resultado esperado: form inline Nova Franquia abaixo das tabelas.
5. Salvar a franquia¶
Caminho: form inline da franquia Clique: [Criar]

Resultado esperado: toast Franquia criada, franquia listada na tabela Outbound (ou Inbound, conforme a direção do bucket); repetir por cada bucket coberto pelo plano.
Validação¶
- [ ] Visual: plano listado com Escopo e Mensalidade corretos; franquias visíveis em Outbound/Inbound no dialog de edição
- [ ] Funcional: linha vinculada ao plano (campo Plano (faturamento) na linha) abate o consumo do bucket certo — conferir em
Comercial → Tarifaçãoou no cartão Saldo e Utilização do Período do detalhe do cliente - [ ] Funcional: CDR de chamada de teste tarifa conforme tarifa/incrementos do bucket
Erros comuns¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| "Bucket é obrigatório" ao salvar franquia | seletor vazio | escolher o bucket na lista de rating buckets |
| Consumo não abate a franquia | bucket da chamada divergente do bucket da franquia (classificação) | conferir a classificação real no Testar Classificação |
| 422 "rating_bucket_code inválido" ao salvar | bucket inativo no banco | usar um bucket ativo da listagem |
| Franquia inbound ignorada | reverso desabilitado no plano ou DID sem serviço 0800/0300 | ligar o toggle de tarifação reversa e classificar o DID |
| Linha nova sem franquia esperada | escopo Por Linha com franquia calculada por linha ativa |
conferir quantidade de linhas ativas com o plano |
Tabela de referência rápida¶
| Botão | Onde | O que faz |
|---|---|---|
| [Novo Plano] | toolbar de Planos | abre o dialog de criação |
| [Criar] | rodapé do dialog / form de franquia | salva plano (POST /plans) ou franquia (POST /plans/<id>/allowances) |
| [Editar] | ações da linha na listagem | reabre o dialog com a seção Franquias |
| [Novo Allowance] | seção Franquias do Plano | abre o form inline de franquia |