Padrão de Regras por Banco

Endpoints da WebApiAlcance para gerenciar padrões de regras por banco - padrões de conciliação vinculados a um banco de um cliente. Cada padrão sugere um preenchimento (conta, histórico ou template flexível) para os lançamentos importados e pode carregar uma cadeia de condições encadeadas: sem condições ele é um padrão blanket (casa todo lançamento do banco); com condições, o casamento é refinado. Cobrem criação, listagem geral, listagem por cliente com filtros, 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/padrao-regra-banco

Escopos necessários

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

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

Endpoints

`POST /padrao-regra-banco/`

Cria um padrão de regra vinculado a um banco de um cliente. O campo condicoes é opcional - vazio significa um padrão blanket que casa todo lançamento do banco. As validações de coerência entre id_cliente, id_banco, id_plano_contas e id_conta ocorrem na camada de serviço.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (PadraoRegraBancoCreate). Campos obrigatórios: id_cliente, id_banco, id_plano_contas, nome e campo_destino. Regras de consistência: id_conta é obrigatório quando tipo_exportacao='conta'; valor_destino é obrigatório quando tipo_exportacao é historico ou flexivel.

Request

{
  "id_cliente": 42,
  "id_banco": 7,
  "id_plano_contas": 3,
  "nome": "Tarifas bancárias",
  "campo_destino": "conta_debito",
  "tipo_exportacao": "conta",
  "id_conta": 155,
  "ordem": 0,
  "ativo": true,
  "condicoes": [
    {
      "campo_comparacao": "historico",
      "modo_comparacao": "contem",
      "conteudo_comparacao": "TAR ",
      "proxima_comparacao": null,
      "ordem": 1
    }
  ]
}

Response 201 Created

{
  "success": true,
  "message": "Padrão de regra por banco criado com sucesso",
  "data": {
    "id": 88,
    "id_usuario_created": 7,
    "id_cliente": 42,
    "id_banco": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "nome": "Tarifas bancárias",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 155,
    "valor_destino": null,
    "ordem": 0,
    "ativo": true,
    "conta_codigo": "1.1.02.001",
    "conta_nome": "Tarifas bancárias",
    "condicoes": [
      {
        "id": 201,
        "id_padrao": 88,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TAR ",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Conflitos (padrão duplicado) retornam 409 Conflict; validações de negócio retornam 422 Unprocessable Entity. Escopo: padrao_regra_banco:write

`GET /padrao-regra-banco/`

Lista todos os padrões do usuário autenticado. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum padrão de regra por banco encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta é um array de PadraoRegraBancoRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Padrões de regra por banco recuperados com sucesso",
  "data": [
    {
      "id": 88,
      "id_usuario_created": 7,
      "id_cliente": 42,
      "id_banco": 7,
      "id_plano_contas": 3,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "nome": "Tarifas bancárias",
      "campo_destino": "conta_debito",
      "tipo_exportacao": "conta",
      "id_conta": 155,
      "valor_destino": null,
      "ordem": 0,
      "ativo": true,
      "conta_codigo": "1.1.02.001",
      "conta_nome": "Tarifas bancárias",
      "condicoes": [
        {
          "id": 201,
          "id_padrao": 88,
          "campo_comparacao": "historico",
          "modo_comparacao": "contem",
          "conteudo_comparacao": "TAR ",
          "proxima_comparacao": null,
          "ordem": 1
        }
      ]
    }
  ]
}

Escopo: padrao_regra_banco:read

`GET /padrao-regra-banco/cliente/{id_cliente}`

Lista os padrões de um cliente específico (apenas os do usuário autenticado), com filtros opcionais por banco e por status ativo.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID do cliente (customer.id) dono dos padrões.
`id_banco`	`int`	query	não	Filtra pelos padrões de um banco específico.
`ativo`	`bool`	query	não	Filtra por `ativo=true` ou `ativo=false`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Padrões de regra por banco recuperados com sucesso",
  "data": [
    {
      "id": 88,
      "id_usuario_created": 7,
      "id_cliente": 42,
      "id_banco": 7,
      "id_plano_contas": 3,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "nome": "Tarifas bancárias",
      "campo_destino": "conta_debito",
      "tipo_exportacao": "conta",
      "id_conta": 155,
      "valor_destino": null,
      "ordem": 0,
      "ativo": true,
      "conta_codigo": "1.1.02.001",
      "conta_nome": "Tarifas bancárias",
      "condicoes": []
    }
  ]
}

Escopo: padrao_regra_banco:read

`GET /padrao-regra-banco/{padrao_id}`

Detalha um padrão pelo ID inteiro. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`padrao_id`	`int`	path	sim	ID interno do padrão

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Padrão de regra por banco encontrado",
  "data": {
    "id": 88,
    "id_usuario_created": 7,
    "id_cliente": 42,
    "id_banco": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "nome": "Tarifas bancárias",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 155,
    "valor_destino": null,
    "ordem": 0,
    "ativo": true,
    "conta_codigo": "1.1.02.001",
    "conta_nome": "Tarifas bancárias",
    "condicoes": [
      {
        "id": 201,
        "id_padrao": 88,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TAR ",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Escopo: padrao_regra_banco:read

`PATCH /padrao-regra-banco/{padrao_id}`

Atualiza campos do padrão. O body é um PadraoRegraBancoUpdate com campos parciais - somente o que vier preenchido é alterado. Se condicoes for fornecido (mesmo vazio), substitui toda a cadeia de condições; se omitido, mantém as condições atuais. Os campos id_cliente, id_banco, id_usuario_created, id e data_hora_criacao são imutáveis.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`padrao_id`	`int`	path	sim	ID do padrão

Request (PadraoRegraBancoUpdate - todos os campos opcionais)

{
  "nome": "Tarifas bancárias (revisado)",
  "ativo": false,
  "condicoes": [
    {
      "campo_comparacao": "historico",
      "modo_comparacao": "contem",
      "conteudo_comparacao": "TARIFA",
      "proxima_comparacao": null,
      "ordem": 1
    }
  ]
}

Response 200 OK

{
  "success": true,
  "message": "Padrão atualizado com sucesso",
  "data": {
    "id": 88,
    "id_usuario_created": 7,
    "id_cliente": 42,
    "id_banco": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "nome": "Tarifas bancárias (revisado)",
    "campo_destino": "conta_debito",
    "tipo_exportacao": "conta",
    "id_conta": 155,
    "valor_destino": null,
    "ordem": 0,
    "ativo": false,
    "conta_codigo": "1.1.02.001",
    "conta_nome": "Tarifas bancárias",
    "condicoes": [
      {
        "id": 202,
        "id_padrao": 88,
        "campo_comparacao": "historico",
        "modo_comparacao": "contem",
        "conteudo_comparacao": "TARIFA",
        "proxima_comparacao": null,
        "ordem": 1
      }
    ]
  }
}

Escopo: padrao_regra_banco:write

`DELETE /padrao-regra-banco/{padrao_id}`

Remove o padrão e, por cascade, todas as suas condições. Quando o padrão não existe, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`padrao_id`	`int`	path	sim	ID do padrão

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta.

Escopo: padrao_regra_banco:write

Schemas

`PadraoRegraBancoCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente (customer.id) dono do padrão.
`id_banco`	`int`	sim	ID do banco (banco.id) ao qual o padrão pertence.
`id_plano_contas`	`int`	sim	ID do plano de contas (plano_contas.id) sob o qual o padrão atua.
`nome`	`str`	sim	Nome descritivo (1-200 caracteres).
`campo_destino`	`CampoDestino`	sim	Campo sugerido: `conta_debito`, `conta_credito` ou `historico`.
`tipo_exportacao`	`TipoExportacao`	não	Estratégia de preenchimento. Default `conta`. Valores: `conta`, `historico`, `flexivel`.
`id_conta`	`int`	condicional	ID da conta sugerida (contas.id). Obrigatório quando `tipo_exportacao='conta'`.
`valor_destino`	`str`	condicional	Texto/template (máx. 500). Obrigatório quando `tipo_exportacao` é `historico` ou `flexivel`.
`ordem`	`int`	não	Ordem de avaliação entre padrões do mesmo banco (asc, `≥ 0`). Default `0`.
`ativo`	`bool`	não	Quando `false`, o padrão é ignorado na avaliação de importações. Default `true`.
`condicoes`	`List[CondicaoPadraoBancoCreate]`	não	Lista (0-100) de condições encadeadas. Vazia = padrão blanket. Default `[]`.

`PadraoRegraBancoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. Se condicoes for enviado (mesmo vazio), substitui toda a cadeia atual.

Campo	Tipo	Observações
`id_plano_contas`	`int`	Novo plano de contas.
`nome`	`str`	Novo nome (1-200 caracteres).
`campo_destino`	`CampoDestino`	Novo campo de destino.
`tipo_exportacao`	`TipoExportacao`	Nova estratégia de preenchimento.
`id_conta`	`int`	Nova conta sugerida.
`valor_destino`	`str`	Novo texto/template (máx. 500).
`ordem`	`int`	Nova ordem de avaliação (`≥ 0`).
`ativo`	`bool`	Ativa/desativa o padrão.
`condicoes`	`List[CondicaoPadraoBancoCreate]`	Quando fornecida (mesmo vazia), substitui TODAS as condições. Omitida mantém as atuais.

`PadraoRegraBancoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do padrão.
`id_usuario_created`	`int`	Usuário que criou o padrão.
`id_cliente`	`int`	Cliente dono do padrão.
`id_banco`	`int`	Banco ao qual o padrão pertence.
`id_plano_contas`	`int`	Plano de contas sob o qual o padrão atua.
`data_hora_criacao`	`datetime`	Criação, normalizada para o fuso `America/Sao_Paulo`.
`nome`	`str`	Nome descritivo.
`campo_destino`	`str`	Campo sugerido.
`tipo_exportacao`	`str`	Estratégia de preenchimento.
`id_conta`	`int`	Conta sugerida (pode ser `null`).
`valor_destino`	`str`	Texto/template (pode ser `null`).
`ordem`	`int`	Ordem de avaliação.
`ativo`	`bool`	Situação do padrão.
`conta_codigo`	`str`	Enriquecimento somente leitura: código da conta (quando carregada).
`conta_nome`	`str`	Enriquecimento somente leitura: nome da conta (quando carregada).
`condicoes`	`List[CondicaoPadraoBancoRead]`	Cadeia de condições do padrão (default `[]`).

`CondicaoPadraoBancoCreate`

Campo	Tipo	Obrigatório	Observações
`campo_comparacao`	`CampoComparacao`	sim	Campo do lançamento de origem a ser comparado.
`modo_comparacao`	`ModoComparacao`	sim	Operador de comparação aplicado ao campo.
`conteudo_comparacao`	`str`	não	Valor de referência (máx. 500). Pode ser `null` em operadores unários (`valido`/`nao_valido`).
`proxima_comparacao`	`ProximaComparacao`	não	Conector lógico com a próxima condição: `E` (AND) ou `OU` (OR). `null` na última.
`ordem`	`int`	não	Ordem de avaliação na cadeia (asc, `≥ 0`). Default `1`.

`CondicaoPadraoBancoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador da condição.
`id_padrao`	`int`	Padrão ao qual a condição pertence.
`campo_comparacao`	`str`	Campo comparado.
`modo_comparacao`	`str`	Operador de comparação.
`conteudo_comparacao`	`str`	Valor de referência (pode ser `null`).
`proxima_comparacao`	`str`	Conector lógico (pode ser `null`).
`ordem`	`int`	Ordem de avaliação na cadeia.

Literais reutilizados do motor de regras

Os tipos CampoComparacao, ModoComparacao, ProximaComparacao, CampoDestino e TipoExportacao são os mesmos Literais canônicos do domínio de Regras de Lançamento - o padrão é avaliado pelo mesmo mecanismo de regras, sem divergência.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). A exceção é o DELETE, que retorna 204 No Content sem corpo.
A rota estática GET /padrao-regra-banco/cliente/{id_cliente} é declarada antes da rota dinâmica GET /padrao-regra-banco/{padrao_id}, garantindo que cliente não seja interpretado como um padrao_id.
Um padrão sem condições (condicoes: []) é blanket: casa todo lançamento do banco. Com condições, o casamento é refinado pela cadeia encadeada.
No PATCH, enviar condicoes (mesmo vazio) substitui toda a cadeia; omitir mantém as condições existentes.
Erros de negócio são mapeados por conteúdo da mensagem: "não encontrado" → 404, "acesso negado" → 403, "já existe/duplicado" → 409, demais → 422 Unprocessable Entity.