Roteiro: Criar rota por operadora (match da chamada, operadoras destino RN1 e troncos)¶
Perfil necessário: admin
Menus usados: Roteamento
Risco: alto (a rota decide qual tronco completa cada chamada de saída; prioridade/filtro errado desvia tráfego ou derruba rotas de contingência — vale a partir do próximo Publicar plano)
Rollback: desligar o toggle Rota ativa (ou excluir a rota) e [Publicar plano] de novo; para voltar atrás numa publicação, reativar a versão anterior via POST /api/carrier-routing/plans/{plan_id}/activate (Swagger)
Pré-requisitos¶
- [ ] Operadoras destino com RN1 cadastradas (roteiro
carrier-operator.md) — o filtro Operadoras Destino (RN1) lista só operadoras com RN1 preenchido - [ ] Troncos ativos criados (roteiro
carrier-trunk.md), preferencialmentein_service— no máximo duas operadoras diferentes de troncos por rota (a 1ª vira operadora principal e a 2ª o fallback) - [ ] Tipos de ligação (call types) que a rota deve cobrir:
LOC_FIX,LOC_MOB,LDN_FIX,VC2_MOB,VC3_MOB,LDI,CNG,SUP - [ ] Saber se a rota restringe por portabilidade (BDO) e por DDD destino/origem
Passo a passo¶
1. Abrir a aba Rotas por Operadora¶
Caminho: Roteamento → Operadoras e Troncos → aba Rotas por Operadora
Clique: [Rotas por Operadora] (tab do topo da página)

Resultado esperado: simulador de roteamento no topo (DDD Origem, Número Destino, [Simular roteamento]) e a listagem de rotas com filtros de Operadora destino/Call Type/Status e ordenação por Prioridade.
2. Abrir o dialog Nova Rota por Operadora¶
Clique: [Nova Rota] (toolbar da listagem)

Resultado esperado: dialog Nova Rota por Operadora abre com prioridade default 100, tipos default LOC_FIX e uma linha de tronco vazia no fieldset Troncos que cobrem esta rota.
3. Preencher prioridade, tipos de ligação e status¶
Preencha (linha 1 do formulário):
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| Prioridade * | sim (default 100) |
inteiro ≥ 0 | Desempate entre rotas que casam a mesma chamada: menor número = mais prioritária |
| Tipos de Ligação * | sim (default LOC_FIX) |
multi-select: LOC_FIX, LOC_MOB, LDN_FIX, VC2_MOB, VC3_MOB, LDI, CNG, SUP |
A API expande a rota em coberturas por tipo selecionado — não precisa duplicar cadastro por tipo |
| Rota ativa | sim (default ligado) | toggle | Desligada, a rota é ignorada no próximo compile do plano |
4. Preencher os filtros da chamada (janela de aplicação)¶
Fieldset Filtros da chamada — todos opcionais; vazio = não restringe:
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| DDD destino (B) | não | 11, 49 (2 dígitos) |
Só casa chamadas com esse DDD no número B |
| DDD origem (A) | não | 11, 49 (2 dígitos) |
Só casa chamadas originadas nesse DDD |
| Operadoras Destino (RN1) | não | multi-select (ex.: TIM Wholesale (15)) |
A rota só casa quando o rn1_out da BDO for o RN1 de uma operadora selecionada. Vazio = qualquer RN1 (rota coringa/fallback). Se a BDO devolver RN1 diferente do filtrado, a chamada não usa os troncos da rota |
| Portabilidade | sim (default Qualquer) |
Qualquer · Portado (sim) · Não portado |
Casa só quando o BDO indicar (ou não) portabilidade do destino |
5. Vincular os troncos que cobrem a rota¶
Fieldset Troncos que cobrem esta rota — cada linha define um tronco elegível:
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| Tronco * | sim por linha ativa | select (ex.: vivo-sp-01) |
Tronco que pode completar a chamada; a operadora dele determina operadora principal/fallback da rota |
| Prefixo B | não | 5511 |
Restringe a cobertura pelo início do número destino (LIKE prefix%) |
| B-CN | não | 11 (2 dígitos) |
Restringe a cobertura pelo DDD do destino |
| RN2 Override | não | 0301 |
Sobrescreve o RN2 default do tronco só nesta rota (usado no token __RN2__) |
| Prioridade | sim (default 100) |
inteiro ≥ 0 | Ordem entre os troncos da rota |
| Peso Custo | sim (default 1.000) |
decimal 3 casas | Informativo/analítico; hoje não participa da seleção runtime |
| Ativa | sim (default ligado) | toggle | Cobertura desligada não entra no plano |
Clique: [Adicionar tronco] para incluir mais linhas (ex.: tronco da operadora fallback).
Clique: [Criar] (rodapé do dialog; [Salvar] quando editando)
Resultado esperado: toast "Rota salva. Publique o plano para ativar."; a rota aparece na listagem ordenada por Prioridade ↑, com colunas de operadoras destino (RN1), call type, DDDs, troncos e tag Ativa.
Restrição de validação: a rota exige pelo menos um tronco ativo (toda cobertura ativa precisa de tronco) e aceita no máximo duas operadoras entre os troncos ativos — a inferência vira
target_carrier_id+fallback_carrier_id. Repita o roteiro para cobrir outros tipos de ligação/CNs.
6. Conferir o plano antes de publicar¶
Clique: [Simular roteamento] no topo da aba, informando DDD Origem (ex.: 49) e Número Destino (ex.: 5549999999999)
Resultado esperado: resultado com tipo de chamada, número B em E.164, DDD B, RN1 (com operadora da BDO) e a regra/tronco que a rota nova selecionou. Avisos de compilação aparecem expandíveis (Ver todos os avisos, Detalhe da compilação).
Clique: [Simular compilação] (topo da página) para o dry-run do plano (regras/trunks/operadoras + warnings/errors, sem gravar nada).
Salvar rota não muda chamada em andamento: o runtime só troca no [Publicar plano] (roteiro
carrier-homologation.md).
Validação¶
- [ ] Visual: rota listada com ordem de prioridade correta e tag Ativa = Sim
- [ ] Visual: Simular compilação sem errors; warnings conhecidos avaliados (ex.: carrier desabilitado, cobertura sem match)
- [ ] Funcional: Simular roteamento retorna a regra/tronco da rota nova para um número do escopo, e não retorna para um número fora dele
- [ ] Funcional: após publicar, chamada real cai na rota nova (
route_name/carriers no CDR)
Erros comuns¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| "Selecione pelo menos um tipo de ligação" | Tipos de Ligação vazio | selecionar ao menos um call type |
| "Adicione pelo menos um tronco ativo" / "Toda cobertura ativa precisa ter tronco" | coberturas sem tronco ou todas desligadas | preencher o Tronco de cada linha ativa |
| "Use no máximo dois carriers por rota: ..." | troncos ativos de 3+ operadoras diferentes | deixar no máximo 2 operadoras (principal + fallback); criar rotas separadas |
| Rota nunca casada | rota de prioridade melhor cobre o mesmo escopo (ex.: coringa com prioridade menor) | reordenar prioridades (menor = primeiro) e conferir a ordenação Prioridade ↑ |
| Chamada não usa os troncos da rota | BDO devolveu RN1 fora do filtro Operadoras Destino (RN1) | ampliar a seleção de operadoras ou deixar vazio (coringa) |
| Rota não aplica depois de salvar | plano não publicado | [Publicar plano] no topo da página |
| Chamada cai no fallback inesperado | tronco principal em quarentena/fora de serviço | conferir Estado dos troncos na aba Troncos e republicar |
Tabela de referência rápida¶
| Ação | Onde | Botão |
|---|---|---|
| Criar rota | aba Rotas por Operadora | [Nova Rota] → [Criar] |
| Testar seleção sem publicar | topo da aba | [Simular roteamento] |
| Dry-run do plano | topo da página | [Simular compilação] |
| Ativar/desativar rota | dialog da rota | toggle Rota ativa → [Salvar] → [Publicar plano] |
| Excluir rota | linha da tabela | ícone de exclusão → [OK] → [Publicar plano] |
| Copiar rotas de outra operadora | (matrix/clone na aba de rotas) | dialog Clonar rotas entre operadoras → [Clonar] |