Ir para o conteúdo

Roteiro: Criar tronco de operadora completo (endpoint, RN2, entrega, limites, CLI, quarentena)

Perfil necessário: admin Menus usados: Roteamento Risco: alto (o tronco define para onde o tráfego de saída sai; um endpoint/RN2/template errado quebra o destino das chamadas casadas pelas rotas — e o efeito vale a partir do próximo Publicar plano) Rollback: mudar Estado do tronco para out_of_service (ou quarantine) e [Salvar]; para desfazer a publicação, reativar a versão anterior do plano via POST /api/carrier-routing/plans/{plan_id}/activate (Swagger) e publicar de novo

Pré-requisitos

  • [ ] Operadora dona do tronco já criada (roteiro carrier-operator.md)
  • [ ] Endpoint SIP do gateway da operadora já cadastrado em Roteamento → Endpoints (o tronco referencia o endpoint; é ele que guarda o IP:porta SIP)
  • [ ] Do lado da operadora: RN2 acordado, formato do número no R-URI, limites contratados (canais/CPS), formato da CLI no wire (E.164 ou nacional) e códigos SIP para failover
  • [ ] Se a operadora exige RN3/CSP: valores acordados (ex.: RN3 060)

Passo a passo

1. Abrir a aba Troncos

Caminho: Roteamento → Operadoras e Troncos → aba Troncos Clique: [Troncos] (tab do topo da página)

Aba Troncos da página Operadoras e Troncos

Resultado esperado: listagem de troncos com colunas Nome, Operadora, RN2, Formato RN2, Template, RN3, Endpoint, Estado, Failover SIP, Quarentena e Prio/Peso.

2. Abrir o dialog Novo Tronco

Clique: [Novo Tronco] (toolbar da listagem)

Botão Novo Tronco destacado na aba Troncos

Resultado esperado: dialog Novo Tronco (largura total) abre.

3. Preencher identificação e destino SIP

Preencha (linha 1 do formulário):

Campo Obrig. Formato/exemplo Efeito
Nome * sim vivo-sp-01 Identificador único do tronco; aparece em logs, CDR e na seleção de troncos das rotas
Operadora * sim select (ex.: TIM Wholesale) Operadora dona do tronco; é o que casa a rota com o RN1 no compile do plano
Endpoint * sim select (ex.: gw1.carrier:5060) Endpoint SIP (IP:porta ou FQDN) para onde as chamadas deste tronco serão enviadas — o "host/porta" real fica no cadastro do endpoint

4. Preencher RN2 e estado

Preencha (linhas 2 e 3):

Campo Obrig. Formato/exemplo Efeito
RN2 Prefix não 15 Cifra RN2 interna que identifica o tronco no R-URI de saída (convenção nossa, não da Anatel); alimente o token __RN2__ do template. Pode ser sobrescrito por rota via RN2 Override
Formato RN2 sim (com default) prefix_with_zero (default) · prefix_raw · header_only · none Como o RN2 entra no R-URI: com 0 antes do número, colado direto, só em header ou não enviado
Estado sim (com default) in_service (default) · out_of_service · quarantine · maintenance Só tronco in_service entra no plano compilado. Tronco recém-homologado ou suspeito pode ficar em quarantine/maintenance de propósito
SIP Profile não select (ex.: udp-5060) Socket SIP de saída usado para este tronco; vazio usa o default
Prioridade sim (default 100) inteiro ≥ 0 Ordem do tronco dentro da operadora no cascade (menor = primeiro)
Peso sim (default 1) inteiro ≥ 1 Desempate entre troncos de mesma prioridade

5. Preencher limites e failover

Preencha:

Campo Obrig. Formato/exemplo Efeito
Max Concurrent não (default 0) 300 Limite de chamadas simultâneas do tronco; 0 = ilimitado
Max CPS não (default 0) 10 Limite de chamadas por segundo; 0 = ilimitado
Códigos SIP para failover não CSV, ex.: 408,500,502,503,504 Respostas SIP que fazem a chamada tentar o próximo tronco. Vazio usa carrier_routing.default_retry_on_codes em Configurações. Inclua 404 aqui quando o tronco puder transbordar Not Found

6. Configurar quarentena automática (opcional)

Preencha:

Campo Obrig. Formato/exemplo Efeito
Quarentena automática não toggle (default desligado) Falhas SIP retryable consecutivas dentro da janela tiram o tronco da seleção pelo período configurado
Falhas se quarentena on 3 (default) Nº de falhas para disparar quarentena (≥ 1)
Janela (s) se quarentena on 60 (default) Janela de contagem das falhas em segundos (≥ 1)
Duração (s) se quarentena on 60 (default) Tempo fora da seleção (≥ 1)

7. Definir o formato de entrega (wire format do R-URI)

O Formato de Entrega (Template) é o user-part do R-URI enviado à operadora e vale para todas as rotas deste tronco.

Preencha:

Campo Obrig. Formato/exemplo Efeito
Formato de Entrega (Template) * sim __RN2____DEST_E164__ (default) Template com tokens: __RN2__, __RN1__, __RN3__, __CSP__, __CN__, __DEST_E164__, __DEST_NATIONAL__, __DEST_LOCAL__. Deve começar com __RN2__, conter um __DEST_*__ e gerar só dígitos. Tokens adjacentes precisam de 4 underscores: __RN3____DEST_NATIONAL__
Presets rápidos não select (ex.: Padrão E164, Nacional com 0) Preenche o template com um formato comum
Enviar RN3 não toggle (default desligado) Emite __RN3__ (indicador de portabilidade) só em chamada portada; o template precisa conter __RN3__
RN3 se Enviar RN3 on 060 (default) Valor do RN3 na chamada portada
CSP não 14 Código de Seleção de Prestadora; o template precisa conter __CSP__
Formato da CLI no wire sim (com default) E.164 (55DDDNUMERO) (default) · Nacional (DDDNUMERO, sem 55) Formato exigido pela operadora no From/PAI. Policy/CDR continuam E.164 independente daqui

Use o preview: informe o Número de exemplo (preview) (default 5549991385477), alterne o toggle Portada e confira o Preview (ex.: 5549991385477 para o padrão E164). O preview é o juiz da homologação — o resultado tem que bater com o formato acordado com a operadora.

Clique: [Criar] (rodapé do dialog; [Salvar] quando editando)

Resultado esperado: toast "Tronco salvo com sucesso", dialog fecha e o tronco aparece na listagem com Estado in_service (ou o estado escolhido) e Failover SIP mostrando os códigos ou "padrão".

Como na operadora: salvar é draft. O tronco só afeta chamadas depois de [Publicar plano] (roteiro carrier-homologation.md).

Validação

  • [ ] Visual: tronco listado na aba Troncos com operadora, template e estado corretos
  • [ ] Visual: preview do template gera só dígitos e bate com o formato acordado
  • [ ] Funcional: Simular compilação (topo da página) não reporta warning de endpoint sem sip_address para este tronco
  • [ ] Funcional: após publicar, uma chamada casada pela rota sai com R-URI igual ao preview (conferir em Operação → CDR → fluxo SIP, estágio EGRESS)

Erros comuns

Sintoma Causa provável Correção
"Nome é obrigatório" / "Operadora é obrigatória" / "Endpoint é obrigatório" campos obrigatórios vazios preencher antes de Criar
"Template deve começar com RN2" template editado na mão recomeçar por um Presets rápidos e ajustar
"Template deve conter DEST_E164, DEST_NATIONAL ou DEST_LOCAL" falta o token do destino incluir o token __DEST_*__
"Template deve gerar somente dígitos" / "Template contém token inválido" texto fora de token (ex.: +, #) remover caracteres não numéricos; template só aceita dígitos no render
"Use códigos SIP de 3 dígitos separados por vírgula" / "Use códigos entre 300 e 699" CSV de failover inválido corrigir para códigos de 3 dígitos entre 300–699
"Informe 1 ou mais" (quarentena) threshold/janela/duração zerados preencher valores ≥ 1 ou desligar a quarentena automática
Aviso "Enviar RN3 ativo mas o template não contém RN3" (ou o equivalente para CSP) toggle ligado e token ausente incluir __RN3__/__CSP__ no template ou desligar o toggle
Tronco criado mas chamadas não o usam Estado ≠ in_service, ou plano não publicado mudar estado e [Publicar plano]
488/415 no EGRESS após publicar mídia/codec divergente do acordado conferir atributos de mídia do endpoint (Roteamento → Endpoints) e revalidar com a operadora

Tabela de referência rápida

Ação Onde Botão
Criar tronco aba Troncos [Novo Tronco] → [Criar]
Testar formato de entrega dialog do tronco Número de exemplo (preview) + toggle Portada
Tirar tronco de produção dialog do tronco Estado = out_of_service → [Salvar] → [Publicar plano]
Quarentena manual dialog do tronco Estado = quarantine → [Salvar] → [Publicar plano]