Roteiro: Homologar operadora ponta a ponta (operadora → tronco → rotas → publicar → shadow → chamada real)¶
Perfil necessário: admin
Menus usados: Roteamento, Plataforma, Operação
Risco: alto (publica plano de roteamento: todo tráfego casado passa a seguir o catálogo novo; erros de template/RN1/prioridade afetam produção imediatamente)
Rollback: em rascunho, basta corrigir/excluir o cadastro (nada mudou no runtime). Após Publicar plano: reativar a versão anterior do plano via POST /api/carrier-routing/plans/{plan_id}/activate (Swagger /api/docs) ou [Publicar plano] de novo após reverter os cadastros
Pré-requisitos¶
- [ ] Dados do carrier em mãos: RN1, host/porta do gateway (endpoint SIP), RN2, formato do R-URI, limites (canais/CPS), CLI wire format, headers especiais
- [ ] Números de teste: fixo e móvel, portado e não portado, no CN alvo
- [ ] Perfil admin (publicação de plano exige admin)
- [ ] Accesso ao banco para o shadow report (
mysql -u opensips -popensips)
Passo a passo¶
1. Criar a operadora¶
Siga o roteiro carrier-operator.md (aba Operadoras → [Nova Operadora]).
Ponto de atenção da homologação: enquanto em homologação, mantenha Ativa desligado ou os troncos fora de in_service — o plano só passa a usar a operadora quando ela entra no compile.
2. Criar o endpoint do gateway e o tronco¶
Cadastre o gateway em Roteamento → Endpoints ([Novo Endpoint]) e depois crie o tronco completo seguindo o roteiro carrier-trunk.md (aba Troncos → [Novo Tronco]).
Ponto de atenção da homologação: use o Número de exemplo (preview) do dialog do tronco para validar o R-URI renderizado contra o formato acordado antes de prosseguir. Estado do tronco durante a homologação: maintenance (ou quarantine) até o teste passar.
3. Criar as rotas por operadora¶
Crie as rotas seguindo o roteiro carrier-route.md (aba Rotas por Operadora → [Nova Rota]).
Ponto de atenção da homologação: cubra cada tipo de ligação contratado (LOC_FIX, LOC_MOB, LDN_FIX, VC2_MOB, VC3_MOB, LDI...) e deixe sempre uma rota coringa de fallback (Operadoras Destino (RN1) vazio) com prioridade pior que as específicas.
4. Criar headers (se a operadora exigir)¶
Siga o roteiro carrier-headers.md (aba Headers → [Nova Header Policy]).
5. Compilar (dry-run) e publicar o plano¶
Caminho: Roteamento → Operadoras e Troncos (topo da página)
Clique: [Simular compilação]

Resultado esperado: toast "Compilação OK — N regras, N trunks, N operadoras" (ou "Compilação coincide com plano ativo"). Warnings aparecem como toast amarelo; errors impedem a publicação (409 no publish).
Clique: [Publicar plano]

Confirme: dialog "Compila o catálogo atual, cria uma nova versão de plano e ativa. Confirma?" → [Publicar]
Resultado esperado: toast "Plano publicado — <versão> · N regras · N trunks" (ou "Plano já existente reativado" quando o checksum não mudou). O selo Plano publicado no topo mostra versão/data/regras/trunks ao clicar.
Importante — o que o publish NÃO faz: o plano versado (routing_plan_*) é lido pelo OpenSIPS direto do banco a cada decisão; não existe módulo MI de carrier routing para recarregar. O passo de reload abaixo é para os dados clássicos que podem ter mudado junto (dispatcher/address/dialplan) e para fechar a rotina padrão do projeto.
6. Recarregar os módulos OpenSIPS (rotina padrão)¶
Caminho: Plataforma → Sistema → Reload OpenSIPS
Clique: [Recarregar todos os módulos]

Resultado esperado: card de resultado verde com confirmação por módulo (address, dialplan, dispatcher) sem erro.
7. Rodar o shadow report¶
Com chamadas reais já fluindo (janela padrão de 48h; reduza @window_hours se precisar):
mysql -h 127.0.0.1 -u opensips -popensips < scripts/carrier_shadow_report.sql
Como ler:
1. Health summary por hora/status/call_type (carrier_routing_log) — procure all_failed/failed concentrados após a publicação
2. Shadow vs legacy por call-id — compara o trunk/carrier escolhido pelo plano com a rota legista registrada no call_log ($.route)
3. Blockers — razões de falha agrupadas por call_type (ex.: no_trunk_available, invalid_delivery_template)
4. Failover events — profundidade de tentativas (attempts) e motivos de retry
Critério: sem divergência inesperada entre plano novo e legado nos números de teste; no_trunk_available só para escopos deliberadamente não cobertos.
8. Validar classificação com números reais¶
Caminho: Roteamento → Testar Classificação
Clique: [Executar Teste]

Preencha: Número A (ex.: 5549999999999) e Número B portado e não portado do CN alvo.
Confira no resultado: Tipo de Chamada casando com as rotas criadas (ex.: LOC_MOB) e o CN/operadora do destino coerentes com o filtro RN1 das rotas. Complemente com o Simular roteamento da aba Rotas por Operadora — ele mostra a regra/tronco que o plano selecionaria para o número.
9. Colocar o tronco em serviço e fazer a chamada real¶
Caminho: Roteamento → Operadoras e Troncos → aba Troncos
Clique: ícone de edição do tronco em homologação
- Mude Estado para
in_service, confirme limites/CLI/template e [Salvar]. - Se a operadora ficou desativada no passo 1, abra o dialog dela e ligue Ativa.
- [Simular compilação] → [Publicar plano] → confirme [Publicar].
Faça a chamada de teste real e valide em Operação → CDR (abrir a chamada → fluxo SIP, estágio EGRESS): R-URI conforme o template do tronco, CLI no wire format acordado (From/PAI) e headers da policy presentes.

Confira o CDR: carrier/tronco de saída = operadora homologada, status final da chamada e route_name/contexto apontando para a rota nova.
Validação¶
- [ ] Operadora, tronco(s) e rotas visíveis nas abas com os valores acordados
- [ ] Simular compilação sem errors; warnings avaliados um a um
- [ ] Plano publicado: selo Plano publicado com versão nova e contagens esperadas
- [ ] Reload dos módulos sem erro (card verde em
Reload OpenSIPS) - [ ] Shadow report (
scripts/carrier_shadow_report.sql) sem divergência inesperada nem novosall_failed - [ ] Testar Classificação coerente (call type, portabilidade, RN1) para números portados e não portados
- [ ] Chamada real com 200 e CDR apontando operadora/tronco homologados
- [ ] CLI recebida no destino no formato acordado (E.164 ou nacional) e headers presentes
Erros comuns¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| Publish retorna 409 "Plano de roteamento inválido" | errors no compile (ex.: rota managed sem cobertura primária válida) | ler os errors no [Simular compilação], corrigir o cadastro e recompilar |
| Toast "N aviso(s) na compilação" | warnings (carrier desabilitado, endpoint sem sip_address, trunk sem cobertura gerenciada) |
avaliar cada warning; warning não bloqueia, mas costuma indicar tronco que não entrará no plano |
| Tronco homologado nunca selecionado | Estado ≠ in_service ou operadora desativada |
mudar estado/ativar operadora e [Publicar plano] |
| Rota nova não pega a chamada | prioridade coberta por rota anterior; RN1 filtrado ≠ RN1 da BDO | conferir ordenação Prioridade ↑ e o Simular roteamento |
| R-URI no destino ≠ acordado | template errado ou RN2 Override inesperado na cobertura | corrigir template/override no tronco/rota, publicar e retestar |
| CLI rejeitada pela operadora | Formato da CLI no wire divergente | alternar E.164/Nacional no tronco, publicar e retestar |
| Chamadas falham em massa após publicar | plano com coberturas incompletas | reativar plano anterior (POST /plans/{id}/activate) e corrigir cadastro antes de publicar de novo |
no_trunk_available no shadow report |
escopo sem cobertura (call type/RN1/CN) ou tronco em quarentena | criar cobertura coringa de fallback ou tirar tronco da quarentena |
Tabela de referência rápida¶
| Etapa | Onde | Botão/evidência |
|---|---|---|
| Operadora/tronco/rotas/headers | abas da página | [Nova Operadora] / [Novo Tronco] / [Nova Rota] / [Nova Header Policy] |
| Dry-run do plano | topo da página | [Simular compilação] |
| Ativar runtime | topo da página | [Publicar plano] → [Publicar] |
| Reload MI | Plataforma → Sistema → Reload OpenSIPS |
[Recarregar todos os módulos] |
| Shadow report | shell | mysql ... < scripts/carrier_shadow_report.sql |
| Classificação | Roteamento → Testar Classificação |
[Executar Teste] |
| Seleção do plano por número | aba Rotas por Operadora | [Simular roteamento] |
| Evidência final | Operação → CDR |
chamada com 200, EGRESS com R-URI/CLI/headers corretos |