Guia detalhado de formulários — módulo Integrações

Visão geral

Este guia documenta o módulo Integrações, acessível em Parâmetros → Integrações, a partir da auditoria final em JSON e das fontes existentes. O JSON contém cinco telas habilitadas. A auditoria foi realizada por navegação e preenchimento no navegador; nenhum formulário, conexão ou cadastro foi salvo.

A auditoria identificou dois formulários: Nova conta, em Contas SMTP, e Novo modelo, em Mensagens de e-mail. TV — TelvoraTV, Learning — Telvora e Book — Telvora aparecem como telas de configuração direta, sem objeto form separado. Os controles select foram deliberadamente deixados sem preenchimento confirmado e mascarados na auditoria final. Portanto, as opções abaixo são rótulos exibidos pela interface, e não uma afirmação de que uma opção real tenha sido selecionada.

Nenhum valor preexistente, nome de empresa ou filial, endereço operacional, credencial, segredo, token ou documento é reproduzido. Os exemplos desta página são fictícios. Os eventos decorrentes da política de bloqueio de escrita não são tratados como defeitos e não entram na seção Erros comuns.

Métricas exatas recalculadas do JSON final

Métrica	Contagem	Critério
Telas habilitadas	5	Todos os cinco registros têm disabled: false.
Formulários	2	Dois registros têm form não nulo.
Controles de lista/configuração direta	21	Soma dos controles em list.controls.
Controles de formulário	16	11 em Nova conta e 5 em Novo modelo.
Controles no total	37	21 + 16.
Campos marcados como obrigatórios	7	Cinco em Nova conta e dois em Novo modelo.
Exemplos fictícios preenchidos pela auditoria	10	Sete no formulário SMTP e três no formulário de mensagens.
Mensagens de validação	1	Uma entrada em validation_messages.
Mensagens auxiliares contendo “Nenhum resultado”	0	Nenhuma entrada elegível em helper_messages.
Erros HTTP reais diferentes de 409	0	Nenhum erro HTTP elegível em runtime_errors.
Erros observados considerados	1	Uma mensagem de validação + zero mensagens auxiliares elegíveis + zero erros HTTP elegíveis.
Erros documentados nas fontes	13	Quatro situações de TV, cinco de Learning e quatro de Book.

Inventário

Tela habilitada	Superfície	Controles	Formulário	Ações e elementos relevantes
Contas SMTP	Lista com um controle e cadastro Nova conta	12	Sim	Nova conta, Editar, Enviar teste; Identificação, Servidor, Autenticação, Remetente, Provedores comuns e Dicas.
Mensagens de e-mail	Lista sem controles de entrada e cadastro Novo modelo	5	Sim	Novo modelo, Importar modelos IXC, ordenação por Código/Nome/Categoria/Assunto/SMTP e ações Editar.
TV — TelvoraTV	Configuração direta	7	Não	Conexão, Pacotes e Salvar conexão.
Learning — Telvora	Configuração direta	7	Não	Salvar conexão.
Book — Telvora	Configuração direta	6	Não	Salvar conexão.

O JSON não registrou abas (tabs: []). Em TV — TelvoraTV, Conexão e Pacotes foram inventariados como botões, embora as fontes existentes descrevam essas superfícies como abas. Não foi encontrado no JSON um formulário para pacotes de TV.

Contas SMTP

A tela está em Parâmetros → Integrações → Contas SMTP. A listagem oferece o controle opcional Destinatário do teste e as ações Nova conta, Editar e Enviar teste.

Controles da listagem

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Destinatário do teste	E-mail (email)	Não	Informe um endereço de teste somente em uma execução operacional autorizada.	teste@example.invalid	Placeholder observado: seu@email.com. O controle não tinha valor preexistente registrado.

Formulário Nova conta

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Nome	Texto (input)	Sim	Dê um nome identificável à conta, sem inserir senha ou token.	Conta SMTP de homologação	Placeholder observado: Ex.: Cobrança — endereço do remetente.
Conta padrão do tenant	Seleção (select)	Não	Use a opção padrão somente se a conta dever atender envios sem conta definida; caso contrário, use-a explicitamente.	Não — usar só quando escolhida	Opções observadas: Não — usar só quando escolhida e Sim — padrão para envios sem conta definida. Nenhuma seleção real foi confirmada.
Observações internas	Texto (input)	Não	Registre uma nota operacional sem credenciais ou dados pessoais.	Uso exclusivo em testes controlados	Placeholder indica uso interno e opcional.
Host	Texto (input)	Sim	Informe o host SMTP fornecido pelo administrador do serviço de e-mail.	smtp.example.invalid	Placeholder observado: smtp.seudominio.com.br.
Porta	Texto (input)	Sim	Informe a porta fornecida pelo provedor e compatível com a criptografia.	587	O placeholder exibe 587; não foi registrada validação de faixa.
Criptografia	Seleção (select)	Não	Escolha o modo suportado pelo servidor e coerente com a porta.	TLS (recomendado — porta 587)	Opções observadas: TLS, SSL e Nenhuma. Nenhuma seleção real foi confirmada.
Usuário	Texto (input)	Não	Informe o usuário fornecido pelo provedor, geralmente o endereço completo.	usuario@example.invalid	Placeholder observado: Geralmente o e-mail completo.
Senha	Senha (password)	Sim	Informe a senha ou senha de aplicativo autorizada. Não publique o valor operacional.	segredo-ficticio-nao-utilizavel	Placeholder observado: Senha ou senha de app. A ausência do campo produziu a única validação observada.
E-mail remetente	E-mail (email)	Sim	Informe um endereço remetente válido e autorizado pelo serviço SMTP.	remetente@example.invalid	O tipo HTML é email; não houve mensagem de formato inválido no JSON.
Nome exibido	Texto (input)	Não	Defina o nome exibido ao destinatário.	Equipe de atendimento	Campo opcional.
Reply-to (opcional)	E-mail (email)	Não	Informe outro endereço quando as respostas deverem ser encaminhadas para ele.	respostas@example.invalid	Placeholder indica o uso quando o endereço de resposta for diferente.

A tela também lista referências visuais de provedores comuns, com exemplos de host, porta, criptografia ou autenticação. A auditoria não confirmou preenchimento automático por esses atalhos.

Passos

1. Abra Parâmetros → Integrações → Contas SMTP e confira a listagem.
2. Clique em Nova conta e confirme as seções Identificação, Servidor, Autenticação e Remetente.
3. Em uma reprodução segura, use somente dados fictícios, como endereços terminados em .invalid.
4. Confira a compatibilidade entre host, porta e criptografia; não presuma que os atalhos preencham campos automaticamente.
5. Para reproduzir a validação observada sem gravar dados, deixe Senha vazia e acione a validação nativa.
6. Use Cancelar ou Voltar ao terminar. Em operação autorizada, use Salvar e Enviar teste somente após validar os dados com o responsável pelo serviço SMTP.

Regras e validações

A interface marcou Nome, Host, Porta, Senha e E-mail remetente como obrigatórios. Conta padrão do tenant, Observações internas, Criptografia, Usuário, Nome exibido e Reply-to não foram marcados como obrigatórios. Os campos de e-mail têm tipo email, mas a auditoria não registrou erro de formato.

Não foram observadas validações de conectividade SMTP, autenticação, DNS, faixa de porta ou coerência entre porta e criptografia. Nenhuma opção de select foi confirmada como selecionada.

Erros comuns

Erro ou sintoma	Causa	Como resolver	Evidência
Please fill out this field. ao validar Senha	O campo Senha ou senha de app estava vazio e foi marcado como obrigatório.	Preencha a senha ou senha de aplicativo autorizada no ambiente operacional. Não registre o segredo na wiki; para reprodução segura, use dado fictício e cancele sem salvar.	Observado na simulação — validation_messages do formulário Nova conta.

Mensagens de e-mail

A tela está em Parâmetros → Integrações → Mensagens de e-mail. A listagem não apresentou controles de entrada. Ela exibe Novo modelo, Importar modelos IXC, ordenação por Código, Nome, Categoria, Assunto e SMTP, além de ações Editar.

Formulário Novo modelo

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Nome	Texto (input)	Sim	Use um nome curto e reconhecível na lista.	Modelo de homologação	Placeholder: Nome amigável na lista.
Categoria	Seleção (select)	Não	Escolha a finalidade mais próxima do modelo.	Geral	Opções observadas: Ativação de contrato, Cancelamento, Cobrança / faturamento, Aviso de atraso e Geral. Nenhuma seleção real foi confirmada.
Conta SMTP	Seleção (select)	Não	Selecione uma conta autorizada para o envio ou use a configuração padrão do tenant.	Padrão do tenant	Também havia um rótulo de conta operacional na lista; ele não é reproduzido. Nenhuma seleção real foi confirmada.
Descrição interna	Texto (input)	Não	Explique a finalidade interna sem inserir dados de clientes ou credenciais.	Modelo fictício para validação documental	Placeholder: Opcional — só para organização.
Assunto	Texto (input)	Sim	Escreva o assunto e use uma variável documentada quando necessário.	Aviso de cobrança — #cliente_razao#	Placeholder observado com variável de assunto.

A seção Variáveis agrupa botões em Cliente, Contrato, Financeiro e Empresa / filial. Os rótulos observados foram:

• Cliente: #cliente_razao#, #cliente_nome#, #cliente_fantasia#, #cliente_cnpj_cpf#, #cliente_email# e #cliente_fone#.
• Contrato: #cliente_contrato_id#, #contrato_numero#, #contrato_descricao#, #contrato_data_de_ativacao# e #motivo_cancelamento#.
• Financeiro: #parcelas_vencidas#, #valor_aberto_atrasado#, #areceber_numero#, #areceber_data_emissao#, #areceber_data_vencimento#, #areceber_valor#, #areceber_valor_atual#, #linha_digitavel#, #pix_copia_cola#, #link_gateway#, #valor_recebido# e #data_recebido#.
• Empresa / filial: #filial_fantasia#, #filial_razao#, #filial_telefone#, #filial_email#, #filial_site#, #filial_cidade# e #data_atual_extenso#.

A auditoria não confirmou que clicar em cada variável insira texto no editor. Os rótulos acima são referências de interface, não valores de clientes ou empresas.

Passos

1. Abra Parâmetros → Integrações → Mensagens de e-mail e confira a listagem, a ordenação e as ações disponíveis.
2. Clique em Novo modelo e confirme os blocos de identificação, conteúdo e variáveis.
3. Use nome, descrição e assunto fictícios. Os rótulos Geral e Padrão do tenant podem ser usados como exemplos de documentação, sem afirmar seleção real.
4. Revise as variáveis por grupo. Se houver teste visual autorizado, confirme a alteração apenas no rascunho.
5. Use Cancelar ou Voltar ao terminar. Em operação autorizada, valide a conta SMTP e o contexto de cada variável antes de usar Salvar.
6. Execute Importar modelos IXC somente com procedimento operacional autorizado; esse fluxo não foi testado.

Regras e validações

A interface marcou Nome e Assunto como obrigatórios. Categoria, Conta SMTP e Descrição interna não foram marcados como obrigatórios. O JSON não registrou mensagem de validação para este formulário.

Não foram observadas regras de tamanho, sintaxe do assunto, validação dos tokens, renderização das variáveis, importação ou teste de envio. Nenhum select foi confirmado como selecionado.

Erros comuns

Erro ou sintoma	Causa	Como resolver	Evidência

Não houve validation_messages, mensagem auxiliar contendo Nenhum resultado ou erro HTTP real diferente de 409 para este formulário no JSON final.

TV — TelvoraTV

A tela está em Parâmetros → Integrações → TV — TelvoraTV. Não há formulário separado no JSON; os sete controles são diretos na tela. As ações registradas são Conexão, Pacotes e Salvar conexão.

Configuração direta

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Nome	Texto (input)	Não marcado	Use um identificador para a conexão.	TV de homologação	A interface não marcou o campo como obrigatório. Nenhum valor real é reproduzido.
URL da API TelvoraTV	Texto (input)	Não marcado	Informe a URL base fornecida pelo administrador.	https://tv.example.invalid/api/v1	O endereço operacional não é reproduzido.
API Key ID	Texto (input)	Não marcado	Informe o identificador da chave criada no painel do serviço.	key-id-ficticio	Não use identificador real na documentação.
API Secret	Senha (password)	Não marcado	Informe o segredo no campo mascarado.	segredo-tv-ficticio	Nenhum segredo real é exposto.
Tenant slug (X-Tenant)	Texto (input)	Não marcado	Informe o identificador do tenant quando exigido.	tenant-exemplo	Nenhum valor preexistente é reproduzido.
Secret validação ERP (TV → ERP)	Senha (password)	Não marcado	Informe o segredo compartilhado com o painel do serviço.	validacao-tv-ficticia	Campo mascarado; nenhum segredo real é exposto.
Status	Seleção (select)	Não marcado	Use o estado ativo somente após concluir os pré-requisitos.	Inativa	Opções observadas: Ativa e Inativa. Nenhuma seleção real foi confirmada.

Passos

1. Abra Parâmetros → Integrações → TV — TelvoraTV e revise os campos sem substituir valores operacionais.
2. Em Conexão, confira URL, identificador da chave, segredo, tenant e segredo de validação com o administrador responsável.
3. Em Pacotes, organize canais e limites conforme o procedimento autorizado; o JSON não registra os campos dessa superfície como formulário.
4. Confirme no painel externo a liberação de canais, a geração da chave e a configuração de integração com o ERP.
5. Em operação autorizada, use Salvar conexão somente após validar os dois lados. A auditoria não salvou a conexão.

Regras e validações

Nenhum dos sete campos foi marcado como obrigatório e nenhuma validação de tela foi registrada. Isso descreve a interface, não significa que a conexão funcione sem configuração externa.

As fontes documentam a necessidade de URL, chave, segredo de validação e configuração no painel externo. Também documentam login do aplicativo com usuário e senha PPPoE, sem envio da senha ao serviço de TV; produto de TV e login PPPoE ativos; limites de dispositivos e telas; e prevalência do maior limite entre pacotes. Essas regras são documentadas, não reproduzidas nesta auditoria.

Erros comuns

Erro ou sintoma	Causa	Como resolver	Evidência
Não foi possível listar canais	URL, identificador da chave ou segredo da conexão incorreto ou incompleto.	Confira os dados com o administrador do serviço, sem expor o segredo, e valide novamente em ambiente autorizado.	Documentado — não reproduzido nas fontes existentes.
Pacote de TV retorna 422	Há canais no pacote que não foram liberados no painel externo.	Libere os canais no painel e revise o pacote antes de sincronizar novamente.	Documentado — não reproduzido nas fontes existentes.
Login no aplicativo de TV falha	Segredo de validação divergente, login PPPoE inativo ou produto de TV ausente no contrato.	Alinhe o segredo nos dois lados, confirme o login PPPoE e verifique o produto de TV no contrato.	Documentado — não reproduzido nas fontes existentes.
Código do pacote não muda	O código é gerado automaticamente e não é editável.	Edite nome e canais; não tente alterar o código automático.	Documentado — não reproduzido nas fontes existentes.

Learning — Telvora

A tela está em Parâmetros → Integrações → Learning — Telvora. Não há formulário separado no JSON; os sete controles são diretos. A ação registrada é Salvar conexão.

Configuração direta

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Nome	Texto (input)	Não marcado	Use um nome para identificar a conexão.	Learning de homologação	Nenhum valor real é reproduzido.
URL da API Telvora Learning	Texto (input)	Não marcado	Informe a URL base fornecida pela administração do serviço.	https://learning.example.invalid/api/v1	O endereço operacional não é reproduzido.
API Key ID (opcional)	Texto (input)	Não marcado	Informe o identificador quando o provedor o utilizar.	learning-key-ficticia	Não use identificador real na documentação.
API key (X-API-Key do Learning)	Senha (password)	Não marcado	Informe a chave no campo mascarado.	api-key-learning-ficticia	Nenhuma chave real é exposta.
Secret de validação (Learning → ERP)	Senha (password)	Não marcado	Informe o segredo compartilhado entre Learning e ERP.	validacao-learning-ficticia	Campo mascarado; nenhum segredo real é reproduzido.
Acessos simultâneos (padrão)	Número (number)	Não marcado	Informe o fallback quando o produto Learning não tiver valor próprio.	2	O rótulo descreve fallback; não foram registrados atributos nativos de mínimo ou máximo.
Status	Seleção (select)	Não marcado	Use Ativa somente após validar a conexão; use o estado inativo/bloqueado para impedir o uso.	Inativa / bloqueada	Opções observadas: Ativa e Inativa / bloqueada. Nenhuma seleção real foi confirmada.

Passos

1. Abra Parâmetros → Integrações → Learning — Telvora e revise os sete controles sem substituir valores operacionais.
2. Confirme com o administrador a criação do provedor e a disponibilidade das chaves, sem publicar nenhuma chave ou segredo.
3. Use Acessos simultâneos (padrão) somente como fallback; a documentação dá prioridade ao valor definido no produto.
4. Confira os estados disponíveis sem alternar uma conexão real durante a auditoria.
5. Em operação autorizada, use Salvar conexão depois de validar URL, chaves, segredo, fallback e status. A auditoria não salvou a conexão.

Regras e validações

Nenhum campo foi marcado como obrigatório e nenhuma mensagem de validação foi registrada. As fontes documentam que o produto Learning ativo no contrato libera o acesso. A prioridade de max_concurrent_sessions é: maior valor dos produtos Learning ativos no contrato; depois o padrão da conexão; por fim 1.

Também são pré-requisitos documentais contrato ativo, item ativo do produto e login PPPoE. Contrato bloqueado, cliente inativo ou ausência do produto específico impedem o acesso. A auditoria não confirmou seleção de select nem executou a validação externa.

Erros comuns

Erro ou sintoma	Causa	Como resolver	Evidência
Menu Learning não aparece	Versão do recurso não publicada ou permissões de integração ausentes.	Publique a versão aplicável e confira as permissões com o administrador.	Documentado — não reproduzido nas fontes existentes.
Login Learning falha mesmo com a senha correta	O produto Learning não está vinculado ao contrato como item ativo.	Inclua o produto Learning no contrato ativo e confirme o login PPPoE.	Documentado — não reproduzido nas fontes existentes.
unauthorized no Learning	O segredo do serviço não coincide com o segredo cadastrado no ERP.	Compare os segredos nos dois ambientes e substitua-os somente por valores autorizados, sem publicá-los.	Documentado — não reproduzido nas fontes existentes.
NO_LEARNING_PRODUCT	O contrato não possui produto com integração Learning ativo.	Cadastre ou vincule produto do tipo Apps, provedor Telvora Learning, e deixe o item ativo no contrato.	Documentado — não reproduzido nas fontes existentes.
Aluno entra em mais dispositivos do que deveria	O limite no produto pode estar ausente ou incorreto; o produto tem prioridade sobre o padrão da conexão.	Ajuste Acessos simultâneos no app no produto e solicite novo login no aplicativo.	Documentado — não reproduzido nas fontes existentes.

Book — Telvora

A tela está em Parâmetros → Integrações → Book — Telvora. Não há formulário separado no JSON; os seis controles são diretos. A ação registrada é Salvar conexão.

Configuração direta

Campo	Tipo	Obrigatório	Como preencher	Exemplo fictício	Observação
Nome	Texto (input)	Não marcado	Use um identificador para a conexão.	Book de homologação	Nenhum valor real é reproduzido.
URL da API Telvora Book	Texto (input)	Não marcado	Informe a URL base fornecida pelo administrador.	https://book.example.invalid/api/v1	O endereço operacional não é reproduzido.
Cliente / código do provedor (opcional)	Texto (input)	Não marcado	Informe um código de referência quando o provedor o exigir.	provider_exemplo	Campo opcional conforme o rótulo.
Bearer token (Authorization)	Senha (password)	Não marcado	Informe o token autorizado no campo mascarado.	bearer-token-ficticio	Nenhum token real é exposto.
Acessos simultâneos (padrão)	Número (number)	Não marcado	Informe o fallback quando o produto Book não tiver valor próprio.	3	O rótulo informa máximo de 20; não foram registrados atributos nativos de mínimo ou máximo.
Status	Seleção (select)	Não marcado	Use Ativa somente após validar a conexão; use o estado inativo/bloqueado para impedir o uso.	Inativa / bloqueada	Opções observadas: Ativa e Inativa / bloqueada. Nenhuma seleção real foi confirmada.

Passos

1. Abra Parâmetros → Integrações → Book — Telvora e revise os campos sem substituir valores operacionais.
2. Confirme com o administrador a existência do provedor e do token autorizado; nunca copie o token para a wiki.
3. Revise Acessos simultâneos (padrão) como fallback e respeite o limite documentado de 20.
4. Confira os estados disponíveis sem alternar uma conexão real.
5. Em operação autorizada, use Salvar conexão somente após confirmar URL, código opcional, token, fallback e status. A auditoria não salvou a conexão.

Regras e validações

Nenhum campo foi marcado como obrigatório e nenhuma mensagem de validação foi registrada. As fontes documentam prioridade do produto Book ativo no contrato sobre o padrão da conexão; na ausência de valor, o fallback é 1, com máximo documentado de 20.

A criação do assinante exige senha PPPoE recuperável com pelo menos oito caracteres. Cliente inativo, contrato bloqueado ou ausência do produto Book ativo bloqueiam o assinante. O e-mail do cliente é usado no login. Essas regras não foram reproduzidas como validações nesta tela.

Erros comuns

Erro ou sintoma	Causa	Como resolver	Evidência
Menu Book não aparece	Versão do recurso não publicada ou permissões de integração ausentes.	Publique a versão aplicável e confira as permissões com o administrador.	Documentado — não reproduzido nas fontes existentes.
Assinante não aparece no Book	Produto Book ausente no contrato, e-mail ausente ou senha PPPoE indisponível.	Confirme o produto ativo no contrato, o e-mail e a existência de senha PPPoE recuperável.	Documentado — não reproduzido nas fontes existentes.
401 na sincronização Book	Bearer token incorreto ou revogado.	Gere ou confirme um token autorizado no serviço e atualize a conexão sem publicar o token.	Documentado — não reproduzido nas fontes existentes.
409 por e-mail no Book	O e-mail já está associado a outro assinante do provedor.	Identifique o cadastro duplicado e corrija a vinculação pelo procedimento administrativo, sem remoção destrutiva.	Documentado — não reproduzido nas fontes existentes.

Observações sobre a evidência

O JSON final não contém mensagem auxiliar com Nenhum resultado, erro HTTP real diferente de 409 ou GET 404 real. Portanto, não há linhas adicionais para esses critérios. Os fluxos de gravação, teste SMTP, importação, edição, sincronização, login externo e criação de pacotes não foram executados e não são apresentados como realizados.

Capturas dos formulários simulados

Os valores visíveis são exemplos fictícios. Seleções e valores preexistentes foram mascarados. A auditoria bloqueou POST, PUT, PATCH e DELETE; nenhum registro foi salvo.

Contas SMTP

Formulário aberto por Nova conta e preenchido apenas no navegador, sem persistência.

Mensagens de e-mail

Formulário aberto por Novo modelo e preenchido apenas no navegador, sem persistência.

Referências