Estruturas

Endpoints da WebApiAlcance para gerenciar estruturas - os layouts que descrevem como mapear as colunas de um extrato bancário (arquivo PDF ou CSV) para os campos contábeis (data, descrição, valor, débito/crédito etc.). Uma estrutura pode ser global (visível para todos os clientes do usuário) ou custom (vinculada a um id_cliente específico). Cobrem criação, listagem com filtros, preview de arquivo antes de persistir, detalhamento por ID, atualização parcial e exclusão lógica (soft delete).

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/estruturas

Escopos necessários

estruturas:read - listagem, detalhamento e preview
estruturas:write - criação, atualização e soft delete

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

Endpoints

`POST /estruturas/`

Cria uma nova estrutura. Se id_cliente vier null, a estrutura é global; caso contrário, é custom de um cliente (o service valida o ownership hierárquico do cliente). Quando id_banco é informado, ele é validado contra o catálogo global de bancos do escritório.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (EstruturaCreate). Campos obrigatórios: nome, tipo_arquivo, coluna_data, coluna_descricao, coluna_valor. Demais campos são opcionais.

Request

{
  "nome": "Extrato Itaú PJ",
  "banco_origem": "Itaú",
  "id_banco": 3,
  "tipo_arquivo": "csv",
  "coluna_data": 0,
  "coluna_descricao": 2,
  "coluna_valor": 3,
  "formato_data": "DD/MM/YYYY",
  "separador_csv": ";",
  "decimal_separator": ",",
  "encoding": "utf-8",
  "id_cliente": null
}

Response 201 Created

{
  "success": true,
  "message": "Estrutura criada com sucesso",
  "data": {
    "id": 42,
    "nome": "Extrato Itaú PJ",
    "banco_origem": "Itaú",
    "id_banco": 3,
    "tipo_arquivo": "csv",
    "coluna_data": 0,
    "coluna_descricao": 2,
    "coluna_valor": 3,
    "coluna_debito_credito": null,
    "coluna_documento": null,
    "coluna_historico_complementar": null,
    "formato_data": "DD/MM/YYYY",
    "separador_csv": ";",
    "decimal_separator": ",",
    "encoding": "utf-8",
    "id_cliente": null,
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_atualizacao": null,
    "ativo": true
  }
}

Escopo: estruturas:write

`GET /estruturas/`

Lista as estruturas visíveis ao usuário logado, com filtros por cliente, tipo de arquivo e escopo. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhuma estrutura encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	query	não	ID do cliente. Se omitido com `escopo=both` ou `global`, retorna apenas estruturas globais.
`tipo`	`"pdf"` \| `"csv"`	query	não	Filtra pelo tipo de arquivo.
`escopo`	`"global"` \| `"custom"` \| `"both"`	query	não	`global` = apenas globais; `custom` = apenas do cliente; `both` = união. Default `both`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Estruturas recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "nome": "Extrato Itaú PJ",
      "banco_origem": "Itaú",
      "id_banco": 3,
      "tipo_arquivo": "csv",
      "coluna_data": 0,
      "coluna_descricao": 2,
      "coluna_valor": 3,
      "coluna_debito_credito": null,
      "coluna_documento": null,
      "coluna_historico_complementar": null,
      "formato_data": "DD/MM/YYYY",
      "separador_csv": ";",
      "decimal_separator": ",",
      "encoding": "utf-8",
      "id_cliente": null,
      "id_usuario_created": 7,
      "data_hora_criacao": "2026-07-03T10:15:00",
      "data_hora_atualizacao": null,
      "ativo": true
    }
  ]
}

Escopo: estruturas:read

`POST /estruturas/preview`

Lê um arquivo sem persistir e devolve o cabeçalho detectado + até 5 linhas de amostra, para o frontend confirmar quais índices de coluna mapear antes de criar/editar a estrutura. Suporta CSV e PDF (para PDF, a primeira tabela detectada via pdfplumber é retornada).

Parâmetros

Os campos são enviados no corpo em multipart/form-data; não há parâmetros de rota ou query.

Parâmetro	Tipo	Local	Obrigatório	Descrição
`tipo`	`"pdf"` \| `"csv"`	form	sim	Tipo do arquivo a analisar.
`arquivo`	arquivo	form/file	sim	Arquivo CSV (ou PDF na Phase 2).

Request

Enviado como multipart/form-data com os campos tipo e arquivo (sem corpo JSON).

Response 200 OK

{
  "success": true,
  "message": "Preview gerado com sucesso",
  "data": {
    "tipo": "csv",
    "colunas_detectadas": ["Data", "Documento", "Histórico", "Valor"],
    "linhas_amostra": [
      ["01/07/2026", "000123", "Pagamento fornecedor", "-1500,00"],
      ["02/07/2026", "000124", "Recebimento cliente", "3200,00"]
    ],
    "total_colunas": 4,
    "encoding_detectado": "utf-8",
    "separador_detectado": ";"
  }
}

Arquivo inválido retorna 400 Bad Request com detail descritivo.

Escopo: estruturas:read

`GET /estruturas/{estrutura_id}`

Detalha uma estrutura pelo ID inteiro. Quando não encontrada (ou sem acesso), retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`estrutura_id`	`int`	path	sim	ID interno da estrutura

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Estrutura encontrada com sucesso",
  "data": {
    "id": 42,
    "nome": "Extrato Itaú PJ",
    "banco_origem": "Itaú",
    "id_banco": 3,
    "tipo_arquivo": "csv",
    "coluna_data": 0,
    "coluna_descricao": 2,
    "coluna_valor": 3,
    "coluna_debito_credito": null,
    "coluna_documento": null,
    "coluna_historico_complementar": null,
    "formato_data": "DD/MM/YYYY",
    "separador_csv": ";",
    "decimal_separator": ",",
    "encoding": "utf-8",
    "id_cliente": null,
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_atualizacao": null,
    "ativo": true
  }
}

Escopo: estruturas:read

`PUT /estruturas/{estrutura_id}`

Atualiza uma estrutura existente. O body é um EstruturaUpdate com campos parciais - somente o que vier preenchido é alterado. id, id_cliente e id_usuario_created são imutáveis e não podem ser enviados. O campo ativo pode ser usado para reativar uma estrutura que sofreu soft delete.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`estrutura_id`	`int`	path	sim	ID interno da estrutura

Request (EstruturaUpdate - todos os campos opcionais)

{
  "nome": "Extrato Itaú PJ - v2",
  "coluna_valor": 4,
  "ativo": true
}

Response 200 OK

{
  "success": true,
  "message": "Estrutura atualizada com sucesso",
  "data": {
    "id": 42,
    "nome": "Extrato Itaú PJ - v2",
    "banco_origem": "Itaú",
    "id_banco": 3,
    "tipo_arquivo": "csv",
    "coluna_data": 0,
    "coluna_descricao": 2,
    "coluna_valor": 4,
    "coluna_debito_credito": null,
    "coluna_documento": null,
    "coluna_historico_complementar": null,
    "formato_data": "DD/MM/YYYY",
    "separador_csv": ";",
    "decimal_separator": ",",
    "encoding": "utf-8",
    "id_cliente": null,
    "id_usuario_created": 7,
    "data_hora_criacao": "2026-07-03T10:15:00",
    "data_hora_atualizacao": "2026-07-03T11:42:00",
    "ativo": true
  }
}

Escopo: estruturas:write

`DELETE /estruturas/{estrutura_id}`

Remove uma estrutura por soft delete (marca ativo = false, sem apagar o registro). Para reativar, use PUT /estruturas/{estrutura_id} com ativo: true conforme a semântica do schema.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`estrutura_id`	`int`	path	sim	ID interno da estrutura

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta.

Quando não encontrada, retorna 404 Not Found.

Escopo: estruturas:write

Schemas

`EstruturaCreate`

Herda todos os campos de EstruturaBase e adiciona id_cliente.

Campo	Tipo	Obrigatório	Observações
`nome`	`str`	sim	Máx. 150 caracteres. Ex.: `Extrato Itaú PJ`.
`banco_origem`	`str`	não	Máx. 100 caracteres. Ex.: `Itaú`.
`id_banco`	`int`	não	Banco padrão (catálogo global) desta estrutura. Ao usá-la em importação, herda o banco e as regras. `null` = sem banco padrão.
`tipo_arquivo`	`"pdf"` \| `"csv"`	sim	Tipo do arquivo do extrato.
`coluna_data`	`int` (`>= 0`)	sim	Índice (base 0) da coluna de data.
`coluna_descricao`	`int` (`>= 0`)	sim	Índice da coluna de descrição/histórico.
`coluna_valor`	`int` (`>= 0`)	sim	Índice da coluna de valor.
`coluna_debito_credito`	`int` (`>= 0`)	não	Índice da coluna D/C. `null` = inferir do sinal do valor.
`coluna_documento`	`int` (`>= 0`)	não	Índice da coluna de número do documento.
`coluna_historico_complementar`	`int` (`>= 0`)	não	Índice da coluna de histórico complementar.
`formato_data`	`str`	não	Máx. 20 caracteres. Default `DD/MM/YYYY`.
`separador_csv`	`str`	não	Máx. 5 caracteres. Default `;`.
`decimal_separator`	`str`	não	Máx. 2 caracteres. Default `,`.
`encoding`	`str`	não	Máx. 20 caracteres. Default `utf-8`.
`id_cliente`	`int`	não	`null` = estrutura global (visível a todos os clientes do usuário); preenchido = custom.

`EstruturaUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. id, id_cliente e id_usuario_created são imutáveis e não aparecem aqui (bloqueio de mass-assignment).

Campo	Tipo	Observações
`nome`	`str`	Máx. 150 caracteres.
`banco_origem`	`str`	Máx. 100 caracteres.
`id_banco`	`int`	Banco padrão (catálogo). O service usa `exclude_unset` para distinguir "não informado" de "limpar para NULL".
`tipo_arquivo`	`"pdf"` \| `"csv"`	Tipo do arquivo.
`coluna_data`	`int` (`>= 0`)	Novo índice da coluna de data.
`coluna_descricao`	`int` (`>= 0`)	Novo índice da coluna de descrição.
`coluna_valor`	`int` (`>= 0`)	Novo índice da coluna de valor.
`coluna_debito_credito`	`int` (`>= 0`)	Novo índice da coluna D/C.
`coluna_documento`	`int` (`>= 0`)	Novo índice da coluna de documento.
`coluna_historico_complementar`	`int` (`>= 0`)	Novo índice da coluna de histórico complementar.
`formato_data`	`str`	Máx. 20 caracteres.
`separador_csv`	`str`	Máx. 5 caracteres.
`decimal_separator`	`str`	Máx. 2 caracteres.
`encoding`	`str`	Máx. 20 caracteres.
`ativo`	`bool`	Use `false` para reativar uma estrutura soft-deletada (POST/PUT).

`EstruturaRead`

Herda todos os campos de EstruturaBase e adiciona os campos de leitura abaixo.

Campo	Tipo	Notas
`id`	`int`	Identificador da estrutura.
`id_cliente`	`int`	`null` = global; preenchido = custom.
`id_usuario_created`	`int`	Usuário que criou a estrutura.
`data_hora_criacao`	`datetime`	Data/hora de criação.
`data_hora_atualizacao`	`datetime`	Data/hora da última atualização (`null` se nunca editada).
`ativo`	`bool`	`false` após soft delete.

`EstruturaPreviewResponse`

Resposta do POST /estruturas/preview. Contém o cabeçalho detectado e até 5 linhas de amostra para o frontend confirmar o mapeamento de colunas antes de persistir.

Campo	Tipo	Notas
`tipo`	`"pdf"` \| `"csv"`	Tipo do arquivo analisado.
`colunas_detectadas`	`List[str]`	Header parseado do CSV (ou, na Phase 2, nomes inferidos do PDF).
`linhas_amostra`	`List[List[str]]`	Até 5 linhas de exemplo, na ordem original do arquivo.
`total_colunas`	`int`	Quantidade de colunas detectadas.
`encoding_detectado`	`str`	Encoding detectado (pode ser `null`).
`separador_detectado`	`str`	Separador detectado (pode ser `null`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). O DELETE é a exceção: retorna 204 No Content sem corpo.
Os índices de coluna (coluna_*) são base 0 e casam com as posições retornadas por POST /estruturas/preview.
O POST /estruturas/preview é declarado antes da rota dinâmica GET /estruturas/{estrutura_id}, e usa POST, então não há colisão de roteamento.
Códigos de erro do domínio são mapeados a partir da mensagem: não encontrado → 404, acesso negado → 403, já existe/duplicado → 409, demais validações → 422 (no preview, arquivo inválido → 400).
Estruturas globais (id_cliente = null) são visíveis a todos os clientes do usuário; estruturas custom exigem validação de ownership hierárquico do cliente na criação.