Roteiro: Criar header policy (headers SIP por operadora)¶
Perfil necessário: admin
Menus usados: Roteamento
Risco: médio (header errado pode fazer a operadora rejeitar a chamada — 403/488 — em todo o tráfego daquela operadora; vale a partir do próximo Publicar plano, pois headers fazem parte do plano compilado)
Rollback: editar/excluir a policy na aba Headers 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¶
- [ ] Operadora dona da política já criada (roteiro
carrier-operator.md) - [ ] Header e valor acordados com a operadora (ex.:
P-COLP,Privacy,X-...de interconnect) - [ ] Saber quando aplicar: sempre, só portado, só LDN, só saída ou só entrada
Passo a passo¶
1. Abrir a aba Headers¶
Caminho: Roteamento → Operadoras e Troncos → aba Headers
Clique: [Headers] (tab do topo da página)

Resultado esperado: listagem de políticas com colunas Operadora, Header, Aplicar e Template; filtros por Operadora e Aplicar na toolbar (a busca textual não se aplica nesta aba).
2. Abrir o dialog Nova Header Policy¶
Clique: [Nova Header Policy] (toolbar da listagem)

Resultado esperado: dialog Nova Header Policy abre com Aplicar Quando default always.
3. Preencher e salvar¶
Preencha:
| Campo | Obrig. | Formato/exemplo | Efeito |
|---|---|---|---|
| Operadora * | sim | select (ex.: TIM Wholesale) |
Operadora dona da política; o header é aplicado nas chamadas entregues aos troncos dela |
| Aplicar Quando | sim (default always) |
Sempre · Só portado · Só LDN · Só saída · Só entrada |
Janela de aplicação do header (values: always, ported_only, ldn_only, outbound_only, inbound_only) |
| Nome do Header * | sim | P-COLP, Privacy, X-Operadora-Codigo |
Nome do header SIP a manipular na mensagem de saída |
| Template | não | {{call_id}}, {{carrier_rn1}}, {{rn2_out}} |
Valor do header; template com variáveis entre chaves duplas. Vazio = header sem valor (presença simples) |
Clique: [Criar] (rodapé do dialog; [Salvar] quando editando)
Resultado esperado: toast "Header policy salva com sucesso"; a política aparece na listagem com operadora, header, janela de aplicação e template.
Como no resto do catálogo: salvar é draft. O header só vale no runtime após [Publicar plano] — no compile, as policies são denormalizadas por operadora no plano (
header_policies_json), e o reload abre na validação do roteiro de homologação.
Validação¶
- [ ] Visual: policy listada na aba Headers com operadora/header/janela corretos
- [ ] Funcional: Simular compilação sem erro; a operadora da policy está habilitada (policies de operadora desabilitada não entram no plano)
- [ ] Funcional: após publicar, INVITE de teste sai com o header esperado (conferir no Operação → CDR → fluxo SIP estágio EGRESS ou captura na ponta da operadora)
Erros comuns¶
| Sintoma | Causa provável | Correção |
|---|---|---|
| "Operadora é obrigatória" | select vazio | escolher a operadora |
| "Header é obrigatório" | Nome do Header vazio | informar o nome do header |
| Header não aparece no INVITE | plano não publicado, ou operadora da policy está desabilitada | [Publicar plano]; conferir toggle Ativa da operadora |
| Operadora rejeita chamadas (403/488) após publicar | header/valor divergente do interconnect | desligar/remover a policy e publicar; validar formato com a operadora antes de religar |
| Duplicidade de header | duas policies para o mesmo header na mesma operadora | manter uma policy por header/operadora (usar a janela Aplicar Quando para variar) |
Tabela de referência rápida¶
| Ação | Onde | Botão |
|---|---|---|
| Criar policy | aba Headers | [Nova Header Policy] → [Criar] |
| Filtrar por operadora/janela | toolbar da aba | selects Operadora e Aplicar |
| Editar/excluir | linha da tabela | ícones de edição/exclusão → [Salvar]/[OK] |
| Ativar no runtime | topo da página | [Publicar plano] |