Crie contas e automatize renovações UniTV com segurança

1. Primeiros passos

1. Receba um convite. O Super Admin gera um link individual para criar sua conta.
2. Crie seu acesso. Informe nome, empresa, e-mail e uma senha com pelo menos 10 caracteres.
3. Conecte o fornecedor. Cadastre o usuário e a senha usados no painel de revenda UniTV.
4. Cadastre os vínculos. Relacione cada SN a um cliente ou pedido do seu sistema.
5. Gere um token. Use o token Bearer para autorizar n8n, WhatsApp ou outra integração.

2. Conectar a conta do fornecedor

No menu Início, preencha o usuário e a senha do fornecedor. O Device code é gerado automaticamente; normalmente não precisa ser informado.

1. Clique em Salvar configuração.
2. Clique em Carregar CAPTCHA.
3. Digite os quatro números exibidos e clique em Conectar.
4. Se o fornecedor solicitar confirmação, informe o código recebido por e-mail ou telefone.

A senha fica cifrada no servidor. O painel nunca mostra a senha salva novamente.

3. Contas e vínculos

O vínculo informa qual conta UniTV pertence a cada cliente da sua automação. Para operações normais, ele continua sendo a forma recomendada. Se você administra contas apenas por SN, pode usar operacao_direta: true em renovar, alterar_senha, editar_conta ou simular; a API valida o SN no fornecedor e cria somente um registro técnico para auditoria, sem exigir cadastro manual de cliente.

Em Contas, localize o SN e preencha:

• Cliente: nome legível para o painel.
• Referência da automação: identificador estável do seu sistema, como número do pedido, telefone ou ID do cliente.
• Telefone e e-mail: dados opcionais para consulta.
• Ativo: precisa estar marcado para permitir operações.

Você poderá localizar o vínculo por referencia_externa, sn ou vinculo_id.

4. Gerar um token da API

1. Abra API & Webhooks.
2. Escolha um nome, por exemplo n8n produção.
3. Clique em Gerar token e copie imediatamente.

O token completo aparece uma única vez. Todas as chamadas devem enviar:

5. Configurar no n8n

1. Adicione um node HTTP Request.
2. Escolha Import cURL no menu do node.
3. Cole o exemplo completo.
4. Troque uta_COPIE_SEU_TOKEN_AQUI pelo token gerado no painel.
5. Troque a referência e a chave de idempotência pelos campos do seu fluxo.

Exemplo pronto para importar — simulação sem consumir pontos:

Depois da importação, o node ficará equivalente a:

Para receber dados de outro node, substitua os valores fixos por expressões do n8n:

No próximo node, você pode testar sucesso com {{ $json.ok === true }} e ler o resultado em {{ $json.data }}.

5.1. 🧩 Fluxo n8n completo: WhatsApp, API e Pix

Esta seção reproduz o fluxo usado na prática: recebe uma mensagem da Uazapi, identifica o telefone, consulta as contas, mostra menus, simula a operação, aguarda CONFIRMO, gera o Pix e só depois cria ou renova a conta.

Mapa visual do fluxo

🗺️ Catálogo rápido de endpoints

🔐 Credenciais no n8n

1. Crie uma credencial Header Auth chamada Automation Bearer: nome do header Authorization, valor Bearer uta_SEU_TOKEN.
2. Crie uma credencial de header para a Uazapi: nome token, valor do token da sua instância.
3. Para PostgreSQL, use o banco dedicado do workflow. Para Redis, use a credencial Redis do seu servidor e uma chave por telefone.
4. Nunca coloque token em um node Code, em URL ou em mensagem do WhatsApp.

🧭 Node 1 — entrada e normalização

Use um Webhook POST, por exemplo /webhook/unitvia. Em seguida, um node Code deve produzir pelo menos:

Para mensagens da Uazapi, mantenha o número completo para envio e remova o prefixo 55 somente quando a API do fornecedor exigir telefone nacional.

📱 Node 2 — menus Uazapi

Use HTTP Request POST para https://tectonny.uazapi.com/send/menu. No body JSON:

Para períodos, troque as opções por 1 mês|1m, 3 meses|3m, 6 meses|6m e 1 ano|1y. Depois que o usuário escolher, não envie o menu novamente.

🔎 Node 3 — consultar conexão e conta

Primeiro consulte a conexão:

Depois consulte por telefone ou SN. Para consulta direta por SN:

Se o telefone tiver mais de uma conta, mostre uma lista com os SNs e salve a escolha na sessão antes de pedir o período.

🧪 Node 4 — simulação obrigatória

Renovação:

Compra de conta nova:

Mostre somente conta, período e valor. Não mostre saldo, pontos ou créditos. Só avance quando o cliente responder exatamente CONFIRMO.

💳 Node 5 — Pix e confirmação

O n8n chama o checkout interno do projeto de pagamento. O pedido fica pendente até o Mercado Pago confirmar; a execução que gerou o Pix não deve ficar aguardando.

Para compra, use mode: "new", customer_name, phone e period. Envie o código Pix completo em uma mensagem/botão separado. Nunca envie somente a chave Pix.

✅ Node 6 — após o pagamento

1. Consulte o status do pedido usando o endpoint configurado pelo checkout.
2. Se status=completed e purchase_type=NEW_ACCOUNT, chame POST action=criar_conta.
3. Se for renovação, chame POST action=renovar.
4. Somente depois da resposta de sucesso envie usuário e senha.
5. Em RETRY ou pendente, consulte novamente; não crie cobrança duplicada.

🗄️ PostgreSQL ou ⚡ Redis?

Você pode usar os dois: Redis para estado temporário da conversa e PostgreSQL para idempotência, cobrança e histórico permanente.

🧰 Teste rápido no n8n

1. Importe o workflow baixado.
2. Configure as credenciais Automation, Uazapi, PostgreSQL/Redis e OpenAI, se usar o fluxo com IA.
3. Ative o workflow e copie a URL de produção do Webhook para a Uazapi.
4. Teste nesta ordem: Consultar → Renovar → CONFIRMO → Pix → status pago.
5. Use o painel Executions do n8n para conferir qual branch foi executado. Um node não conectado não será executado.

6. Operações disponíveis

Consultar conexão e saldo

Listar contas

Listar vínculos ativos

Consultar histórico de operações

Consultar histórico de criações

Simular criação de conta

A simulação informa custo, saldo e elegibilidade sem criar a conta e sem consumir pontos.

Criar nova conta

Resposta da criação concluída:

Criar ou atualizar vínculo

Resposta esperada: {"ok":true,"data":{"id":12}}. Use esse ID como vinculo_id ou continue operando pela referencia_externa.

Simular renovação

Períodos aceitos: 1m, 3m, 6m e 1y. A simulação não consome pontos.

Exemplo de resposta da simulação:

Renovar

Resposta de renovação concluída:

Trocar senha da conta UniTV

A nova senha deve possuir exatamente 6 caracteres alfanuméricos, com pelo menos uma letra e um número. Senhas iniciais geradas pelo fornecedor podem ter outro formato, mas a troca manual segue essa regra.

A troca é processada de forma assíncrona pelo fornecedor e pode levar até 5 minutos. A resposta pode vir com status ENVIADO; depois aguarde e execute simular com incluir_senha=true. Quando a senha final conferir, o histórico muda para SUCESSO.

Editar dados da conta

Suspender e reativar o acesso

A suspensão combina duas ações: troca a senha por uma senha temporária segura e usa o status do fornecedor para exibir a conta como suspensa. A senha original fica cifrada somente durante a suspensão.

Na reativação, a API restaura a senha original e volta o status visual para ativo. Se alguém tiver alterado a senha diretamente no fornecedor durante a suspensão, a restauração automática é bloqueada para não sobrescrever essa mudança.

Use GET https://automation.tectonny.com.br/api.php?action=suspensoes para consultar o estado das suspensões. As senhas original e temporária nunca são retornadas por esse endpoint, pelos históricos ou pelos webhooks.

7. Criar revendas e adicionar créditos

O painel original chama essa área de Reseller Management. A API permite criar revendas filhas, consultar seus saldos, editar observações e transferir pontos da conta pai.

Listar revendas e saldos

Usuários de uma revenda: o fornecedor não aceita reseller_id como filtro no endpoint de contas. GET action=contas lista as contas da conexão UniTV autenticada. Para consultar os usuários de uma revenda separadamente, conecte as credenciais dessa revenda como outra conexão e use GET action=contas&conexao_id=....

Consultar os pacotes disponíveis

Use o campo id do pacote retornado como package_id. Normalmente o pacote UniTV principal é o 1.

Criar uma revenda

A senha deve ter de 8 a 16 caracteres, com letras e números. Ela não é armazenada no histórico da API.

Editar a observação

Adicionar créditos mensais

Adicionar créditos anuais

Para saldo anual, mantenha points em zero e informe points_year:

Debitar créditos

Ativar ou bloquear uma revenda

A operação alterna o status atual da revenda. Use a mesma ação novamente somente quando quiser fazer a próxima alteração.

Consultar o histórico

Os eventos de saída usam os nomes reseller.criar_revenda.sucesso, reseller.recarregar_revenda.sucesso, reseller.debitar_revenda.sucesso e seus equivalentes de falha.

8. Códigos de ativação

O fornecedor permite gerar códigos de 1 mês ou 1 ano. O cliente resgata o código no aplicativo UniTV; a API permite acompanhar quando ele passa de DISPONÍVEL para UTILIZADO.

Teste seguro no n8n: veja o JSON sem consumir pontos

Faça primeiro uma consulta de leitura. Ela não gera código, não altera o saldo e não modifica nenhuma conta.

1. Crie um workflow e adicione um node Manual Trigger.
2. Depois dele, adicione um node HTTP Request.
3. Na aba Parameters do HTTP Request, clique em Import cURL.
4. Cole o comando abaixo, troque somente o token e confirme em Import.
5. Clique em Execute step ou Test step.
6. No painel OUTPUT, à direita, selecione a visualização JSON.

Uma resposta HTTP 200 aparecerá no formato abaixo. Os valores são apenas ilustrativos e outros campos do fornecedor também podem aparecer:

Nos próximos nodes do n8n, leia os campos com expressões como:

Para enxergar também o status HTTP, em Options → Response ative Include Response Headers and Status. Nesse modo o corpo ficará dentro de body e o código HTTP aparecerá em statusCode.

Segundo teste seguro: simular a geração

Importe este comando em outro HTTP Request. A simulação informa custo e saldo, mas não cria código:

Listar códigos sem mostrar o valor completo

Listar códigos completos para entrega

Simular geração sem consumir pontos

Gerar código

Associar dados do cliente

Acompanhar um código

Todos esses comandos podem ser colados diretamente em Import cURL no node HTTP Request do n8n. O código completo não é salvo no histórico e não é enviado em webhooks de saída.

9. Exemplo inicial em PHP

Este exemplo mostra o começo de uma integração própria: criar.php chama a API pelo servidor e conta.php apresenta o SN e a senha uma única vez.

Arquivo criar.php

Configure o token como variável de ambiente UNITV_API_TOKEN. Não coloque o token no HTML, JavaScript ou repositório público.

Arquivo conta.php

A senha não vai pela URL. Ela fica temporariamente na sessão e é removida assim que a página é aberta.

10. Webhooks

Webhook de entrada

É uma alternativa à URL com ?action=. Este cURL também pode ser importado diretamente no HTTP Request do n8n:

O header Authorization continua obrigatório. O retorno possui o mesmo formato da API.

Também é possível criar uma conta pelo webhook de entrada:

Webhooks de saída

Cadastre uma URL HTTPS pública para receber o resultado das operações. O sistema envia a assinatura no header X-Unitv-Signature, calculada com HMAC SHA-256 e o segredo cadastrado.

Exemplo real do JSON recebido pelo seu webhook:

Headers enviados:

Valide a assinatura antes de aceitar o evento e responda com HTTP 2xx.

Eventos de criação: account.creation.sucesso, account.creation.enviado e account.creation.falha. O JSON do webhook de saída nunca contém a senha da conta.

11. Várias contas UniTV na mesma operação

Um administrador pode conectar mais de uma conta de revendedor UniTV. Cada conexão recebe um conexao_id e mantém credenciais, sessão, saldo e histórico separados.

Use o connection_id retornado como conexao_id na consulta ou operação. Se não informar, a API utiliza a conexão padrão.

Para cadastrar outra conta pela API, use POST action=salvar_conexao com nova_conexao=true. Se o nome não for informado, o sistema cria um nome automático. Para excluir, use POST action=excluir_conexao com confirmar=true; conexões com vínculos ativos precisam ser desvinculadas antes. Nunca coloque credenciais reais em exemplos públicos.

Os vínculos locais passam a registrar qual conexão originou o SN. A mesma chave de idempotência continua protegida, mas operações explicitamente direcionadas a outra conexão recebem escopo próprio.

Importante: o fallback automático entre conexões só deve ocorrer quando o fornecedor confirmar saldo insuficiente. Timeout ou erro de autenticação não deve trocar de painel, evitando uma renovação duplicada.

O fallback é opcional. Sem fallback_conexoes, apenas a conexão escolhida é utilizada.

No site renovar.tectonny.com.br, o Super Admin pode configurar o mesmo comportamento em Painéis UniTV usados pelo site: informe o ID principal e, opcionalmente, os IDs de fallback separados por vírgula. O site preserva o conexao_id da conta localizada ao criar o vínculo e concluir a renovação.

12. Plano PRO e renovação automática

O Super Admin pode alternar cada administrador entre STARTER e PRO. Somente o PRO apresenta, na página Contas, os controles de vencimento e renovação automática.

1. Cadastre e mantenha ativo o vínculo da conta.
2. Em Renovação automática, escolha a data de vencimento e o período: 1, 3 ou 6 meses, ou 1 ano.
3. Marque Renovar automaticamente e salve.
4. Mantenha o fornecedor conectado e saldo suficiente. A operação aparecerá no Histórico com origem AUTO_PRO.

O sistema verifica vencimentos a cada cinco minutos, impede processamento duplicado e atualiza a próxima data depois da confirmação do fornecedor. Em caso de falha, mostra o motivo no painel e aguarda seis horas para uma nova tentativa. Ao voltar para STARTER, as configurações ficam guardadas, mas não são executadas.

12.1. Limites e limpeza administrativa

No menu Super Admin, a área Padrões dos planos define o limite mensal e as permissões padrão de STARTER e PRO. O padrão inicial é 100 operações para STARTER e 1.000 para PRO, mas os valores podem ser alterados.

Marque Aplicar também aos administradores atuais somente quando quiser sobrescrever as políticas individuais daquele plano.

A área Limpar logs e históricos pode remover logs da API, históricos de operações e entregas de webhook. Contas, vínculos, tokens, credenciais e a auditoria do Super Admin são preservados. A confirmação exige digitar APAGAR.

13. Erros comuns

14. Segurança e boas práticas

• Sempre execute simular_criacao antes de criar e simular antes de renovar.
• Guarde tokens e segredos nas credenciais do n8n, nunca diretamente em nodes compartilhados.
• Use uma idempotency_key derivada do pagamento ou pedido.
• Revogue tokens de integrações desativadas.
• Não registre senhas de clientes em logs, planilhas ou mensagens.
• Consulte o menu Histórico para auditar cada operação.