Bancos

Endpoints da WebApiAlcance para o cadastro de bancos (instituições financeiras) usados na conciliação e na autodetecção de arquivos OFX. O cadastro é multi-tenant: cada banco pertence ao usuário que o criou (id_usuario_created), e as operações são restritas ao dono. Cobrem criação, listagem dos bancos do usuário autenticado (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/bancos

Escopos necessários

bancos:read - listagem do usuário e detalhamento
bancos:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /bancos vira o recurso bancos, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /bancos/`

Cria um novo banco vinculado ao usuário autenticado. O id_usuario_created é preenchido a partir do usuário logado - não é aceito no body. Conflitos (nome/codigo_ofx duplicado) retornam 409 Conflict; validações de negócio retornam 422 Unprocessable Entity.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (BancoCreate): nome (obrigatório), codigo_ofx (opcional) e ativo (opcional, default true).

Request

{
  "nome": "Banco do Brasil",
  "codigo_ofx": "001",
  "ativo": true
}

Response 201 Created

{
  "success": true,
  "message": "Banco criado com sucesso!",
  "data": {
    "id": 1,
    "nome": "Banco do Brasil",
    "codigo_ofx": "001",
    "ativo": true,
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "data_hora_atualizacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: bancos:write

`GET /bancos/by-user`

Lista todos os bancos do usuário autenticado, com filtros opcionais. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum banco encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`ativo`	`bool`	query	não	Quando informado, filtra por `ativo=true` ou `ativo=false`.
`nome`	`str`	query	não	Filtro por nome (busca parcial). Ex.: `Banco do Brasil`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Bancos recuperados com sucesso!",
  "data": [
    {
      "id": 1,
      "nome": "Banco do Brasil",
      "codigo_ofx": "001",
      "ativo": true,
      "id_usuario_created": 42,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "data_hora_atualizacao": "2026-07-03T09:15:00-03:00"
    }
  ]
}

Escopo: bancos:read

`GET /bancos/{banco_id}`

Detalha um banco do usuário autenticado pelo ID inteiro. Quando não encontrado (ou pertencente a outro usuário), retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Banco encontrado!",
  "data": {
    "id": 1,
    "nome": "Banco do Brasil",
    "codigo_ofx": "001",
    "ativo": true,
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "data_hora_atualizacao": "2026-07-03T09:15:00-03:00"
  }
}

Escopo: bancos:read

`PUT /bancos/{banco_id}`

Atualiza um banco existente do usuário autenticado. O body é um BancoUpdate com campos parciais - somente o que vier preenchido é alterado. Campos id, id_usuario_created e timestamps são imutáveis e não aparecem no schema (proteção contra mass-assignment).

Parâmetros

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

Request (BancoUpdate - todos os campos opcionais)

{
  "nome": "Banco do Brasil S.A.",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Banco atualizado!",
  "data": {
    "id": 1,
    "nome": "Banco do Brasil S.A.",
    "codigo_ofx": "001",
    "ativo": false,
    "id_usuario_created": 42,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "data_hora_atualizacao": "2026-07-03T11:42:00-03:00"
  }
}

Escopo: bancos:write

`DELETE /bancos/{banco_id}`

Remove um banco do usuário autenticado pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Banco removido!",
  "data": null
}

Escopo: bancos:write

Schemas

`BancoCreate`

Herda os campos de BancoBase. O id_usuario_created vem do usuário autenticado, não do body.

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	Nome do banco / instituição financeira. 1 a 200 caracteres.
`codigo_ofx`	`str`	não	BANKID/instituição exposto pelo arquivo OFX (usado na autodetecção no upload). Até 50 caracteres. `null` = sem vínculo OFX.
`ativo`	`bool`	não	Default `true`. Quando `false`, o banco é ignorado na autodetecção e nas listagens ativas.

`BancoUpdate`

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

Campo	Tipo	Observações
`nome`	`str`	Novo nome (1 a 200 caracteres).
`codigo_ofx`	`str`	Novo código OFX (até 50 caracteres).
`ativo`	`bool`	Ativa/desativa o banco.

`BancoRead`

Estende BancoBase com os campos gerenciados (identificação, dono e timestamps).

Campo	Tipo	Notas
`id`	`int`	Identificador do banco.
`nome`	`str`	Nome do banco.
`codigo_ofx`	`str`	Código OFX (ou `null`).
`ativo`	`bool`	Situação do banco.
`id_usuario_created`	`int`	ID do usuário que criou (multi-tenant).
`data_hora_criacao`	`datetime`	Timestamp de criação (fuso `America/Sao_Paulo`).
`data_hora_atualizacao`	`datetime`	Timestamp da última atualização (fuso `America/Sao_Paulo`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Cadastro multi-tenant: cada banco pertence ao usuário que o criou. Detalhamento, atualização e exclusão de um banco de outro usuário retornam 404 Not Found.
GET /bancos/by-user é declarado antes da rota dinâmica GET /bancos/{banco_id}, então by-user é resolvido como rota estática (e não interpretado como um banco_id).
Erros de negócio são mapeados por semântica: "não encontrado" → 404, "já existe"/"duplicado" → 409, "acesso negado" → 403, demais → 422.
O campo codigo_ofx alimenta a autodetecção do banco no upload de extratos OFX; bancos com ativo = false são ignorados nesse processo.