Conversor de Relatórios Bancários

Endpoints da WebApiAlcance para o domínio Conversor de Relatórios Bancários (conversor-report). Cada registro representa o processamento de um arquivo de dados bancários - o arquivo convertido, a estrutura detectada, o status do processamento e os detalhes da execução. As rotas cobrem criação (registro do processamento), 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-report

Escopos necessários

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

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

Endpoints

`POST /conversor-report/`

Registra um novo processamento de dados do conversor de relatórios. Use para persistir o resultado de uma conversão: o arquivo, a estrutura detectada, o status e os detalhes da execução.

Parâmetros

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

Request

{
  "arquivo": "extrato_itau_2026-06.ofx",
  "tipo_estrutura": "OFX",
  "status": "concluido",
  "usuario_id": 7,
  "cliente_id": 1234,
  "data_processamento": "2026-07-03T14:20:00",
  "detalhes": "312 lançamentos convertidos"
}

Response 201 Created

{
  "success": true,
  "message": "Conversão registrada com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1234,
    "arquivo": "extrato_itau_2026-06.ofx",
    "tipo_estrutura": "OFX",
    "data_processamento": "2026-07-03T14:20:00",
    "status": "concluido",
    "detalhes": "312 lançamentos convertidos"
  }
}

Escopo: conversor_report:write

`GET /conversor-report/`

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. A resposta traz data = array de ConversorReportDataOut.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros recuperados com sucesso",
  "data": [
    {
      "id": 42,
      "usuario_id": 7,
      "cliente_id": 1234,
      "arquivo": "extrato_itau_2026-06.ofx",
      "tipo_estrutura": "OFX",
      "data_processamento": "2026-07-03T14:20:00",
      "status": "concluido",
      "detalhes": "312 lançamentos convertidos"
    }
  ]
}

Escopo: conversor_report:read

`GET /conversor-report/{id}`

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

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1234,
    "arquivo": "extrato_itau_2026-06.ofx",
    "tipo_estrutura": "OFX",
    "data_processamento": "2026-07-03T14:20:00",
    "status": "concluido",
    "detalhes": "312 lançamentos convertidos"
  }
}

Escopo: conversor_report:read

`PUT /conversor-report/{id}`

Atualiza um processamento existente. O body é um ConversorReportDataUpdate com campos parciais - somente o que vier preenchido é alterado. Quando não encontrado, retorna o envelope de erro com "Registro não encontrado para atualização.".

Parâmetros

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

Request (ConversorReportDataUpdate - todos os campos opcionais)

{
  "status": "revisado",
  "detalhes": "Reprocessado após ajuste de layout"
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizado com sucesso",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "cliente_id": 1234,
    "arquivo": "extrato_itau_2026-06.ofx",
    "tipo_estrutura": "OFX",
    "data_processamento": "2026-07-03T14:20:00",
    "status": "revisado",
    "detalhes": "Reprocessado após ajuste de layout"
  }
}

Escopo: conversor_report:write

`DELETE /conversor-report/{id}`

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

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: conversor_report:write

Schemas

`ConversorReportDataCreate`

Campo	Tipo	Obrigatório	Observações
`arquivo`	`str`	sim	Nome/identificador do arquivo processado.
`tipo_estrutura`	`str`	sim	Estrutura detectada do arquivo (ex.: `OFX`, `CSV`, `CNAB`).
`status`	`str`	sim	Situação do processamento (ex.: `concluido`, `erro`, `pendente`).
`usuario_id`	`int`	não	ID do usuário que disparou a conversão. Aceita `null`.
`cliente_id`	`int`	não	ID do cliente vinculado ao processamento. Aceita `null`.
`data_processamento`	`datetime`	não	Data/hora do processamento. Aceita `null`.
`detalhes`	`str`	não	Detalhes/observações da execução. Aceita `null`.

`ConversorReportDataUpdate`

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

Campo	Tipo	Observações
`cliente_id`	`int`	Reatribui o processamento a outro cliente.
`arquivo`	`str`	Novo nome/identificador do arquivo.
`tipo_estrutura`	`str`	Nova estrutura detectada.
`data_processamento`	`datetime`	Nova data/hora de processamento.
`status`	`str`	Nova situação do processamento.
`detalhes`	`str`	Novos detalhes/observações.

`ConversorReportDataOut`

Campo	Tipo	Notas
`id`	`int`	Identificador do processamento.
`usuario_id`	`int`	Usuário que disparou a conversão (pode ser `null`).
`cliente_id`	`int`	Cliente vinculado (pode ser `null`).
`arquivo`	`str`	Arquivo processado.
`tipo_estrutura`	`str`	Estrutura detectada do arquivo.
`data_processamento`	`datetime`	Data/hora do processamento (pode ser `null`).
`status`	`str`	Situação do processamento.
`detalhes`	`str`	Detalhes da execução (pode ser `null`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Este domínio registra metadados de processamentos de conversão. Não há endpoint de upload/multipart nem task Celery neste domínio - as rotas apenas persistem e consultam os registros de conversão.
Em criação (POST), atualização (PUT) e exclusão (DELETE), erros de negócio são devolvidos no envelope de erro (success: false) com a mensagem específica descrita em cada endpoint, e não como código HTTP dedicado.