Conversor de Extratos Bancários

Endpoints da WebApiAlcance para gerenciar os registros de processamento do Conversor de Extratos Bancários - o histórico das conversões de arquivos de extrato/relatório por banco. Cada registro guarda o arquivo processado, o banco de origem, a situação do processamento e os detalhes da execução. Cobrem criação, listagem geral, detalhamento por ID, atualização 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/conversor-extract

Pasta interna vs. prefixo público

O domínio reside internamente na pasta conversor_data, mas é publicado sob o prefixo /conversor-extract. O escopo e a documentação derivam do prefixo público, não do nome da pasta.

Escopos necessários

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

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

Endpoints

`POST /conversor-extract/`

Registra um novo processamento de conversão de extrato/relatório. O corpo é um ConversorDataCreate.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ConversorDataCreate): arquivo, banco e status (obrigatórios); usuario_id, cliente_id, data_processamento e detalhes (opcionais).

Request

{
  "usuario_id": 7,
  "cliente_id": 1381,
  "arquivo": "extrato_itau_2026-06.pdf",
  "banco": "Itaú",
  "data_processamento": "2026-07-03T14:22:10",
  "status": "concluido",
  "detalhes": "128 lançamentos convertidos"
}

Response 201 Created

{
  "success": true,
  "message": "Processamento registrado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1381,
    "arquivo": "extrato_itau_2026-06.pdf",
    "banco": "Itaú",
    "data_processamento": "2026-07-03T14:22:10",
    "status": "concluido",
    "detalhes": "128 lançamentos convertidos"
  }
}

Escopo: conversor_extract:write

`GET /conversor-extract/`

Lista todos os processamentos registrados. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum registro encontrado.".

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": "Registros recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "usuario_id": 7,
      "cliente_id": 1381,
      "arquivo": "extrato_itau_2026-06.pdf",
      "banco": "Itaú",
      "data_processamento": "2026-07-03T14:22:10",
      "status": "concluido",
      "detalhes": "128 lançamentos convertidos"
    }
  ]
}

Escopo: conversor_extract:read

`GET /conversor-extract/{id}`

Detalha um processamento pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrado.".

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1381,
    "arquivo": "extrato_itau_2026-06.pdf",
    "banco": "Itaú",
    "data_processamento": "2026-07-03T14:22:10",
    "status": "concluido",
    "detalhes": "128 lançamentos convertidos"
  }
}

Escopo: conversor_extract:read

`PUT /conversor-extract/{id}`

Atualiza um registro existente. O corpo é um ConversorDataUpdate com campos parciais - somente o que vier preenchido é alterado. Quando o ID não existe, retorna o envelope de erro com message: "Registro não encontrado para atualização.".

Parâmetros

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

Request (ConversorDataUpdate - todos os campos opcionais)

{
  "status": "erro",
  "detalhes": "Layout de arquivo não reconhecido"
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1381,
    "arquivo": "extrato_itau_2026-06.pdf",
    "banco": "Itaú",
    "data_processamento": "2026-07-03T14:22:10",
    "status": "erro",
    "detalhes": "Layout de arquivo não reconhecido"
  }
}

Escopo: conversor_extract:write

`DELETE /conversor-extract/{id}`

Remove um registro de processamento pelo ID. Quando o ID não existe, retorna o envelope de erro com message: "Registro não encontrado para exclusão.".

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro excluído com sucesso",
  "data": null
}

Escopo: conversor_extract:write

Schemas

`ConversorDataCreate`

Campo	Tipo	Obrigatório	Observações
`arquivo`	`str`	sim	Nome/identificação do arquivo processado.
`banco`	`str`	sim	Banco de origem do extrato/relatório.
`status`	`str`	sim	Situação do processamento (ex.: `concluido`, `erro`).
`usuario_id`	`int`	não	ID do usuário que disparou o processamento.
`cliente_id`	`int`	não	ID do cliente vinculado à conversão.
`data_processamento`	`datetime`	não	Momento do processamento.
`detalhes`	`str`	não	Observações ou resumo da execução.

`ConversorDataUpdate`

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

Campo	Tipo	Observações
`cliente_id`	`int`	Reatribui o registro a outro cliente.
`arquivo`	`str`	Novo nome/identificação do arquivo.
`banco`	`str`	Novo banco de origem.
`data_processamento`	`datetime`	Novo momento do processamento.
`status`	`str`	Nova situação.
`detalhes`	`str`	Novas observações da execução.

`ConversorDataOut`

Campo	Tipo	Notas
`id`	`int`	Identificador do registro.
`usuario_id`	`int`	Usuário que disparou o processamento.
`cliente_id`	`int`	Cliente vinculado à conversão.
`arquivo`	`str`	Arquivo processado.
`banco`	`str`	Banco de origem.
`data_processamento`	`datetime`	Momento do processamento.
`status`	`str`	Situação do processamento.
`detalhes`	`str`	Observações ou resumo da execução.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Estes endpoints gerenciam apenas o registro/histórico das conversões (metadados). O upload e a conversão do arquivo em si não fazem parte deste domínio - não há rota de upload multipart nem task Celery expostas aqui.
GET /conversor-extract/{id} usa o parâmetro de path id (inteiro), não um UUID.