Movimentação Bancária

Endpoints da WebApiAlcance para gerenciar lançamentos de movimentação bancária dos clientes - os débitos e créditos registrados por conta, banco e classe financeira (originados da integração com o Klingo ERP). Cobrem criação, listagem com filtros e paginação, detalhamento por ID, atualização parcial e exclusão.

Base path

/api/v1/movimentacao-bancaria

Escopos necessários

• movimentacao_bancaria:read - listagem e detalhamento
• movimentacao_bancaria:write - criação, atualização e exclusão

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

Endpoints

POST /movimentacao-bancaria/

Cria um novo lançamento de movimentação bancária. Todos os campos são opcionais; recomenda-se enviar ao menos cnpj, data e o valor em debito ou credito.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (MovimentacaoBancariaCreate), com todos os campos opcionais.

Request

{
  "cnpj": "12345678000199",
  "cfg_emp": "EMP-001",
  "unidade": "Matriz",
  "classe_financeira_nome": "Receita de Serviços",
  "empresa_historico": "Recebimento NF 1523",
  "lote": "L-2026-07",
  "documento": 1523,
  "data": "2026-07-03",
  "banco": "Banco do Brasil",
  "agencia": 1234,
  "conta": 567890,
  "debito": 0,
  "credito": 150000
}

Response 201 Created

{
  "success": true,
  "message": "Movimentação bancária criada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP-001",
    "unidade": "Matriz",
    "classe_financeira_nome": "Receita de Serviços",
    "empresa_historico": "Recebimento NF 1523",
    "lote": "L-2026-07",
    "documento": 1523,
    "data": "2026-07-03",
    "banco": "Banco do Brasil",
    "agencia": 1234,
    "conta": 567890,
    "debito": 0,
    "credito": 150000,
    "data_hora_criacao": "2026-07-03T14:22:05"
  }
}

Quando os dados são inválidos, retorna 422 Unprocessable Entity com detail descrevendo o erro.

Escopo: movimentacao_bancaria:write

GET /movimentacao-bancaria/

Lista os lançamentos de movimentação bancária, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma movimentação bancária encontrada.".

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Movimentações bancárias recuperadas com sucesso",
  "data": [
    { "id": 4821, "cnpj": "12345678000199", "data": "2026-07-03", "credito": 150000 },
    { "id": 4822, "cnpj": "12345678000199", "data": "2026-07-03", "debito": 32000 }
  ]
}

Escopo: movimentacao_bancaria:read

GET /movimentacao-bancaria/{movimentacao_id}

Detalha um lançamento de movimentação bancária pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail descrevendo o erro.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Movimentação bancária recuperada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP-001",
    "unidade": "Matriz",
    "classe_financeira_nome": "Receita de Serviços",
    "empresa_historico": "Recebimento NF 1523",
    "lote": "L-2026-07",
    "documento": 1523,
    "data": "2026-07-03",
    "banco": "Banco do Brasil",
    "agencia": 1234,
    "conta": 567890,
    "debito": 0,
    "credito": 150000,
    "data_hora_criacao": "2026-07-03T14:22:05"
  }
}

Escopo: movimentacao_bancaria:read

PUT /movimentacao-bancaria/{movimentacao_id}

Atualiza um lançamento existente. O body é um MovimentacaoBancariaUpdate com campos parciais - somente o que vier preenchido é alterado. Os campos cnpj e cfg_emp são imutáveis via PUT e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

Request (MovimentacaoBancariaUpdate - todos os campos opcionais)

{
  "empresa_historico": "Recebimento NF 1523 (ajustado)",
  "credito": 148500
}

Response 200 OK

{
  "success": true,
  "message": "Movimentação bancária atualizada com sucesso",
  "data": {
    "id": 4821,
    "cnpj": "12345678000199",
    "cfg_emp": "EMP-001",
    "unidade": "Matriz",
    "classe_financeira_nome": "Receita de Serviços",
    "empresa_historico": "Recebimento NF 1523 (ajustado)",
    "lote": "L-2026-07",
    "documento": 1523,
    "data": "2026-07-03",
    "banco": "Banco do Brasil",
    "agencia": 1234,
    "conta": 567890,
    "debito": 0,
    "credito": 148500,
    "data_hora_criacao": "2026-07-03T14:22:05"
  }
}

Retorna 404 Not Found quando o registro não existe e 422 Unprocessable Entity para dados inválidos.

Escopo: movimentacao_bancaria:write

DELETE /movimentacao-bancaria/{movimentacao_id}

Remove um lançamento de movimentação bancária pelo ID. Quando não encontrado, retorna 404 Not Found.

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Movimentação bancária removida com sucesso",
  "data": null
}

Escopo: movimentacao_bancaria:write

Schemas

MovimentacaoBancariaCreate

Herda todos os campos de MovimentacaoBancariaBase. Todos são opcionais.

MovimentacaoBancariaUpdate

Todos os campos são opcionais; apenas os enviados são atualizados. Não inclui cnpj nem cfg_emp - esses campos são imutáveis via PUT (mass-assignment guard).

MovimentacaoBancariaRead

Estende MovimentacaoBancariaBase (todos os campos acima) com os campos abaixo.

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Códigos HTTP refletem semântica REST padrão.
• GET /movimentacao-bancaria/ retorna 200 OK com data: [] quando nenhum registro corresponde aos filtros - lista vazia não é erro.
• O filtro limit aceita valores de 1 a 500 (default 100); offset deve ser >= 0 (default 0).
• Os campos cnpj e cfg_emp são definidos na criação e não podem ser alterados via PUT - para corrigi-los, exclua e recrie o lançamento.
• Os lançamentos têm origem na integração com o Klingo ERP.