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 oIP:portaSIP) - [ ] 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)

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)

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_addresspara 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] |