Motor de Regras

O motor de regras é um mecanismo do Maestro para gerenciar e supervisionar os disparos feitos pelas assessorias. A Gerente do Ambiente pode configurar diversas regras dentro deste motor e essas regras serão verificadas durante campanhas, disparos por API ou upload de campanhas por SFTP.

Configuração Inicial

O acesso às regras deve ser feito com perfil Gerente do Ambiente em: Configurações > Regras

Tipos de regras

Há dois tipos primários de regras: 1. Regras implícitas
Estas regras validam conceitos do sistema e não podem ser desativadas. 2. Regras customizáveis
Cada regra customizável pode ser ativada ou desativada.

Regras implícitas

Algumas regras não são exibidas no motor de regras mas rodam como validadores de disparos e campanhas no Maestro:

• Segmento válido

A assessoria só consegue criar templates, criar campanhas e disparar mensagens em segmentos que possui acesso.

• Template aprovados

Apenas templates aprovados são válidos para criar campanhas e disparar mensagens. Se houver broker configurado para o canal utilizado, o template deve estar “Publicado”. Se não houver broker configurado, a mensagem não será disparada, mas o template será considerado válido e poderá ser utilizado para integrações externas Templates expirados não ficam disponíveis para uso após a rotina de expiração. Templates vencidos há mais de 5 dias não devem aparecer na lista de seleção.

• DDD e Telefone

Quando o disparo é efetuado para um telefone (WhatsApp ou SMS):

Campanhas devem ter DDD mapeado corretamente.
Telefones com formatação inválida serão rejeitados.

Regras customizáveis

Essas regras podem ser ativadas ou desativadas individualmente.

• Horários

Campanhas e disparos fora da faixa configurada são bloqueados. Há dois modos de configuração, que podem coexistir:

Horário comercial: janela fixa aplicada de segunda a sexta-feira.
Períodos específicos: intervalos com datas de início e fim, que permitem incluir sábados e domingos. Múltiplos intervalos podem ser cadastrados.

• Feriados

Campanhas e disparos são bloqueados nos dias configurados como feriado. A regra opera em dois níveis independentes:

Bloqueio por feriados nacionais (ativável separadamente).
Bloqueio por datas avulsas inseridas manualmente.

• Localidades

Permite definir janelas de envio diferenciadas por localidade do contato. Quando ativa, disparos fora do horário permitido para a localidade do destinatário são bloqueados.

• Contatos

Permite autorizar ou bloquear contatos específicos no momento de enviar as mensagens.

Escopo do bloqueio

O bloqueio se aplica quando todos os campos preenchidos na entrada coincidem com o envio. Quanto mais campos informados, mais específico e restrito é o escopo. Exemplo

Apenas telefone preenchido → qualquer envio para aquele telefone é bloqueado, independente do contrato.
Telefone + contrato preenchidos → somente a combinação exata é bloqueada. Envios para o mesmo telefone com outro contrato, ou para o mesmo contrato com outro telefone, não são afetados.

⚠️ Contatos duplicados serão rejeitados pelo motor de regras

1. Contatos Autorizados

Somente contatos presentes na lista poderão receber mensagens pelos canais selecionados. A lista é atualizada via arquivos CSV no diretório maestro/allow_list do SFTP. A regra é aplicada apenas nos canais explicitamente configurados — outros canais não são afetados.

Campo	Obrigatório	Descrição
CPF_CNPJ	❌	Documento do cliente (para validações ou relatórios).
NUCONTRATOGESTAO	❌	Número do contrato do cliente.
NUMERO	✅ se EMAIL não estiver preenchido	Número de telefone com DDD do cliente.
EMAIL	✅ se NUMERO não estiver preenchido	E-mail do cliente.

ℹ️ É possível fazer combinações misturando os campos acima. A combinação que não pode ser feita no mesmo contato é o “numero” e “email”.
Exemplo Inválido
   CPF_CNPJ;NUCONTRATOGESTAO;NUMERO;EMAIL
🚫 12345678965;456;+5511981236549;cliente@dominio.com

Exemplo Válido

CPF_CNPJ;NUCONTRATOGESTAO;NUMERO;EMAIL
12345678965;456;+5511981236549;
98765432156;654;;cliente@dominio.com

2. Contatos Bloqueados

Contatos presentes na lista são impedidos de receber mensagens em qualquer canal. A lista é atualizada via arquivos CSV no diretório maestro/block_list do SFTP.

⚠️ Contatos bloqueados prevalecem em relação aos contatos autorizados
Isso significa que se um contato for importado nas duas regras (Autorizados e Bloqueados), ele será bloqueado.

Campo	Obrigatório	Descrição
TIPO_BLOQUEIO	❌	Tipos permitidos: 1 (Permanente)	2 (Temporário)	Vazio.
CPF_CNPJ	❌	Documento do cliente (para validações ou relatórios).
DATA_SOLICITACAO	❌	Data da solicitação do bloqueio.
DATA_EXPIRACAO	❌	Data de expiração do bloqueio.
NUCONTRATOGESTAO	❌	Número do contrato do cliente.
NUMERO	❌	Número de telefone com DDD do cliente.
EMAIL	❌	E-mail do cliente.
MOTIVO	❌	Motivo do bloqueio.

ℹ️ É possível fazer combinações misturando os campos acima. A combinação que não pode ser feita no mesmo contato é o “numero” e “email”.
Exemplo Inválido
   TIPO_BLOQUEIO;CPF_CNPJ;DATA_SOLICITACAO;DATA_EXPIRACAO;NUCONTRATOGESTAO;NUMERO;EMAIL;MOTIVO
🚫 2;12313213213;;;1516;+5511930457438;cliente@dominio.com;Motivo 1

Exemplo Válido

TIPO_BLOQUEIO;CPF_CNPJ;DATA_SOLICITACAO;DATA_EXPIRACAO;NUCONTRATOGESTAO;NUMERO;EMAIL;MOTIVO
2;12313213213;;;1516;;cliente@dominio.com;Motivo 1
;45665465464;;25/04/2026;;+5511930457438;;Motivo 2

• Domínios

Domínios configurados terão todas as tentativas de disparo rejeitadas.

• Limites

1. Limite de erros por arquivo de Público

Se o percentual de erros no arquivo da campanha ultrapassar o limite configurado, a base inteira é invalidada e nenhum disparo é efetuado. Caso o limite esteja configurado em 0%, nenhuma base será invalidada por esta regra, mesmo ela estando ativa.

2. Limite diário de disparos por contrato

Cada contrato tem uma cota diária de mensagens. Ao atingir o limite, novos disparos daquele contrato são bloqueados para o restante do dia. Se um contato (e-mail ou telefone) estiver vinculado a mais de um contrato:

O contrato que ultrapassar o limite será bloqueado.
O contrato dentro do limite terá o disparo processado normalmente.

Como o motor de regras funciona?

Campanhas

Ao se criar uma nova campanha, o motor de regras é executado. A criação da campanha será rejeitada caso as seguintes regras forem inválidas:

Regra de Horário
Bloqueio por Feriado
Limite de erros por arquivo de Público

Caso as regras acima sejam válidas, a campanha será criada e cada disparo será efetuado. O disparo pode ser bloqueado caso as seguintes regras forem inválidas:

Contatos Autorizados / Contatos Bloqueados
Restrições de horário por Localidade
Limite diário de disparos por contrato
Bloqueio por Domínio de Email

API Direct Message

Cada chamada da API Direct Message é considerado um disparo avulso. O disparo será bloqueado caso uma regra seja quebrada. 409 - Conflict

{
      "message": "Erro na validação do Motor de Regras.",
      "errors": {},
      "record_errors": [],
      "conflicts": [
        "Domínio de e-mail bloqueado na Lista de Restrição",
        "E-mail bloqueado na Lista de Restrição"
      ],
      "requestId": "00-80016a94505f232820c73054f2ee1fa2-12c5228b9f317e12-00"
    }

Para mais informações, consulte a documentação da API Direct Message

SFTP

Valida todo o arquivo linha a linha. Caso alguma linha seja invalidada por alguma regra, no arquivo final da importação, criado na pasta /maestro/campaigns/processed, será criado um arquivo {nome original}_EXCEPTIONS.csv com todas as exceções que foram encontradas durante a validação do arquivo importado.

Este arquivo contém a cópia da linha original com uma coluna adicional Motivo Falha exibindo o porquê do contato não ter sido processado

Exemplo:

(Outras colunas...),MotivoFalha
...,Excedido o limite de envios diários para esse contato
...,Número bloqueado na lista de restrição
...,Envio bloqueado fora do horário permitido para este código de área

Histórico

No botão histórico de cada regra é possível ver as alterações que cada regra teve com o tempo, incluindo o usuário que realizou a alteração e qual foi a alteração. FAQ

O que acontece se eu tentar criar uma campanha fora do horário permitido?

A campanha não será criada, pois o motor valida a regra de horário durante a criação.

Campanhas são enviadas em feriados?

Não. Em dias configurados como feriado, os disparos são bloqueados automaticamente.

E se o percentual de erros da base for maior que o limite configurado?

A base será invalidada e a campanha não seguirá adiante.

Posso reutilizar templates expirados?

Não. Templates expirados ficam indisponíveis após a rotina de expiração e não aparecem na lista de seleção.

O que ocorre se o nome do arquivo enviado via SFTP estiver fora do padrão?

O arquivo será rejeitado e não será processado.

​Motor de Regras

​Configuração Inicial

​Tipos de regras

​Regras implícitas

​• Segmento válido

​• Template aprovados

​• DDD e Telefone

​Regras customizáveis

​• Horários

​• Feriados

​• Localidades

​• Contatos