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 e/ou estrutura) 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. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

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 ou id_estrutura - combináveis) 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, além de ordem e ativo (opcionais).

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

{
  "success": true,
  "message": "Regra de ignorar criada 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
      }
    ]
  }
}

Erros de validação retornam 422 Unprocessable Entity (ex.: nenhum escopo informado); duplicidades retornam 409 Conflict; escopo inexistente 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

{
  "success": true,
  "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 success: false, message: "Nenhuma regra de ignorar encontrada." e details: [].

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

{
  "success": true,
  "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

{
  "success": true,
  "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

{
  "success": true,
  "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

{
  "success": true,
  "message": "Regra encontrada 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

`PATCH /regra-ignorar/{regra_id}`

Atualiza uma regra existente. O body é um RegraIgnorarUpdate com campos parciais - somente o que vier preenchido é alterado. Os escopos (id_banco / id_cliente / id_estrutura), id_usuario_created, id e data_hora_criacao são imutáveis. 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

{
  "success": true,
  "message": "Regra atualizada 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 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 ou id_estrutura) 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 três escopos deve ser informado.
`id_cliente`	`int`	condicional	Escopo cliente.
`id_estrutura`	`int`	condicional	Escopo 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. Escopos e metadados de criação são imutáveis.

Campo	Tipo	Observações
`nome`	`str`	1 a 200 caracteres.
`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).
`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`	`CampoComparacao`	sim	Campo do lançamento a comparar (Literal de `regras_lancamento`).
`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.
`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 { success, message, data } (ou { success: false, message, details } em erro).
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 Literais CampoComparacao, ModoComparacao e ProximaComparacao são reaproveitados do domínio regras_lancamento.
As listagens por escopo retornam envelope de erro (success: false) com details: [] quando não há regras - uma lista vazia não é devolvida em data.