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; as regras de um cliente são visíveis a todos os usuários autenticados (visão compartilhada do escritório). Uma regra pode ainda ser específica de uma estrutura ou de um layout Klingo, e pode gerar lucro automático para um sócio.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/regras-lancamentoEscopos necessários
regras_lancamento:read- listagem geral, listagem por cliente e detalhamentoregras_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'. Opcionais de vínculo: id_estrutura ou id_klingo_layout (exclusivos entre si; sem nenhum dos dois a regra é geral do cliente) e id_qsa_cliente (sócio que recebe o lucro automático quando a regra casa). Cliente, plano de contas, conta, estrutura, layout e sócio precisam ser coerentes entre si: sócio inexistente -> 404; sócio de outro cliente ou inativo, estrutura com layout, ou condição coluna_relatorio sem layout Klingo -> 422.
Request
{
"id_cliente": 1234,
"id_plano_contas": 88,
"nome": "Tarifa bancária - despesas",
"campo_destino": "conta_debito",
"tipo_exportacao": "conta",
"id_conta": 501,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": true,
"condicoes": [
{
"campo_comparacao": "historico",
"modo_comparacao": "contem",
"conteudo_comparacao": "TARIFA",
"proxima_comparacao": null,
"ordem": 1
}
]
}Response 201 Created
{
"status": "success",
"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,
"id_klingo_layout": null,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": true,
"conta_codigo": "4.1.01.001",
"conta_nome": "Despesas bancárias",
"nome_socio": null,
"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 as regras da base (visão compartilhada do escritório); sem nenhum filtro retorna todas. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma regra de lançamento encontrada.".
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | não | Filtra pelas regras de um cliente. |
id_estrutura | int | query | não | Só as regras específicas dessa estrutura (as gerais não entram). |
id_klingo_layout | int | query | não | Só as regras específicas desse layout Klingo. |
apenas_gerais | bool | query | não | true retorna só regras gerais (sem estrutura e sem layout). Ignorado se id_estrutura ou id_klingo_layout vier. Default false. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"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,
"id_klingo_layout": null,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": true,
"conta_codigo": "4.1.01.001",
"conta_nome": "Despesas bancárias",
"nome_socio": null,
"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, com filtros opcionais por plano de contas, situação, estrutura e layout Klingo. O filtro de vínculo é tri-state: sem id_estrutura/id_klingo_layout e com apenas_gerais=false retorna todas; id_estrutura=<X> retorna apenas as da estrutura X; id_klingo_layout=<Y> apenas as do layout Y; apenas_gerais=true (sem os ids) retorna apenas regras gerais. Se um id 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. |
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. |
id_klingo_layout | int | query | não | Retorna apenas regras específicas do layout Klingo informado. |
apenas_gerais | bool | query | não | Quando true (e sem id_estrutura/id_klingo_layout), retorna apenas regras gerais (sem estrutura e sem layout). Default false. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"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,
"id_klingo_layout": null,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": true,
"conta_codigo": "4.1.01.001",
"conta_nome": "Despesas bancárias",
"nome_socio": null,
"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. 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 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,
"id_klingo_layout": null,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": true,
"conta_codigo": "4.1.01.001",
"conta_nome": "Despesas bancárias",
"nome_socio": null,
"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 estrutura, layout ou sócio
Enviar id_estrutura, id_klingo_layout ou id_qsa_cliente com null explicitamente desvincula o valor (a regra vira geral; sem sócio, deixa de gerar lucro). Para manter o valor atual, omita o campo. Estrutura e layout Klingo continuam exclusivos entre si; sócio inexistente retorna 404 e sócio de outro cliente ou inativo retorna 422.
Request (RegraLancamentoUpdate - todos os campos opcionais)
{
"nome": "Tarifa bancária - despesas administrativas",
"ativo": false
}Response 200 OK
{
"status": "success",
"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,
"id_klingo_layout": null,
"id_qsa_cliente": null,
"ordem": 0,
"ativo": false,
"conta_codigo": "4.1.01.001",
"conta_nome": "Despesas bancárias",
"nome_socio": null,
"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 ao qual a regra pertence. |
id_plano_contas | int | sim | Plano de contas 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. Exclusivo com id_klingo_layout. |
id_klingo_layout | int | não | Layout Klingo (klingo_layout.id) ao qual a regra é específica. Exclusivo com id_estrutura (422 se vierem juntos). |
id_qsa_cliente | int | não | Sócio (customer_qsa.id) que recebe o lucro automático quando a regra casa. Deve ser do mesmo cliente e estar ativo. null = não gera lucro. |
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). |
id_klingo_layout | int | Reatribui o layout Klingo. null explícito desvincula; omitido mantém. |
id_qsa_cliente | int | Reatribui o sócio do lucro automático. null explícito desvincula; omitido mantém. |
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 | CampoComparacaoRegra | sim | Campo comparado: historico, valor, data, natureza, numero_documento ou coluna_relatorio (valor cru de uma coluna do relatório Klingo; só em regra vinculada a um layout Klingo). |
coluna_relatorio | str (≤50) | condicional | Nome da coluna do relatório (ex.: col3), marcada como campo de regra no layout. Obrigatório com campo_comparacao='coluna_relatorio' e proibido nos demais casos (422). |
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). |
id_klingo_layout | int | null | Layout Klingo vinculado (null = não é específica de layout). |
id_qsa_cliente | int | null | Sócio que recebe o lucro automático (null = não gera lucro). |
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. |
nome_socio | str | null | Enriquecimento somente leitura - nome do sócio de id_qsa_cliente. |
condicoes | List[CondicaoRegraRead] | Condições encadeadas da regra (cada uma com campo_comparacao e, quando aplicável, coluna_relatorio). |
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": [...] }). ODELETEretorna204 No Content, sem corpo. - As leituras são uma visão compartilhada do escritório: qualquer usuário autenticado vê as regras de qualquer cliente.
- 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) e422 Unprocessable Entitypara os demais. - A rota estática
GET /regras-lancamento/cliente/{id_cliente}é declarada antes da rota dinâmicaGET /regras-lancamento/{regra_id}, entãoclienteé resolvido como segmento estático (e não interpretado como umregra_id). - Os schemas
LancamentoParaAvaliareLancamentoSugeridosão de uso interno do motoraplicar_regrase não são expostos por nenhuma rota deste domínio.