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-ignorar

Escopos necessários

  • regra_ignorar:read - listagem por escopo e detalhamento
  • regra_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âmetroTipoLocalObrigatórioDescrição
id_bancointpathsimID 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âmetroTipoLocalObrigatórioDescrição
id_clienteintpathsimID 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âmetroTipoLocalObrigatórioDescrição
id_estruturaintpathsimID 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âmetroTipoLocalObrigatórioDescrição
regra_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
regra_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
regra_idintpathsimID 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.

CampoTipoObrigatórioObservações
nomestrsim1 a 200 caracteres.
condicoesList[CondicaoRegraIgnorarCreate]sim1 a 100 itens.
id_bancointcondicionalEscopo banco. Ao menos um dos quatro escopos deve ser informado.
id_clienteintcondicionalEscopo cliente.
id_estruturaintcondicionalEscopo estrutura. Exclusivo com id_klingo_layout.
id_klingo_layoutintcondicionalEscopo layout Klingo (null = vale para qualquer importação). Exclusivo com id_estrutura.
ordemintnãoOrdem de aplicação. Default 0 (>= 0).
ativoboolnãoDefault 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.

CampoTipoObservações
nomestr1 a 200 caracteres.
id_bancointVínculo com o banco. Omitido mantém; null desvincula.
id_estruturaintVínculo com a estrutura. Omitido mantém; null desvincula.
id_klingo_layoutintVínculo com o layout Klingo. Omitido mantém; null desvincula.
ordemint>= 0.
ativoboolAtiva/desativa a regra.
condicoesList[CondicaoRegraIgnorarCreate]Se enviado, substitui toda a cadeia (1 a 100 itens - não esvazia).

RegraIgnorarRead

CampoTipoNotas
idintIdentificador da regra.
id_usuario_createdintUsuário que criou a regra.
id_bancoint | nullEscopo banco (quando aplicável).
id_clienteint | nullEscopo cliente (quando aplicável).
id_estruturaint | nullEscopo estrutura (quando aplicável).
id_klingo_layoutint | nullEscopo layout Klingo (quando aplicável).
data_hora_criacaodatetimeTimestamp normalizado para America/Sao_Paulo.
nomestrNome da regra.
ordemintOrdem de aplicação.
ativoboolSituação da regra.
condicoesList[CondicaoRegraIgnorarRead]Cadeia de condições da regra.

CondicaoRegraIgnorarCreate

CampoTipoObrigatórioObservações
campo_comparacaoCampoComparacaoRegrasimCampo a comparar: historico, valor, data, natureza, numero_documento ou coluna_relatorio (coluna do relatório Klingo; exige regra com id_klingo_layout).
coluna_relatoriostr (≤50)condicionalNome da coluna do relatório (ex.: col3). Obrigatório com campo_comparacao='coluna_relatorio' e proibido nos demais casos (422).
modo_comparacaoModoComparacaosimModo de comparação (Literal de regras_lancamento).
conteudo_comparacaostrnãoAté 500 caracteres.
proxima_comparacaoProximaComparacaonãoConector para a próxima condição (E/OU).
ordemintnãoDefault 1 (>= 0).

CondicaoRegraIgnorarRead

CampoTipoNotas
idintIdentificador da condição.
id_regra_ignorarintRegra à qual a condição pertence.
campo_comparacaostrCampo comparado.
coluna_relatoriostr | nullColuna do relatório Klingo comparada (quando campo_comparacao é coluna_relatorio).
modo_comparacaostrModo de comparação.
conteudo_comparacaostr | nullConteúdo comparado.
proxima_comparacaostr | nullConector para a próxima condição.
ordemintOrdem 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 como 422 com { "detail": [...] }).
  • As rotas estáticas GET /banco/{id_banco}, GET /cliente/{id_cliente} e GET /estrutura/{id_estrutura} são declaradas antes da rota dinâmica GET /{regra_id}, garantindo que banco, cliente e estrutura sejam resolvidas como rotas estáticas (e não interpretadas como um regra_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_comparacao e proxima_comparacao sã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 em data.