Regras de Ignorar
Endpoints da WebApiAlcance para gerenciar regras de ignorar (regra_ignorar) - regras multi-escopo que descartam lançamentos durante o import/conciliação antes que sejam processados. Cada regra é vinculada a ao menos um escopo (banco, cliente, estrutura ou layout Klingo) e carrega uma cadeia de condições de comparação. Cobrem criação, listagem por escopo (banco, cliente, estrutura), detalhamento por ID, atualização parcial e exclusão.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/regra-ignorarEscopos necessários
regra_ignorar:read- listagem por escopo e detalhamentoregra_ignorar:write- criação, atualização e exclusão
O escopo é derivado da rota: o prefixo /regra-ignorar vira o recurso regra_ignorar (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PATCH/DELETE).
Endpoints
POST /regra-ignorar/
Cria uma nova regra de ignorar vinculada ao usuário autenticado. A regra exige ao menos um escopo (id_banco, id_cliente, id_estrutura ou id_klingo_layout; combináveis, exceto estrutura com layout) e ao menos uma condição. O id_usuario_created é atribuído a partir do usuário logado - não é aceito no body.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RegraIgnorarCreate): nome (obrigatório), condicoes (obrigatório, 1 a 100 itens), ao menos um de id_banco / id_cliente / id_estrutura / id_klingo_layout, além de ordem e ativo (opcionais). id_estrutura e id_klingo_layout juntos retornam 422; uma condição coluna_relatorio exige id_klingo_layout. Estrutura ou layout de outro cliente retornam 404.
Request
{
"nome": "Ignorar tarifas de manutenção",
"id_banco": 3,
"ordem": 0,
"ativo": true,
"condicoes": [
{
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}Response 201 Created
{
"status": "success",
"message": "Regra de ignorar criada com sucesso",
"data": {
"id": 42,
"id_usuario_created": 7,
"id_banco": 3,
"id_cliente": null,
"id_estrutura": null,
"id_klingo_layout": null,
"data_hora_criacao": "2026-07-03T10:15:00-03:00",
"nome": "Ignorar tarifas de manutenção",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 101,
"id_regra_ignorar": 42,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
}Erros de validação retornam 422 Unprocessable Entity (ex.: nenhum escopo informado, estrutura e layout juntos); duplicidades retornam 409 Conflict; escopo inexistente ou de outro cliente retorna 404 Not Found. Escopo: regra_ignorar:write
GET /regra-ignorar/
Lista todas as regras de ignorar numa visão compartilhada do escritório - não filtra por usuário nem por escopo (banco/cliente/estrutura). Serve para uma visão geral consolidada. Lista vazia é um estado válido: retorna 200 OK com data: [] e a mensagem "Nenhuma regra de ignorar encontrada." (diferente das listagens por escopo, que devolvem envelope de erro quando vazias).
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regras recuperadas com sucesso",
"data": [
{
"id": 42,
"id_usuario_created": 7,
"id_banco": 3,
"id_cliente": null,
"id_estrutura": null,
"data_hora_criacao": "2026-07-03T10:15:00-03:00",
"nome": "Ignorar tarifas de manutenção",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 101,
"id_regra_ignorar": 42,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
]
}Escopo: regra_ignorar:read
GET /regra-ignorar/banco/{id_banco}
Lista todas as regras de ignorar vinculadas a um banco. Quando não há regras, retorna envelope de erro com status: "error" e message: "Nenhuma regra de ignorar encontrada.".
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_banco | int | path | sim | ID do banco |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regras recuperadas com sucesso",
"data": [
{
"id": 42,
"id_usuario_created": 7,
"id_banco": 3,
"id_cliente": null,
"id_estrutura": null,
"data_hora_criacao": "2026-07-03T10:15:00-03:00",
"nome": "Ignorar tarifas de manutenção",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 101,
"id_regra_ignorar": 42,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
]
}Escopo: regra_ignorar:read
GET /regra-ignorar/cliente/{id_cliente}
Lista todas as regras de ignorar vinculadas a um cliente. Quando não há regras, retorna envelope de erro com message: "Nenhuma regra de ignorar encontrada." e details: [].
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | path | sim | ID do cliente |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regras recuperadas com sucesso",
"data": [
{
"id": 55,
"id_usuario_created": 7,
"id_banco": null,
"id_cliente": 12,
"id_estrutura": null,
"data_hora_criacao": "2026-07-03T10:20:00-03:00",
"nome": "Ignorar transferências internas",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 130,
"id_regra_ignorar": 55,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TRANSFERENCIA INTERNA",
"proxima_comparacao": null,
"ordem": 1
}
]
}
]
}Escopo: regra_ignorar:read
GET /regra-ignorar/estrutura/{id_estrutura}
Lista todas as regras de ignorar vinculadas a uma estrutura. Quando não há regras, retorna envelope de erro com message: "Nenhuma regra de ignorar encontrada." e details: [].
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_estrutura | int | path | sim | ID da estrutura |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regras recuperadas com sucesso",
"data": [
{
"id": 60,
"id_usuario_created": 7,
"id_banco": null,
"id_cliente": null,
"id_estrutura": 4,
"data_hora_criacao": "2026-07-03T10:25:00-03:00",
"nome": "Ignorar rendimentos de aplicação",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 140,
"id_regra_ignorar": 60,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "RENDIMENTO APLICACAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
]
}Escopo: regra_ignorar:read
GET /regra-ignorar/{regra_id}
Detalha uma regra de ignorar pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
regra_id | int | path | sim | ID interno da regra |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regra encontrada com sucesso",
"data": {
"id": 42,
"id_usuario_created": 7,
"id_banco": 3,
"id_cliente": null,
"id_estrutura": null,
"id_klingo_layout": null,
"data_hora_criacao": "2026-07-03T10:15:00-03:00",
"nome": "Ignorar tarifas de manutenção",
"ordem": 0,
"ativo": true,
"condicoes": [
{
"id": 101,
"id_regra_ignorar": 42,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
}Escopo: regra_ignorar:read
PATCH /regra-ignorar/{regra_id}
Atualiza uma regra existente. O body é um RegraIgnorarUpdate com campos parciais - somente o que vier preenchido é alterado. id_cliente, id_usuario_created, id e data_hora_criacao são imutáveis; id_banco, id_estrutura e id_klingo_layout são editáveis (omitido mantém, null desvincula, id grava). O resultado do merge é revalidado: continua exigindo ao menos um escopo, estrutura e layout Klingo juntos retornam 422, e vínculo de outro cliente retorna 404. Se condicoes for enviado, substitui toda a cadeia existente (mínimo 1 item - nunca esvazia).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
regra_id | int | path | sim | ID da regra |
Request (RegraIgnorarUpdate - todos os campos opcionais)
{
"nome": "Ignorar tarifas bancárias",
"ativo": false
}Response 200 OK
{
"status": "success",
"message": "Regra atualizada com sucesso",
"data": {
"id": 42,
"id_usuario_created": 7,
"id_banco": 3,
"id_cliente": null,
"id_estrutura": null,
"id_klingo_layout": null,
"data_hora_criacao": "2026-07-03T10:15:00-03:00",
"nome": "Ignorar tarifas bancárias",
"ordem": 0,
"ativo": false,
"condicoes": [
{
"id": 101,
"id_regra_ignorar": 42,
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA MANUTENCAO",
"proxima_comparacao": null,
"ordem": 1
}
]
}
}Escopo: regra_ignorar:write
DELETE /regra-ignorar/{regra_id}
Remove uma regra de ignorar pelo ID. Quando a regra não existe, retorna 404 Not Found.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
regra_id | int | path | sim | ID da regra |
Request
Sem corpo de requisição.
Response 204 No Content
Sem corpo de resposta em caso de sucesso.
Escopo: regra_ignorar:write
Schemas
RegraIgnorarCreate
Exige ao menos um escopo (id_banco, id_cliente, id_estrutura ou id_klingo_layout) e ao menos uma condição.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome | str | sim | 1 a 200 caracteres. |
condicoes | List[CondicaoRegraIgnorarCreate] | sim | 1 a 100 itens. |
id_banco | int | condicional | Escopo banco. Ao menos um dos quatro escopos deve ser informado. |
id_cliente | int | condicional | Escopo cliente. |
id_estrutura | int | condicional | Escopo estrutura. Exclusivo com id_klingo_layout. |
id_klingo_layout | int | condicional | Escopo layout Klingo (null = vale para qualquer importação). Exclusivo com id_estrutura. |
ordem | int | não | Ordem de aplicação. Default 0 (>= 0). |
ativo | bool | não | Default true. |
RegraIgnorarUpdate
Todos os campos são opcionais; apenas os enviados são atualizados. id_cliente e os metadados de criação são imutáveis.
| Campo | Tipo | Observações |
|---|---|---|
nome | str | 1 a 200 caracteres. |
id_banco | int | Vínculo com o banco. Omitido mantém; null desvincula. |
id_estrutura | int | Vínculo com a estrutura. Omitido mantém; null desvincula. |
id_klingo_layout | int | Vínculo com o layout Klingo. Omitido mantém; null desvincula. |
ordem | int | >= 0. |
ativo | bool | Ativa/desativa a regra. |
condicoes | List[CondicaoRegraIgnorarCreate] | Se enviado, substitui toda a cadeia (1 a 100 itens - não esvazia). |
RegraIgnorarRead
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador da regra. |
id_usuario_created | int | Usuário que criou a regra. |
id_banco | int | null | Escopo banco (quando aplicável). |
id_cliente | int | null | Escopo cliente (quando aplicável). |
id_estrutura | int | null | Escopo estrutura (quando aplicável). |
id_klingo_layout | int | null | Escopo layout Klingo (quando aplicável). |
data_hora_criacao | datetime | Timestamp normalizado para America/Sao_Paulo. |
nome | str | Nome da regra. |
ordem | int | Ordem de aplicação. |
ativo | bool | Situação da regra. |
condicoes | List[CondicaoRegraIgnorarRead] | Cadeia de condições da regra. |
CondicaoRegraIgnorarCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
campo_comparacao | CampoComparacaoRegra | sim | Campo a comparar: historico, valor, data, natureza, numero_documento ou coluna_relatorio (coluna do relatório Klingo; exige regra com id_klingo_layout). |
coluna_relatorio | str (≤50) | condicional | Nome da coluna do relatório (ex.: col3). Obrigatório com campo_comparacao='coluna_relatorio' e proibido nos demais casos (422). |
modo_comparacao | ModoComparacao | sim | Modo de comparação (Literal de regras_lancamento). |
conteudo_comparacao | str | não | Até 500 caracteres. |
proxima_comparacao | ProximaComparacao | não | Conector para a próxima condição (E/OU). |
ordem | int | não | Default 1 (>= 0). |
CondicaoRegraIgnorarRead
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador da condição. |
id_regra_ignorar | int | Regra à qual a condição pertence. |
campo_comparacao | str | Campo comparado. |
coluna_relatorio | str | null | Coluna do relatório Klingo comparada (quando campo_comparacao é coluna_relatorio). |
modo_comparacao | str | Modo de comparação. |
conteudo_comparacao | str | null | Conteúdo comparado. |
proxima_comparacao | str | null | Conector para a próxima condição. |
ordem | int | Ordem da condição na cadeia. |
Notas
- Toda resposta segue o envelope
{ status, message, data }(erros de negócio vêm como{ "message": ... }e a validação de entrada como422com{ "detail": [...] }). - As rotas estáticas
GET /banco/{id_banco},GET /cliente/{id_cliente}eGET /estrutura/{id_estrutura}são declaradas antes da rota dinâmicaGET /{regra_id}, garantindo quebanco,clienteeestruturasejam resolvidas como rotas estáticas (e não interpretadas como umregra_id). - Uma regra de ignorar descarta o lançamento no import da conciliação quando suas condições casam - não possui destino contábil (diferente das regras de lançamento).
- Os valores de
campo_comparacao,modo_comparacaoeproxima_comparacaosão os mesmos de Regras de Lançamento. - As listagens por escopo retornam envelope de erro (
status: "error") quando não há regras - uma lista vazia não é devolvida emdata.