Central de Notificações

Visão funcional

A Central de Notificações é o módulo responsável pelo envio de mensagens automáticas e manuais aos clientes via WhatsApp e e-mail. O envio pode ocorrer de duas formas: manualmente pelo operador, selecionando destinatários e disparando na hora, ou automaticamente pelo sistema em horário configurado.

As categorias de notificação disponíveis são:

• Aniversário – clientes que fazem aniversário no período;
• Cobrança a Vencer – títulos do contas a receber com vencimento próximo, com ou sem boleto bancário gerado;
• Cobrança Vencida – títulos em atraso, com ou sem boleto;
• Cobrança Paga – títulos quitados;
• OS Pronta – ordens de serviço com status de pronta;
• NF-e – notas fiscais eletrônicas emitidas;
• Tipos Personalizados – categorias criadas pelo próprio usuário com SQL customizado (ver seção específica).

Categorias de OS que existem mas não aparecem na tela: o sistema também tem as categorias OS Aberta, OS em Andamento e OS Faturada (códigos OS_ABERTA, OS_ANDAMENTO, OS_FATURADA). Só "OS Pronta" fica visível nos combos de categoria, nos templates e no envio automático da tela; as outras três não aparecem em nenhum desses lugares, mas têm rótulo próprio no filtro de Histórico — ou seja, elas existem para uso via API/integração de outro módulo, e podem aparecer no Histórico sem que o operador tenha configurado nada na Central de Notificações para elas.

Abas da tela

Notificações

Aba principal de consulta e envio manual. O operador filtra por categoria, filial e período, seleciona os destinatários na lista e aciona o envio por WhatsApp, e-mail ou ambos. O sistema exibe progresso em tempo real e permite cancelar o envio em andamento.

Configurações

Aba com quatro sub-abas de configuração:

• WhatsApp – tipo de API, credenciais e intervalo entre envios;
• E-mail – servidor SMTP, porta, criptografia e credenciais;
• Templates – mensagens por categoria e canal;
• Automático – ativação, horário e categorias do envio automático.

Histórico

Exibe registros de todos os envios realizados com filtros por período, tipo (WhatsApp/e-mail) e categoria. O filtro de status tem apenas as opções Todos, Sucesso e Erro; "Reenviado" não é uma opção de filtro — é só um rótulo que aparece na grade para envios que foram reenviados. Permite reenvio de falhas diretamente da tela.

Tipos Personalizados

Gerenciamento das categorias customizadas criadas pelo usuário (ver seção específica). A aba só aparece para usuários com permissão de acesso ao módulo correspondente.

Configuração do WhatsApp

Tipo de API

Existem duas opções de integração com WhatsApp:

• API Oficial (Meta) – integração direta com a API oficial da Meta. Exige Phone ID, Token de acesso e versão da API (ex.: v18.0). Não apresenta risco de bloqueio do número;
• API Não Oficial (uazapi) – emulação web do WhatsApp via uazapi. Exige a criação de uma instância e vinculação do celular por QR Code. Apresenta risco de bloqueio do número em caso de uso inadequado (envio em massa, spam).

Campos da API Oficial

Onde ficam

Central de Notificações > Configurações > WhatsApp > grupo API Oficial Meta

Campos

• Phone ID (NC_WA_PHONEID)
• Token (NC_WA_TOKEN)
• Versão (NC_WA_VERSAO)

Campos da API Não Oficial (uazapi)

Onde ficam

Central de Notificações > Configurações > WhatsApp > grupo API Não Oficial - uazapi

Campos

• Servidor (NC_WA_UAZ_URL) – endereço do servidor uazapi; em branco, usa o servidor padrão do sistema;
• Instância (NC_WA_UAZ_INSTANCIA) – gerado automaticamente pelo sistema na primeira abertura; não editável pelo usuário;
• Token (NC_WA_UAZ_TOKEN) – gerado automaticamente pelo botão Criar Instância; não aparece como campo editável na tela;
• Intervalo entre envios (seg.) (NC_WA_INTERVALO) – tempo de espera entre cada mensagem enviada. Campo compartilhado pelos dois tipos de API.

Ações disponíveis

• Criar Instância – registra a instância no servidor uazapi. Exige que o Admin Token da conta uazapi já esteja gravado em NOTIF_CONFIG.NC_WA_UAZ_ADMTOKEN (não há campo na tela para isso; precisa ser gravado direto no banco);
• Consultar Status – verifica se o WhatsApp está conectado;
• Conectar (QR Code) – exibe o QR Code para leitura pelo celular;
• Desconectar – encerra a sessão do WhatsApp na instância.

O indicador de status (luz vermelha/verde) é atualizado automaticamente a cada 15 segundos enquanto a tela estiver aberta.

Configuração de E-mail

Onde fica

Central de Notificações > Configurações > E-mail

Campos

• Servidor SMTP (NC_EMAIL_SMTP)
• Porta (NC_EMAIL_PORTA)
• Criptografia (NC_EMAIL_SSL) – opções: TLS, SSL, None
• Usuário (NC_EMAIL_USUARIO)
• Senha (NC_EMAIL_SENHA)
• Nome exibido (NC_EMAIL_NOME)
• E-mail de resposta (Reply-To) (NC_EMAIL_REPLY)
• Intervalo entre envios (seg.) (NC_EMAIL_INTERVALO)

O botão Testar E-mail envia uma mensagem de teste para o próprio endereço configurado em Usuário.

Templates de mensagem

Onde fica

Central de Notificações > Configurações > Templates

Cada categoria possui um template separado para WhatsApp e um para E-mail. O template de e-mail inclui campo de assunto. Os templates são salvos por filial.

Variáveis disponíveis

Todas as categorias suportam as variáveis base:

• {NOME} – nome do cliente;
• {TELEFONE} – telefone do destinatário;
• {EMAIL} – e-mail do destinatário.

Variáveis adicionais por categoria:

Categoria	Variáveis extras
Aniversário	{DATA_NASC}
Cobrança a Vencer / Vencida	{VENCIMENTO} {VALOR} {DOCUMENTO} {LINK_BOLETO}
Cobrança Paga	{VENCIMENTO} {VALOR} {DOCUMENTO} (sem {LINK_BOLETO} — ver nota abaixo)
OS Pronta	{NUMERO_OS} {DATA_OS} {VALOR_OS} {STATUS_OS}
NF-e	{NUMERO_NOTA} {EMISSAO} {VALOR_NOTA} {CHAVE} {LINK_NOTA} {LINK_NFE} {LINK_BOLETO}
Tipos Personalizados	{DETALHE1} {DETALHE2} {DETALHE3} {DETALHE4} {REFERENCIA} {REFERENCIA_DOC} + campos retornados pelo SQL

Sobre {LINK_BOLETO} e {LINK_NOTA}/{LINK_NFE}: esses placeholders só são efetivamente substituídos por um link no canal WhatsApp via API Oficial (Meta). Nos demais casos o comportamento é:

• WhatsApp uazapi: o boleto/nota vai anexado como documento (não como link); o placeholder é removido do texto;
• E-mail: o boleto/nota sempre vai anexado em PDF; o placeholder é removido do texto;
• Título sem boleto gerado (ver seção "Cobrança a Vencer, Vencida e Paga"): não há link nem anexo; o placeholder também é removido.

Como o placeholder é apenas removido (não a frase inteira em volta dele), um template escrito como "...você pode baixar o boleto pelo link: {LINK_BOLETO}" fica com a frase incompleta ("...pelo link:") sempre que o link não é usado. Vale revisar os templates de Cobrança pensando nesse caso.

{LINK_BOLETO} não existe para Cobrança Paga: diferente de "a Vencer"/"Vencida", a categoria Cobrança Paga não gera link nem anexo — nunca gerou. Se {LINK_BOLETO} for colocado no template dela, o texto {LINK_BOLETO} aparece literal na mensagem, sem ser substituído por nada.

Cobrança a Vencer, Vencida e Paga

Essas três categorias trabalham em cima do contas a receber (CTARECEB) como um todo. Um título entra na lista independentemente de ter ou não boleto bancário gerado; o que muda é o que é enviado.

Título sem boleto bancário gerado

Quando o título não tem banco vinculado, ou o banco não tem layout de boleto (NOTACAPA) e conta corrente (CONTACORR) configurados para a filial, a notificação é enviada mesmo assim:

• E-mail: enviado sem anexo, só com o texto do template;
• WhatsApp (uazapi ou Meta): enviado só com o texto, sem link e sem documento anexado.

Boleto acumulado (opção "Acumulativo" na impressão de boletos)

Quando o boleto foi gerado de forma acumulada — várias notas/parcelas agrupadas em um único boleto, pela tela Relatórios > Financeiro > Boletos e Duplicatas > Impressão, marcando Acumulativo por Cliente ou Acumulativo por Cliente/Vencimento — a Central de Notificações reconhece o agrupamento automaticamente e:

• Mostra uma única linha na listagem, representando o boleto inteiro (não uma linha por conta a receber);
• O Valor exibido é a soma de todas as contas do grupo (em aberto, para Cobrança a Vencer/Vencida; pagas, para Cobrança Paga);
• O Documento exibido é o número do boleto acumulado (ex.: AC00033);
• O envio — e-mail ou WhatsApp — leva um único PDF, com o valor total e o mesmo nosso número do boleto que seria impresso pela tela de Boletos e Duplicatas;
• O histórico e o controle de reenvio consideram o boleto acumulado como um todo, então a baixa de uma das contas do grupo não faz a notificação ser enviada de novo por engano.

Envio Automático

Onde fica

Central de Notificações > Configurações > Automático

O sistema verifica a cada minuto se chegou o horário de envio e, se sim, dispara o processamento em segundo plano sem intervenção do usuário.

Campos de configuração

• Ativo (NC_AUTO_ATIVO) – habilita ou desabilita o envio automático da filial;
• Hora de envio (NC_AUTO_HORA / NC_AUTO_MINUTO) – horário em que o envio deve ocorrer (formato HH:MM);
• Canais (NC_AUTO_CANAIS) – WhatsApp e/ou E-mail;
• Categorias (NC_AUTO_CATEGORIAS) – quais categorias devem ser processadas automaticamente.

Atenção: "OS Pronta" aparece marcável nesta lista, mas nunca é enviada pelo automático. O checklist de categorias mostra toda categoria visível na tela (inclusive OS Pronta), mas o processamento automático só existe, de fato, para: Aniversário, Cobrança a Vencer, Cobrança Vencida, Cobrança Paga, NF-e e Tipos Personalizados. Marcar "OS Pronta" na aba Automático não tem efeito nenhum — essa categoria só é enviada manualmente, pela aba Notificações.

Regra de execução

• O sistema só executa uma vez por dia por filial (controla pela data em NC_AUTO_ULTIMODIA);
• Categorias não marcadas são ignoradas;
• Se nenhum canal estiver habilitado, o envio é abortado;
• Boleto acumulado é processado como um único envio, mesmo no automático (ver seção "Cobrança a Vencer, Vencida e Paga").

O período processado NÃO é "dia anterior" para todas as categorias. O sistema sempre calcula a data de corte como "ontem" (Date - 1), mas cada categoria usa esse valor de um jeito diferente:

Categoria	Período efetivamente processado
Aniversário	Ignora a data de corte: sempre processa aniversariantes de hoje
Cobrança a Vencer	De ontem até hoje (inclui vencimentos do dia)
Cobrança Vencida	Só ontem
Cobrança Paga	De ontem até hoje (inclui pagamentos do dia)
NF-e	Só ontem

Na prática: um aniversário, uma cobrança a vencer ou um pagamento de hoje já entra no próximo ciclo automático (mesmo dia seguinte de manhã); só Cobrança Vencida e NF-e realmente esperam até o dia seguinte ao registro.

Tipos Personalizados

Onde fica

Central de Notificações > aba Tipos Personalizados

Permite criar categorias de notificação próprias, com SQL personalizado definido pelo usuário. Cada tipo personalizado aparece automaticamente nas abas de Notificações (envio manual), Templates e nas categorias do Envio Automático.

Campos do cadastro

• Descrição (NP_DESCRICAO) – nome da categoria exibido na interface;
• Ativo (NP_ATIVO) – somente tipos ativos aparecem nas listas;
• Limite de envios (NP_LIMIT) – quantidade máxima de registros processados por execução; 0 = sem limite. Vale só para o envio automático — não restringe disparos manuais pela aba Notificações;
• SQL (NP_SQL) – consulta SQL que retorna os destinatários;
• Col 1 a Col 4 (NP_COL1_CAPTION a NP_COL4_CAPTION) – rótulos das colunas extras exibidas na listagem de envio manual.

Colunas obrigatórias no SQL

O SQL deve retornar obrigatoriamente as seguintes colunas:

• CLIENTE_ID – código do cliente;
• NOME – nome do destinatário;
• FONE – número de WhatsApp;
• EMAIL – endereço de e-mail;
• REFERENCIA – identificador único do registro (usado para controle de reenvio).

Colunas opcionais que alimentam os placeholders do template:

• DETALHE1 a DETALHE4 – informações extras usadas via {DETALHE1}…{DETALHE4};
• REFERENCIA_DOC – número de documento para exibição no histórico.

Parâmetros disponíveis no SQL

• :FILIAL – código da filial atual;
• :DATA_DE ou :DE – data de início do período;
• :DATA_ATE ou :ATE – data de fim do período;
• :REENVIO – 'S' ou 'N'. No envio manual reflete a opção "Permitir reenvio" marcada na tela; no envio automático vem sempre 'N'. Útil para o SQL decidir se deve ou não repetir registros já enviados.

Regra de controle de reenvio

O sistema filtra automaticamente registros que já foram enviados com sucesso, comparando REFERENCIA e categoria na tabela NOTIF_HISTORICO. Assim, o mesmo registro não é enviado duas vezes no automático nem no manual (quando a opção de reenvio não está marcada).

Validação de placeholders

Ao salvar o template de um tipo personalizado, o sistema valida se todas as variáveis usadas no texto ({...}) são campos efetivamente retornados pelo SQL cadastrado. Se um placeholder não existir no SQL, a gravação é bloqueada com mensagem indicando os campos disponíveis.

Permissões

Módulo	Descrição
Central de Notificações – Tipos Personalizados (324)	Habilita a aba de Tipos Personalizados na Central de Notificações. Sem esta permissão, a aba fica oculta.

Comportamentos importantes

Mensagem não chega por WhatsApp

Conferir, nesta ordem:

1. Se a instância está conectada (botão Consultar Status deve mostrar "Conectado").

2. Se o número do cliente possui WhatsApp ativo – o sistema valida antes do envio.

3. Se o template de WhatsApp da categoria está preenchido.

4. Se o canal WhatsApp está habilitado nos canais selecionados no momento do envio.

Mensagem não chega por e-mail

Conferir:

1. Configurações de SMTP (servidor, porta, criptografia, usuário e senha) usando o botão Testar E-mail.

2. Se o cliente possui e-mail cadastrado.

3. Se o template de e-mail da categoria está preenchido.

Tipo personalizado não aparece nas categorias

Conferir:

1. Se o campo Ativo do tipo personalizado está marcado.

2. Se o SQL está salvo corretamente (sem erros de sintaxe).

A lista de categorias é recarregada automaticamente ao gravar ou excluir um tipo personalizado — não é preciso fechar e reabrir a tela.

Envio automático não disparou

Conferir, nesta ordem:

1. Se NC_AUTO_ATIVO = 'S' para a filial.

2. Se o horário configurado já passou no dia corrente.

3. Se NC_AUTO_ULTIMODIA já está preenchido com a data de hoje (indica que já executou).

4. Se ao menos um canal (WA ou e-mail) está marcado.

5. Se ao menos uma categoria está marcada.

Registro aparece na consulta mas não é enviado no automático

Duas causas possíveis:

• A categoria é "OS Pronta": essa categoria não é processada pelo envio automático, mesmo aparecendo marcável na aba Automático (ver seção "Envio Automático");
• O registro é muito recente: cada categoria de Cobrança/NF-e/Aniversário tem sua própria regra de corte por data — ver a tabela em "Envio Automático" para saber exatamente quando cada uma passa a ser processada. Isso é intencional, para evitar inconsistência no controle de execução diária.

Atualização de banco (estrutura criada pelo módulo)

Tabelas criadas:

• NOTIF_CONFIG – configuração de WhatsApp e e-mail por filial;
• NOTIF_TEMPLATE – templates de mensagem por categoria, tipo e filial;
• NOTIF_HISTORICO – histórico de todos os envios realizados;
• NOTIF_TIPO_PERS – cadastro dos tipos de notificação personalizados.

Campos relevantes de NOTIF_CONFIG:

• NC_AUTO_ATIVO, NC_AUTO_HORA, NC_AUTO_MINUTO, NC_AUTO_CANAIS, NC_AUTO_CATEGORIAS, NC_AUTO_ULTIMODIA – controle do envio automático.