Central de Notificações

De Office System
Revisão de 17h25min de 11 de agosto de 2026 por Vitor (discussão | contribs) (→‎Cobrança a Vencer, Vencida e Paga)
(dif) ← Edição anterior | Revisão atual (dif) | Versão posterior → (dif)
Ir para navegação Ir para pesquisar

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.
Disponível em “https://wiki.officesystem.com.br/index.php?title=Central_de_Notificações&oldid=2389”