> For the complete documentation index, see [llms.txt](https://docs.docbits.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docbits.com/portuguese/administration-and-setup/settings/global-settings/document-types/custom-validation-rules.md). # Regras de Validação Personalizadas ## Visão Geral As regras de validação personalizadas permitem que um administrador defina **suas próprias verificações** nos dados que o DocBits extrai de um documento — sem escrever um script e sem esperar por uma alteração no produto. Uma regra responde a três perguntas: 1. **Onde** o problema é exibido? Em um campo de cabeçalho ou em uma célula de uma linha de tabela. 2. **Quando** a regra se aplica? Sempre, ou somente para documentos (ou linhas) que atendem a uma condição — veja [Condições da Regra (Applies when)](/portuguese/administration-and-setup/settings/global-settings/document-types/rule-conditions-applies-when.md). 3. **O que** deve ser verdadeiro? Um campo deve estar preenchido, corresponder a um formato, estar dentro de um intervalo, corresponder a uma lista, ser comparado corretamente com outro campo ou fechar a soma. Quando a verificação falha, o DocBits marca o campo ou a célula na **tela de validação** e exibe a sua mensagem — exatamente como uma verificação nativa. Com a severidade **Error**, o documento não pode ser validado até que o problema seja corrigido; com **Warning**, o usuário vê apenas uma dica. As regras são definidas por **tipo de documento** e são executadas em todos os documentos desse tipo: durante o processamento e sempre que o documento é salvo. ### Problemas que elas resolvem | Requisito de negócio | Sem regras personalizadas | Com uma regra personalizada | | ------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- | | Faturas alemãs acima de 250 EUR devem exibir o número de identificação fiscal do fornecedor | um script, ou os usuários precisam se lembrar | **Required** em Supplier Tax ID, *applies when* a origem é DE e o valor total é maior que 250 | | Os números de fatura de um fornecedor sempre têm o formato `INV-123456` | erros de digitação chegam ao ERP | **Pattern** `^INV-\d{6}$` em Invoice Number para esse fornecedor | | Toda linha de artigo precisa de uma quantidade maior que zero | linhas com quantidade 0 são exportadas | **Range** (mínimo 0,01) na coluna Quantity | | A data de vencimento não pode ser anterior à data da fatura | execuções de pagamento incorretas | **Compare fields**: Due Date na data da fatura ou depois dela (Invoice Date) | | As linhas devem somar o valor líquido | apenas a verificação nativa fixa | **Formula** `sum(row.NET_AMOUNT) == header.total_net_amount` com a sua própria tolerância | | Somente moedas conhecidas pelo seu ERP são permitidas | erros de exportação no ERP | **List of Values** em Currency | | Avisar os usuários sobre valores incomuns sem bloqueá-los | não é possível | qualquer regra com a severidade **Warning** | ## Ativar as regras de validação personalizadas As regras de validação personalizadas são ativadas **por tipo de documento**. Não existe uma chave geral para toda a organização. 1. Acesse **Settings → Global Settings → Document Types**. 2. No cartão do tipo de documento, clique no ícone de **configurações** (engrenagem). 3. Abra a seção **Custom Validation Rules** e ative o alternador. 4. Clique em **Manage validation rules** para abrir a lista de regras.
Os alternadores de regras nas configurações adicionais de um tipo de documento

Os alternadores de Manage Layouts, Custom Validation Rules e Transformation Rules

A partir de agora, o cartão do tipo de documento também mostra um link **Validation Rules**.
O cartão do tipo de documento com o link Validation Rules

Os links no cartão do tipo de documento

{% hint style="warning" %} **O alternador substitui as verificações de valores nativas.** Enquanto as regras de validação personalizadas estiverem ativadas para um tipo de documento, as verificações fixas "valor total = valor líquido + valor do imposto" e as verificações de valor de linha / desconto **não** são executadas para ele; as regras configuráveis tomam o lugar delas. Recrie como regras as verificações nas quais você confia (veja as [receitas](#receitas)) antes de ativá-lo. Desativar o alternador restaura as verificações nativas. Todas as outras validações de campo (campos obrigatórios, formatos, dados mestres) continuam sendo executadas. {% endhint %} ## A lista de regras **Document Types → (tipo de documento) → Validation Rules** lista todas as regras do tipo de documento.
A lista de regras de validação

A lista de regras com nível, severidade, campo de destino e origem de cada regra

Cada cartão mostra o nome e a descrição da regra, além dos selos de seu **nível** (Header / Line / Table), **severidade** (Error / Warning), do **campo** ao qual o erro está associado e de sua **origem**. Use o interruptor à direita para ativar ou desativar uma regra e o menu **⋮** para duplicá-la ou excluí-la. Filtre a lista por nível (**All / Header / Line / Table**) e por estado (**All / Active / Inactive**), ou pesquise nela. ### Regras System default, Customized e Custom | Origem | O que é | O que você pode fazer | | ------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **System default** | Uma regra fornecida com o DocBits para todas as organizações. | Ela não pode ser editada diretamente — o construtor exibe "This is a system default rule and cannot be edited." Clique em **Customize** para criar sua própria cópia editável, ou desative-a para que deixe de valer para a sua organização. | | **Customized** | Uma regra padrão do sistema que a sua organização alterou ou desativou. | Edite-a como uma regra própria. **Reset to Default** exclui a sua cópia e restaura a original. | | **Custom** | Uma regra criada pela sua organização. | Editar, **Duplicate**, **Delete**. | As alterações nas regras padrão do sistema nunca afetam outras organizações. ## Criar uma regra Clique em **New rule**. O construtor tem três etapas. **Test rule** e **Save** ficam no canto superior direito. ### Etapa 1 — Nome e escopo
Etapa 1 do construtor de regras de validação para uma regra de campo de cabeçalho

Etapa 1 para uma regra de campo de cabeçalho

| Configuração | O que faz | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Rule level** | O que a regra analisa e onde o erro é exibido — veja [Níveis de regra](#niveis-de-regra). | | **Severity** | **Error** marca o campo como inválido e bloqueia a validação. **Warning** mostra a mensagem, mas nunca bloqueia. | | **Rule Name** | Exibido na lista e para os administradores. Faça com que descreva a regra ("Supplier tax ID required for German invoices"). | | **Rule key** | Uma chave técnica gerada a partir do nome. Ela permanece a mesma quando você renomeia a regra mais tarde. Clique no lápis para escolher sua própria chave antes do primeiro salvamento; depois disso, ela fica fixa. | | **Description** | Explicação opcional para outros administradores. | | **Table name** | *Somente para linha de tabela.* A tabela cujas linhas são verificadas, por exemplo `INVOICE_TABLE`. | | **Attach error to field / column** | O campo (ou, para linhas de tabela, a coluna) que exibe o erro na tela de validação. | #### Níveis de regra | Nível | Executa | O erro é exibido em | Pode ler | Regra típica | | ---------------- | ------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | **Header field** | uma vez por documento | um campo de cabeçalho | `header.*`, `doc.*` | "O número de identificação fiscal do fornecedor é obrigatório para faturas alemãs" | | **Table line** | uma vez para cada linha da tabela selecionada | a célula da linha com falha | `row.*` (a linha atual), `header.*`, `doc.*` | "A quantidade deve ser maior que zero" | | **Whole table** | uma vez por documento, analisando todas as linhas em conjunto | um campo de cabeçalho | totais sobre as linhas (`sum()`, `count()`, `min()`, `max()`), `header.*`, `doc.*` | "Os valores líquidos das linhas devem somar o valor líquido" |
Etapa 1 para uma regra de linha de tabela

Uma regra de linha de tabela: a tabela e a coluna que exibe o erro

### Etapa 2 — Applies when Decida se a regra é executada para todos os documentos ou apenas para alguns. Deixe vazio para verificar todos os documentos. Caso contrário, adicione linhas de condição — por exemplo "Document Origin is Deutsch" e "Total Amount greater than 250" — e combine-as com **All** / **ANY** e grupos aninhados.
Uma condição Applies when

A verificação só é executada para documentos alemães acima de 250 com EUR ou sem moeda

Para regras de linha de tabela, a condição também pode usar as colunas da linha atual e é avaliada **linha por linha**: as linhas que não correspondem simplesmente não são verificadas.
Uma condição de linha

Somente as linhas de artigo (linhas com número de item) são verificadas

As condições são explicadas em detalhes — cada campo, operador e regra de comparação, com muitos exemplos — em [Condições da Regra (Applies when)](/portuguese/administration-and-setup/settings/global-settings/document-types/rule-conditions-applies-when.md). ### Etapa 3 — Verificação: o que deve ser verdadeiro Escolha uma verificação. As configurações abaixo dos cartões mudam conforme a verificação escolhida.
Etapa 3 com a verificação Required selecionada

As sete verificações. Required não precisa de configurações adicionais

#### Required — o campo deve ter um valor
uma verificação Required

Uma verificação Required: sem configuração adicional

Falha quando o campo está vazio (ausente ou contendo apenas espaços). Sem configurações adicionais. Use-a junto com **Applies when** para tornar um campo obrigatório **condicionalmente**. Um campo que deve estar sempre preenchido é melhor configurado como campo obrigatório nas configurações do campo. > *Supplier Tax ID é obrigatório* — aplica-se quando *Document Origin is Deutsch* e *Total Amount greater than 250*. #### Formula — os valores devem fechar a soma Uma comparação aritmética. A expressão contém exatamente **uma** comparação (`==`, `!=`, `>`, `>=`, `<`, `<=`); ambos os lados podem usar `+ - * /`, números, parênteses e referências a campos.
Uma verificação Formula

Uma fórmula de tabela inteira com tolerância e marcadores de posição na mensagem

* Clique nos chips abaixo da expressão para inserir funções e prefixos de campo: `sum()`, `count()`, `min()`, `max()`, `default()`, `coalesce()`, `header.`, `doc.`. Enquanto você digita o nome de um campo, uma lista de campos correspondentes é aberta. * `sum(row.NET_AMOUNT)`, `count(row.ITEM_NUMBER)`, `min(...)`, `max(...)` funcionam sobre todas as linhas e só estão disponíveis no nível **Whole table**. `count()` conta as linhas em que a coluna está preenchida. * `default(header.discount, 0)` usa `0` quando o campo está vazio; `coalesce(header.a, header.b, 0)` usa o primeiro valor preenchido. * **Tolerance**: para `==` e `!=`, diferenças de até este valor são consideradas iguais. Use `0.01` ou `0.05` para absorver arredondamentos. Não tem efeito em `<`, `>`, `<=` e `>=`. * Valores vazios ou ilegíveis contam como `0`. Uma divisão por zero ignora a regra em vez de gerar um erro. * Na mensagem de erro, `{actual}` é substituído pelo resultado do lado esquerdo e `{expected}` pelo resultado do lado direito. Exemplos: | Finalidade | Nível | Expressão | Tolerância | | -------------------------------------------- | ------------ | -------------------------------------------------------------------------- | ---------- | | Os totais do cabeçalho são consistentes | Header field | `header.total_amount == header.total_net_amount + header.total_tax_amount` | 0.01 | | As linhas somam o valor líquido | Whole table | `sum(row.NET_AMOUNT) == header.total_net_amount` | 0.05 | | Valor da linha = quantidade × preço unitário | Table line | `row.NET_AMOUNT == row.QUANTITY * row.UNIT_PRICE` | 0.01 | | Imposto não superior a 19 % do valor líquido | Header field | `header.total_tax_amount <= header.total_net_amount * 0.19` | – | | Pelo menos uma linha | Whole table | `count(row.ITEM_NUMBER) >= 1` | 0 | #### Pattern — corresponder a um formato / regex
uma verificação Pattern

Uma verificação Pattern com uma expressão regular

O valor deve corresponder a uma **expressão regular**. A expressão procura dentro do valor; portanto, ancore-a com `^` (início) e `$` (fim) quando o valor inteiro precisar corresponder. Marque **Case-insensitive match** se a diferença entre maiúsculas e minúsculas não importar. | Formato | Expressão regular | | -------------------------------------------------- | -------------------------------- | | `INV-` seguido de seis dígitos | `^INV-\d{6}$` | | Número de IVA alemão (VAT ID) | `^DE\d{9}$` | | Pedido de compra começando com 45 e com 10 dígitos | `^45\d{8}$` | | Somente dígitos | `^\d+$` | | IBAN (verificação aproximada) | `^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$` | #### Range — entre mínimo e máximo O valor deve ser um número entre **Minimum** e **Maximum** (ambos incluídos). Preencha um deles ou ambos. Um valor que não seja um número falha. Valores formatados como `1.234,56` são compreendidos.
Uma verificação Range

Range somente com mínimo: as quantidades devem ser de pelo menos 0,01

#### Compare fields — por exemplo, vencimento ≥ data da fatura
uma verificação Compare fields

Compare fields: comparar um campo com outro campo, com hoje ou com um valor fixo

Compara o valor de um campo com outro campo, com **hoje** ou com um valor fixo, usando *igual a*, *diferente de*, *maior que*, *menor que*, *na data ou depois (≥)* ou *na data ou antes (≤)*. Números são comparados como números e datas como datas. * Due Date **na data ou depois (≥)** de Invoice Date * Invoice Date **na data ou antes (≤)** de hoje — sem faturas com data futura * Discount **menor que** 100 #### Allowed values — a partir de uma lista fixa
uma verificação Allowed values

Allowed values: um valor por linha, opcionalmente sem diferenciar maiúsculas de minúsculas

O valor deve ser um dos valores que você digitar, **um valor por linha**. Opcionalmente sem diferenciar maiúsculas de minúsculas. Bom para listas curtas e estáveis (`EUR`, `CHF`, `USD`). #### List of Values — a partir de uma LOV nomeada
uma verificação List of Values

List of Values: os valores vêm de uma lista nomeada nas configurações

Como *Allowed values*, mas os valores vêm de uma **List of Values** compartilhada, gerenciada em **Settings › List of Values**. Escolha a lista em vez de digitá-la novamente; quando a lista muda, a regra passa a usar os novos valores (após um breve atraso de cache). Contam apenas os valores das entradas da lista, não os seus rótulos. {% hint style="info" %} Exceto **Required**, toda verificação **é aprovada quando o valor está vazio**. Uma regra Pattern no Purchase Order não reclama de faturas sem pedido de compra. Se um valor vazio também for um problema, adicione uma regra Required ou limite a regra com *Applies when … is not empty*. {% endhint %} #### Mensagem de erro e código de erro * **Error message shown to the processing user** — o texto na tela de validação. Diga o que está errado **e** o que fazer: "Supplier tax ID is missing. German invoices over 250 EUR must show it." * **Error code** — um código técnico curto, por exemplo `REQUIRED_CONDITIONAL`, `FORMAT_MISMATCH`, `OUT_OF_RANGE`, `DATE_ORDER`, `LINES_HEADER_MISMATCH`, `VALUE_NOT_ALLOWED`. Ele aparece nas exportações e permite agrupar erros. ## Test rule Clique em **Test rule** para executar a versão atual da regra — salva ou não — em um documento. Informe um **Document ID** ou mude para **By Document JSON** e cole os dados extraídos. **Nada é salvo** e o documento não é alterado. O resultado é um destes três desfechos: | Resultado | Significado | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Rule failed — error raised** | A condição correspondeu e a verificação falhou. A mensagem é exibida exatamente como o usuário a veria. | | **Rule passed** | A condição correspondeu e a verificação foi aprovada. As regras de linha de tabela mostram o resultado por linha ("4 of 4 checked rows passed"). | | **Rule skipped — scope not matched** | A condição *Applies when* era falsa para este documento; portanto, nada foi verificado e nenhum erro foi gerado. |
Test rule: regra com falha

A fatura alemã não tem número de identificação fiscal do fornecedor: a regra falha com a mensagem configurada

Test rule: regra ignorada

A mesma regra com o limite elevado para 1000: a fatura (469,18) não está no escopo; portanto, a regra é ignorada

Test rule: resultados por linha

Uma regra de linha de tabela informa cada linha verificada

Teste cada nova regra em pelo menos um documento que deva falhar, um que deva ser aprovado e um que deva ser ignorado. ## Quando as regras são executadas * **Durante o processamento**, junto com as outras validações, após a extração e as regras de transformação. * **A cada salvamento** do documento na tela de validação. * **Após uma alteração de regra**, os documentos existentes **não** são reverificados de uma só vez. Cada documento é reverificado com as novas regras na próxima vez em que for salvo ou reprocessado. Documentos que já foram exportados não são afetados. * As regras são executadas por ordem de prioridade (depois pela chave). Um campo exibe **um** erro: se duas regras falharem no mesmo campo, a primeira prevalece; as regras seguintes não a sobrescrevem. * Os avisos são coletados separadamente e nunca ocultam um erro. * Se uma regra não puder ser avaliada — por exemplo, uma divisão por zero em uma fórmula — ela é ignorada. Uma regra com defeito nunca marca um documento como inválido por engano. ## Receitas Copie estas regras como ponto de partida. As chaves de campos e colunas são as do tipo de documento **Invoice** padrão; ajuste-as aos seus tipos de documento. **1. Número de identificação fiscal do fornecedor para faturas alemãs acima de 250 EUR** Header field · Error · associar a *Supplier Tax ID* · Applies when **All**: *Document Origin* is *Deutsch*, *Total Amount* greater than *250* · Verificação **Required** · Mensagem "Supplier tax ID is missing. German invoices over 250 EUR must show it." · Código `REQUIRED_CONDITIONAL`. **2. Os totais do cabeçalho fecham a soma** (substitui a verificação nativa) Header field · Error · associar a *Total Amount* · sempre · **Formula** `header.total_amount == header.total_net_amount + header.total_tax_amount`, tolerância `0.01` · Mensagem "Total {actual} does not equal net plus tax ({expected})." **3. As linhas somam o valor líquido** (substitui a verificação nativa) Whole table · Error · associar a *Total Net Amount* · sempre · **Formula** `sum(row.NET_AMOUNT) == header.total_net_amount`, tolerância `0.05` · Mensagem "Line net amounts add up to {actual}, but the invoice net amount is {expected}." · Código `LINES_HEADER_MISMATCH`. **4. A quantidade deve ser positiva nas linhas de artigo** Table line · Error · tabela `INVOICE_TABLE`, coluna `QUANTITY` · Applies when *row\.ITEM\_NUMBER* is not empty · **Range** mínimo `0.01` · Código `OUT_OF_RANGE`. **5. Valor da linha = quantidade × preço unitário** Table line · Warning · coluna `NET_AMOUNT` · sempre · **Formula** `row.NET_AMOUNT == row.QUANTITY * row.UNIT_PRICE`, tolerância `0.01`. **6. Formato do número de fatura de um fornecedor** Header field · Error · *Invoice Number* · Applies when *Supplier ID* is *20723* · **Pattern** `^INV-\d{6}$`. **7. Vencimento não anterior à data da fatura** Header field · Error · *Due Date* · sempre · **Compare fields** Due Date *na data ou depois (≥)* de Invoice Date · Código `DATE_ORDER`. **8. Sem faturas com data futura** Header field · Error · *Invoice Date* · sempre · **Compare fields** Invoice Date *na data ou antes (≤)* de hoje. **9. Somente moedas aprovadas (apenas como dica)** Header field · **Warning** · *Currency* · sempre · **List of Values** *approved\_currencies* · Código `VALUE_NOT_ALLOWED`. **10. Pedido de compra obrigatório acima de 5.000** Header field · Error · *Purchase Order* · Applies when *Total Amount* greater than *5000* · **Required**. ## Boas práticas * **Comece como aviso.** Salve uma nova regra com a severidade **Warning**, acompanhe-a por alguns dias (Test rule) e depois mude-a para **Error**. * **Uma regra, uma mensagem.** Várias regras pequenas com mensagens claras são mais fáceis de entender do que uma fórmula grande. * **Use Applies when em vez de cópias.** Uma regra com uma condição é melhor do que cinco cópias para cinco fornecedores. * **Seja tolerante com valores monetários.** Sempre defina uma tolerância nas fórmulas de valores. * **Dê às regras o nome da regra de negócio**, não da técnica ("Vencimento não anterior à data da fatura", e não "Regra de comparação 3"). ## Solução de problemas | Sintoma | O que verificar | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A regra nunca gera um erro | O recurso está ativado para o tipo de documento e a regra está **Active**? Execute **Test rule** no documento: "skipped" significa que *Applies when* era falso. | | Um campo vazio não é reportado | Somente **Required** reporta valores vazios. Adicione uma regra Required. | | As verificações de total nativas desapareceram | Esperado enquanto as regras personalizadas estão ativadas. Recrie-as como regras Formula (receitas 2 e 3). | | Uma regra alterada não tem efeito em um documento | Os documentos são reverificados no próximo salvamento. Salve ou reprocesse o documento. | | Um Pattern corresponde a valores que não deveria | Os padrões procuram dentro do valor. Ancore com `^` e `$`. | | Apenas um de dois erros é exibido em um campo | Um campo exibe somente a primeira regra com falha. Ajuste as prioridades ou associe uma das regras a outro campo. | | Colunas de tabela ausentes em *Applies when* | Elas só estão disponíveis no nível **Table line**. | | A regra padrão do sistema não pode ser alterada | Clique em **Customize** para criar sua própria cópia. | ## Relacionado * [Condições da Regra (Applies when)](/portuguese/administration-and-setup/settings/global-settings/document-types/rule-conditions-applies-when.md) — condições em detalhe * [Transformation Rules](/portuguese/administration-and-setup/settings/global-settings/document-types/transformation-rules.md) — corrija os valores antes de serem validados * [Layout Selection Rules](/portuguese/administration-and-setup/settings/global-settings/document-types/layout-manager/layout-selection-rules.md) — escolha o layout que um documento usa * [Setting Validation and Match Score](/portuguese/administration-and-setup/settings/global-settings/document-types/fields/setting-validation-and-match-score.md) — configurações de validação por campo --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.docbits.com/portuguese/administration-and-setup/settings/global-settings/document-types/custom-validation-rules.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.