Regras de Lançamento

Endpoints da WebApiAlcance para gerenciar regras de lançamento - regras de automação que, a partir de condições encadeadas sobre um lançamento de origem (histórico, valor, data, natureza, número do documento), sugerem o preenchimento de um campo destino (conta_debito, conta_credito ou historico). São usadas na avaliação automática durante importações de extratos. Cada regra pertence a um cliente e a um plano de contas, e é sempre filtrada pelo usuário autenticado (ownership).

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/regras-lancamento

Escopos necessários

regras_lancamento:read - listagem geral, listagem por cliente e detalhamento
regras_lancamento:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /regras-lancamento vira o recurso regras_lancamento (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PATCH/DELETE).

Endpoints

`POST /regras-lancamento/`

Cria uma nova regra de lançamento com suas condições encadeadas. O id_usuario_created é preenchido a partir do usuário autenticado - não é aceito no corpo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RegraLancamentoCreate). São obrigatórios id_cliente, id_plano_contas, nome, campo_destino e condicoes (1 a 100). O campo id_conta é obrigatório quando tipo_exportacao='conta'; valor_destino é obrigatório quando tipo_exportacao é 'historico' ou 'flexivel'. As validações de ownership (cliente, plano de contas e conta pertencem ao mesmo usuário) ocorrem no service.

Request

{
  "id_cliente": 1234,
  "id_plano_contas": 88,
  "nome": "Tarifa bancária - despesas",
  "campo_destino": "conta_debito",
  "tipo_exportacao": "conta",
  "id_conta": 501,
  "ordem": 0,
  "ativo": true,
  "condicoes": [
    {
      "campo_comparacao": "historico",
      "modo_comparacao": "contem",
      "conteudo_comparacao": "TARIFA",
      "proxima_comparacao": null,
      "ordem": 1
    }
  ]
}

Response 201 Created

{
  "success": true,
  "message": "Regra de lançamento criada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "nome": "Tarifa bancária - despesas",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 501,
    "valor_destino": null,
    "id_estrutura": null,
    "ordem": 0,
    "ativo": true,
    "conta_codigo": "4.1.01.001",
    "conta_nome": "Despesas bancárias",
    "condicoes": [
      {
        "id": 90,
        "id_regra": 42,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TARIFA",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Escopo: regras_lancamento:write

`GET /regras-lancamento/`

Lista todas as regras do usuário autenticado. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma regra de lançamento encontrada.".

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 de lançamento recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "id_usuario_created": 7,
      "id_cliente": 1234,
      "id_plano_contas": 88,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00",
      "nome": "Tarifa bancária - despesas",
      "campo_destino": "conta_debito",
      "tipo_exportacao": "conta",
      "id_conta": 501,
      "valor_destino": null,
      "id_estrutura": null,
      "ordem": 0,
      "ativo": true,
      "conta_codigo": "4.1.01.001",
      "conta_nome": "Despesas bancárias",
      "condicoes": [
        {
          "id": 90,
          "id_regra": 42,
          "campo_comparacao": "historico",
          "modo_comparacao": "contem",
          "conteudo_comparacao": "TARIFA",
          "proxima_comparacao": null,
          "ordem": 1
        }
      ]
    }
  ]
}

Escopo: regras_lancamento:read

`GET /regras-lancamento/cliente/{id_cliente}`

Lista as regras de um cliente específico (apenas as do usuário autenticado), com filtros opcionais por plano de contas, situação e estrutura. O filtro de estrutura é tri-state: sem id_estrutura e apenas_gerais=false retorna todas; id_estrutura=<X> retorna apenas as vinculadas à estrutura X; apenas_gerais=true (sem id_estrutura) retorna apenas regras gerais. Se id_estrutura e apenas_gerais forem passados juntos, apenas_gerais é ignorado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID do cliente (customer.id).
`id_plano_contas`	`int`	query	não	Filtra pelas regras de um plano de contas específico.
`ativo`	`bool`	query	não	Quando informado, filtra por `ativo=true` ou `ativo=false`.
`id_estrutura`	`int`	query	não	Retorna apenas regras vinculadas à estrutura informada.
`apenas_gerais`	`bool`	query	não	Quando `true` (e `id_estrutura` ausente), retorna apenas regras gerais (`id_estrutura IS NULL`). Default `false`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Regras de lançamento recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "id_usuario_created": 7,
      "id_cliente": 1234,
      "id_plano_contas": 88,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00",
      "nome": "Tarifa bancária - despesas",
      "campo_destino": "conta_debito",
      "tipo_exportacao": "conta",
      "id_conta": 501,
      "valor_destino": null,
      "id_estrutura": null,
      "ordem": 0,
      "ativo": true,
      "conta_codigo": "4.1.01.001",
      "conta_nome": "Despesas bancárias",
      "condicoes": [
        {
          "id": 90,
          "id_regra": 42,
          "campo_comparacao": "historico",
          "modo_comparacao": "contem",
          "conteudo_comparacao": "TARIFA",
          "proxima_comparacao": null,
          "ordem": 1
        }
      ]
    }
  ]
}

Lista vazia retorna 200 OK com data: [] e a mensagem "Nenhuma regra de lançamento encontrada.". Escopo: regras_lancamento:read

`GET /regras-lancamento/{regra_id}`

Busca uma regra pelo ID inteiro, validando ownership. Quando não encontrada (ou de outro usuário), 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 de lançamento encontrada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "nome": "Tarifa bancária - despesas",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 501,
    "valor_destino": null,
    "id_estrutura": null,
    "ordem": 0,
    "ativo": true,
    "conta_codigo": "4.1.01.001",
    "conta_nome": "Despesas bancárias",
    "condicoes": [
      {
        "id": 90,
        "id_regra": 42,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TARIFA",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Escopo: regras_lancamento:read

`PATCH /regras-lancamento/{regra_id}`

Atualiza campos da regra. O corpo é um RegraLancamentoUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos id_cliente, id_plano_contas, id_usuario_created, id e data_hora_criacao são imutáveis e não podem ser enviados. Se condicoes for fornecido, substitui todas as condições da regra (replace, mínimo 1); se omitido, mantém as condições atuais.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`regra_id`	`int`	path	sim	ID da regra

Desvincular de estrutura

Como o service usa exclude_unset=True, enviar id_estrutura: null explicitamente desvincula a regra da estrutura (vira regra geral). Para manter o valor atual, omita o campo.

Request (RegraLancamentoUpdate - todos os campos opcionais)

{
  "nome": "Tarifa bancária - despesas administrativas",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Regra de lançamento atualizada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_cliente": 1234,
    "id_plano_contas": 88,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "nome": "Tarifa bancária - despesas administrativas",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 501,
    "valor_destino": null,
    "id_estrutura": null,
    "ordem": 0,
    "ativo": false,
    "conta_codigo": "4.1.01.001",
    "conta_nome": "Despesas bancárias",
    "condicoes": [
      {
        "id": 90,
        "id_regra": 42,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TARIFA",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Escopo: regras_lancamento:write

`DELETE /regras-lancamento/{regra_id}`

Remove a regra e, por cascade, todas as suas condições. Quando não encontrada, 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.

Escopo: regras_lancamento:write

Schemas

`RegraLancamentoCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	Cliente (customer.id) ao qual a regra pertence.
`id_plano_contas`	`int`	sim	Plano de contas (plano_contas.id) sob o qual a regra atua.
`nome`	`str` (1-200)	sim	Nome descritivo da regra.
`campo_destino`	`CampoDestino`	sim	`conta_debito`, `conta_credito` ou `historico`.
`tipo_exportacao`	`TipoExportacao`	não	`conta` (default), `historico` ou `flexivel`.
`id_conta`	`int`	condicional	Conta sugerida (contas.id). Obrigatório quando `tipo_exportacao='conta'`.
`valor_destino`	`str` (≤500)	condicional	Texto/template. Obrigatório quando `tipo_exportacao` é `historico` ou `flexivel`.
`id_estrutura`	`int`	não	Estrutura vinculada (estrutura.id). `None` = regra geral do cliente.
`ordem`	`int` (≥0)	não	Ordem de avaliação entre regras do mesmo cliente. Default `0`.
`ativo`	`bool`	não	`False` faz a regra ser ignorada na avaliação automática. Default `True`.
`condicoes`	`List[CondicaoRegraCreate]`	sim	Lista de 1 a 100 condições encadeadas para a regra disparar.

`RegraLancamentoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`nome`	`str` (1-200)	Novo nome da regra.
`campo_destino`	`CampoDestino`	Novo campo destino.
`tipo_exportacao`	`TipoExportacao`	Nova estratégia de preenchimento.
`id_conta`	`int`	Nova conta sugerida.
`valor_destino`	`str` (≤500)	Novo texto/template.
`id_estrutura`	`int`	Reatribui a estrutura. `null` explícito desvincula (vira regra geral).
`ordem`	`int` (≥0)	Nova ordem de avaliação.
`ativo`	`bool`	Ativa/inativa a regra.
`condicoes`	`List[CondicaoRegraCreate]`	Quando fornecida, substitui todas as condições (1-100). Quando omitida, mantém as atuais.

`CondicaoRegraCreate`

Cada condição compara um campo do lançamento de origem com um valor de referência, encadeando-se via conector lógico.

Campo	Tipo	Obrigatório	Observações
`campo_comparacao`	`CampoComparacao`	sim	Campo comparado: `historico`, `valor`, `data`, `natureza`, `numero_documento`.
`modo_comparacao`	`ModoComparacao`	sim	Operador: `igual`, `diferente`, `contem`, `nao_contem`, `maior`, `maior_igual`, `menor`, `menor_igual`, `valido`, `nao_valido`, `buscar_conteudo`.
`conteudo_comparacao`	`str` (≤500)	não	Valor de referência. Pode ser `None` em operadores unários como `valido`/`nao_valido`.
`proxima_comparacao`	`ProximaComparacao`	não	Conector para a próxima condição: `E` (AND) ou `OU` (OR). `None` na última da cadeia.
`ordem`	`int` (≥0)	não	Ordem de avaliação na cadeia (ascendente). Default `1`.

`RegraLancamentoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador da regra.
`id_usuario_created`	`int`	Usuário que criou a regra (ownership).
`id_cliente`	`int`	Cliente da regra.
`id_plano_contas`	`int`	Plano de contas da regra.
`data_hora_criacao`	`datetime`	Timestamp de criação (localizado em `America/Sao_Paulo`).
`nome`	`str`	Nome da regra.
`campo_destino`	`str`	Campo destino preenchido pela regra.
`tipo_exportacao`	`str`	Estratégia de preenchimento.
`id_conta`	`int` \| `null`	Conta sugerida.
`valor_destino`	`str` \| `null`	Texto/template quando `tipo_exportacao` é `historico`/`flexivel`.
`id_estrutura`	`int` \| `null`	Estrutura vinculada (`null` = geral).
`ordem`	`int`	Ordem de avaliação.
`ativo`	`bool`	Situação da regra.
`conta_codigo`	`str` \| `null`	Enriquecimento somente leitura - código da conta sugerida.
`conta_nome`	`str` \| `null`	Enriquecimento somente leitura - nome da conta sugerida.
`condicoes`	`List[CondicaoRegraRead]`	Condições encadeadas da regra.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). O DELETE retorna 204 No Content, sem corpo.
Todas as operações são filtradas pelo usuário autenticado: uma regra de outro usuário responde 404 Not Found.
Erros de negócio do service são mapeados por HTTP: 404 Not Found (não encontrado), 403 Forbidden (acesso negado), 409 Conflict (já existe/duplicado) e 422 Unprocessable Entity para os demais.
A rota estática GET /regras-lancamento/cliente/{id_cliente} é declarada antes da rota dinâmica GET /regras-lancamento/{regra_id}, então cliente é resolvido como segmento estático (e não interpretado como um regra_id).
Os schemas LancamentoParaAvaliar e LancamentoSugerido são de uso interno do motor aplicar_regras e não são expostos por nenhuma rota deste domínio.