10. Integrações
Permite o i‑Lumen buscar, em sistemas de terceiros, dados associados a uma entidade (hoje a ONU; o motor é preparado para outras, como OLT ou contrato) — por exemplo contrato, nome do cliente, endereço, latitude/longitude, CTO, cidade, plano. A chave de busca é o identificador da entidade (para ONU, o serial).
Tela de Integrações: a lista de integrações cadastradas, com nome, URL, método, autenticação e status.
10.1 A lista
Mostra nome da integração, URL, método (GET/POST), tipo de autenticação, status (ativa/inativa) e a Comunicação com o servidor de destino (ver 10.4).
10.2 Configurar uma integração
O editor é dividido em etapas:
| Etapa | O que configurar |
|---|---|
| 1 · Conexão | Entidade de destino (define onde os dados são gravados), nome, método, timeout, URL (use {key} — para ONU, {serial} também vale), ativa, verificar SSL. |
| 2 · Autenticação | Nenhuma / Básica (usuário+senha) / Bearer (token) / Cabeçalho próprio. |
| 3 · Corpo (JSON) | Modelo JSON enviado na requisição (qualquer método; pode usar {key}/{serial}). |
| 4 · Mapeamento | Liga cada coluna do destino a um campo da resposta (caminho no JSON). A lista de colunas é montada conforme a entidade escolhida. |
| 5 · Teste | Dispara uma chamada de exemplo e mostra a resposta e os campos mapeados. |
Entidade de destino: é o primeiro campo porque define onde os dados serão gravados (a tabela) e qual chave é enviada à API. Trocar a entidade remonta a lista de colunas do mapeamento. Entidades novas são cadastradas pela equipe (uma linha de registro + a tabela de destino) — sem precisar de uma nova tela ou código.
Mais de uma API na mesma entidade: se um único sistema não traz todas as informações, você pode criar várias integrações para a mesma entidade, cada uma preenchendo as colunas que sabe. A gravação faz mistura por campo — uma integração não apaga o que a outra gravou.
{key}/{serial}: ao consultar, o i‑Lumen substitui{key}pela chave real da entidade (para ONU, o serial;{serial}é mantido como atalho). Pode ir na URL e/ou no Corpo (JSON), inclusive em rotas GET. Sempre rode a etapa 5 · Teste antes de ativar.Teste sem redigitar o secret: ao editar uma integração já salva, deixe o campo Secret em branco e clique Testar — o i‑Lumen usa o secret guardado (cifrado). Só preencha o Secret de novo se quiser trocá‑lo.
10.3 Quando os dados são buscados e onde ficam
A captação é automática, por evento — não há botão de sincronizar manual. Sempre que a Descoberta Completa de ONU de um OLT termina, o i‑Lumen re‑consulta as integrações ativas para todas as ONUs daquele OLT e atualiza os dados. Assim o enriquecimento acompanha a cadência da descoberta completa, sem depender de clique. O trabalho roda em segundo plano (não atrasa a descoberta) e, por rodar depois da descoberta, os dados sobrevivem à recriação das ONUs.
Os valores são gravados nas colunas mapeadas da tabela de destino (para a ONU,
onu_dados_externos), já convertidos ao tipo de cada coluna. Use a etapa 5 · Teste do
editor para conferir o mapeamento a qualquer momento, sem gravar nada.
10.4 Quedas e alertas de comunicação
Se o servidor de terceiro fica fora do ar durante a captação, o i‑Lumen não falha em silêncio: ele registra a queda e abre um alerta de falha de comunicação, para que a indisponibilidade do parceiro fique documentada — útil quando há questionamento sobre "falta de informação".
A coluna Comunicação na lista de integrações mostra o estado de cada uma. Passe o mouse sobre o badge para ver os detalhes (incluindo a latência) no tooltip:
| Badge | Significado |
|---|---|
| 🟢 Comunicando | O destino respondeu nas últimas chamadas, dentro do tempo esperado. O tooltip mostra ok/falha em 24h, a última chamada e a latência (p95 / média / máx). |
| 🟡 Lento | O destino responde, mas devagar — a latência (p95 das últimas 24h) está acima do limite. Pode indicar dados chegando com atraso. |
| 🔴 Sem comunicação | O destino está inacessível (erro de conexão/timeout/DNS/SSL). O tooltip mostra desde quando e o último erro. |
| ⚪ Sem dados | Nenhuma chamada nas últimas 24h. |
O que conta como queda: só falha de conectividade (o servidor não respondeu). Um erro pontual de um assinante que não existe no sistema de origem (ex.: HTTP 404 para um serial) não é tratado como queda — a comunicação está funcionando, só aquele registro não foi encontrado.
Latência ("Lento"): mesmo comunicando, um parceiro lento atrasa o enriquecimento. O i‑Lumen acompanha o p95 (e a média/máx) das chamadas bem‑sucedidas nas últimas 24h; acima do limite, o badge fica Lento e é aberto um alerta de atenção. O limite é 3000 ms por padrão e pode ser ajustado em Configurações (chave
integracoes_latencia_p95_alerta_ms).
O alerta de queda (erro) e o de lentidão (atenção) aparecem também na Central de Alertas e na Saúde do servidor (Dashboard). Ambos se resolvem sozinhos quando a condição normaliza (na próxima captação em que o destino responder / responder rápido). A janela de cada alerta (início → resolução) é o registro da duração do problema.
10.5 Diagnóstico de conexão
Quando uma integração falha de forma intermitente (ex.: às vezes dá timeout, mas quando conecta vai rápido), nem sempre é óbvio onde está o problema — pode ser DNS, rota/borda de rede, TLS ou o próprio servidor/banco do parceiro. O Diagnóstico de conexão investiga isso por camada e entrega um relatório com o veredito e o que verificar.
Como usar: no editor da integração, na seção Testar, clique em Diagnosticar conexão. Além disso, quando o Testar falha por conectividade (timeout, erro de conexão, DNS ou TLS), o diagnóstico roda sozinho e mostra o relatório logo abaixo.
O diagnóstico faz várias amostras de cada camada (para capturar a intermitência):
| Camada | O que mede | O que indica |
|---|---|---|
| DNS | Resolve o host e mede o tempo; lista todos os IPs. | Lentidão/falha aqui = problema de resolução de nomes. |
| TCP por IP | Várias conexões a cada IP; perda de SYN, RTT e jitter. | Perda de SYN com "conecta rápido quando vai" = rota / elemento de borda / firewall / security list. |
| TLS | Handshake e certificado (validade). | Falha de TLS com TCP OK = MTU/MSS ou middlebox. |
| HTTP | A requisição real, repetida; tempo e status. | Conexão rápida mas HTTP lento/falho = servidor/banco do parceiro, não a rede. |
| Referência | Conexões a IPs públicos estáveis. | Diferencia "a saída do seu servidor está instável" de "só o parceiro está instável". |
Leitura rápida do veredito: o banner colorido no topo já resume a causa provável (ex.: "Intermitência no estabelecimento TCP — rota/borda" ou "Rede saudável — intermitência no servidor/banco") e lista o que verificar. Use Copiar relatório para enviar ao time de rede ou ao responsável pela API/Oracle.
Importante: rode o diagnóstico durante a falha. Se ele rodar num momento bom, todas as camadas aparecem OK e o veredito será "não capturou o evento" — repita quando o problema estiver acontecendo para flagrar o flapping.