> ## Documentation Index > Fetch the complete documentation index at: https://docs.maestro.robbu.global/llms.txt > Use this file to discover all available pages before exploring further. # Motor de Regras > Regras de restrição, bloqueio e controle aplicadas às campanhas no Maestro. O motor de regras é um mecanismo do Maestro para gerenciar e supervisionar os envios de mensagens feitos pelas assessorias. A Gerente do Ambiente pode configurar diversas regras dentro deste motor, e essas regras são verificadas durante campanhas, envios por API (Direct Message) 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** — validam conceitos do sistema e não podem ser desativadas. 2. **Regras customizáveis** — cada uma pode ser ativada ou desativada individualmente. ## Regras implícitas Algumas regras não são exibidas no motor de regras, mas rodam como validadores de envios e campanhas: ### Segmento válido A assessoria só consegue criar templates, criar campanhas e enviar mensagens em segmentos aos quais tem acesso. ### Template aprovado Apenas templates aprovados são válidos para criar campanhas e enviar mensagens. * Se houver provedor configurado para o canal utilizado, o template deve estar **Publicado**. * Se não houver provedor configurado, a mensagem não será enviada, mas o template é considerado válido e pode ser usado para integrações externas. * Templates expirados não ficam disponíveis para uso após a rotina de expiração — vencidos há mais de 5 dias causam o bloqueio do envio. ### DDD e Telefone Quando o envio é feito para um telefone (WhatsApp ou SMS): * Campanhas devem ter DDD mapeado corretamente. * Telefones com formatação inválida são rejeitados. ## Regras customizáveis ### Horários Campanhas e envios fora da faixa configurada são bloqueados. Dois modos coexistem: * **Horário comercial** — janela fixa de segunda a sexta-feira. * **Períodos específicos** — intervalos com datas de início e fim, podendo incluir sábados e domingos. Múltiplos intervalos podem ser cadastrados. ### Feriados Campanhas e envios são bloqueados nos dias configurados como feriado, em dois níveis independentes: * Bloqueio por feriados nacionais (ativável separadamente). * Bloqueio por datas avulsas inseridas manualmente. ### Localidades Define janelas de envio diferenciadas por localidade do contato. Quando ativa, envios fora do horário permitido para a localidade do destinatário são bloqueados. ### Contatos Permite autorizar ou bloquear contatos específicos no momento do envio. **Escopo do bloqueio**: aplica-se 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 → só a combinação exata é bloqueada. Contatos duplicados são rejeitados pelo motor de regras. #### 1. Contatos Autorizados Somente contatos presentes na lista podem receber mensagens pelos canais selecionados. A lista é atualizada via arquivos CSV no diretório `maestro/allow_list` do SFTP. A regra se aplica apenas aos canais explicitamente configurados. Se o arquivo do cliente usa nomes de coluna diferentes dos abaixo, um [Mapeamento de Layout de Importação](/integracoes/mapeamento-de-layouts) (tipo "Lista de Contatos Autorizados") pode traduzi-los automaticamente. | Campo | Obrigatório | Descrição | | ----------------- | ---------------------------------- | ------------------------------------------------ | | `document_number` | ❌ | Documento do cliente (validações ou relatórios). | | `contract_code` | ✅ (coluna deve existir no arquivo) | Número do contrato do cliente. | | `phone_number` | ✅ (coluna deve existir no arquivo) | Número de telefone com DDD. | | `email` | ❌ | E-mail do cliente. | É possível combinar os campos acima. A única combinação inválida no mesmo contato é `phone_number` + `email` preenchidos simultaneamente na mesma linha. ``` Exemplo inválido: document_number;contract_code;phone_number;email 12345678965;456;+5511981236549;cliente@dominio.com ❌ (telefone e e-mail juntos) Exemplo válido: document_number;contract_code;phone_number;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 sobre contatos autorizados — se um contato estiver nas duas listas, ele é bloqueado. Se o arquivo do cliente usa nomes de coluna diferentes dos abaixo, um [Mapeamento de Layout de Importação](/integracoes/mapeamento-de-layouts) (tipo "Lista de Bloqueio") pode traduzi-los automaticamente. | Campo | Obrigatório | Descrição | | -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `block_type` | ❌ | Ação a aplicar: `1` bloqueia permanentemente, `2` bloqueia temporariamente, `3` desbloqueia (remove) o contato. Vazio segue o comportamento padrão de bloqueio. | | `document_number` | ❌ | Documento do cliente. | | `block_requested_at` | ❌ | Data da solicitação do bloqueio. | | `block_expires_at` | ❌ | Data de expiração do bloqueio. | | `contract_code` | ✅ (coluna deve existir no arquivo) | Número do contrato do cliente. | | `phone_number` | ✅ (coluna deve existir no arquivo) | Número de telefone com DDD. | | `email` | ✅ (coluna deve existir no arquivo) | E-mail do cliente. | | `reason` | ❌ | Motivo do bloqueio. | A única combinação inválida no mesmo contato é `phone_number` + `email` preenchidos simultaneamente na mesma linha. ``` Exemplo inválido: block_type;document_number;block_requested_at;block_expires_at;contract_code;phone_number;email;reason 2;12313213213;;;1516;+5511930457438;cliente@dominio.com;Motivo 1 ❌ Exemplo válido: block_type;document_number;block_requested_at;block_expires_at;contract_code;phone_number;email;reason 2;12313213213;;;1516;;cliente@dominio.com;Motivo 1 ;45665465464;;25/04/2026;;+5511930457438;;Motivo 2 ``` ### Domínios Domínios de e-mail configurados têm todas as tentativas de envio 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 envio é efetuado. Com o limite em 0%, nenhuma base é invalidada por esta regra, mesmo ativa. **2. Limite diário de envios por contrato**: cada contrato tem uma cota diária de mensagens. Ao atingir o limite, novos envios daquele contrato são bloqueados pelo restante do dia. Se um contato estiver vinculado a mais de um contrato, apenas o contrato que ultrapassar o limite é bloqueado. Campanhas agendadas consomem a cota do dia do **processamento**, não do dia da entrega. O contador é incrementado quando a campanha é processada (logo após a criação) — uma campanha criada hoje e agendada para amanhã consome a cota de hoje, não a de amanhã. ## Como o motor de regras funciona ### Campanhas Ao processar uma campanha, o motor de regras avalia cada linha (contato) do público individualmente contra: * Regra de Horário * Bloqueio por Feriado * Contatos Autorizados / Contatos Bloqueados * Restrições de horário por Localidade * Limite diário de envios por contrato * Bloqueio por Domínio de E-mail Uma linha que quebra qualquer uma dessas regras é bloqueada individualmente, sem afetar as demais. Por último, depois de todos os contatos verificados, é avaliado o **Limite de erros por arquivo de Público** — a única regra que olha para o público como um todo, contabilizando o percentual de contatos inválidos. Se esse percentual ultrapassar o limite configurado, a base inteira é invalidada e nenhum envio é efetuado. ### API Direct Message Cada chamada é considerada um envio avulso, bloqueado caso quebre alguma regra: ```json title="409 - Conflict" theme={null} { "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" } ``` Veja mais em [Direct Message API](/integracoes/direct-message-api). ### SFTP Valida o arquivo linha a linha. Linhas invalidadas geram, na pasta `/maestro/campaigns/processed`, um arquivo `{nome original}_EXCEPTIONS.csv` com a cópia da linha original e uma coluna adicional `Motivo Falha`: ``` (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 realizadas ao longo do tempo, incluindo o usuário responsável e o que foi alterado. ## FAQ A campanha não será criada, pois o motor valida a regra de horário durante a criação. Não. Em dias configurados como feriado, os envios são bloqueados automaticamente. A base será invalidada e a campanha não seguirá adiante. Não. O uso de templates expirados causa o bloqueio do envio. Para campanhas, não há validação de nome de arquivo — qualquer nome é aceito. A validação de nome de arquivo existe apenas na importação de templates via SFTP, que segue o padrão `{segmento}_{canal}_[{waba}]_{data}.csv` — veja [Uso de SFTP](/integracoes/uso-de-sftp). De hoje. O contador da cota diária é incrementado no momento em que a campanha é processada (logo após a criação), não quando a mensagem é enviada. O limite diário sempre vale para o dia do processamento, nunca para o dia da entrega.