Estruturas: Planilha base

Endpoints da WebApiAlcance para a planilha base (amostra) de uma estrutura de extrato bancário. Cada estrutura tem no máximo uma planilha base (relação 1:1), usada como exemplo do arquivo que a estrutura mapeia. Cobrem upload, consulta de metadados, troca do arquivo, download, preview, cópia para outra estrutura e remoção.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

Base path

/api/v1/estrutura-amostras

Escopos necessários

  • estrutura_amostras:read - consulta de metadados, download e preview (rotas GET).
  • estrutura_amostras:write - upload, troca, cópia e remoção (POST, PUT, DELETE).

O escopo é derivado do prefixo público da rota: /estrutura-amostras vira o recurso estrutura_amostras (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE). O escopo estruturas:* não se aplica a estas rotas.

Todas as rotas exigem usuários do escritório; não há restrição adicional.

Envelope de resposta

Exceto o download (que devolve bytes), toda resposta segue o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

Erros de negócio retornam { "message": ... } com o status HTTP correspondente. Falhas de validação retornam 422 com { "detail": [...] }. Os endpoints de upload, preview e cópia têm limite de requisições por usuário e por IP; ao excedê-lo a resposta é 429.

Formatos e limites

A extensão aceita depende do tipo_arquivo da estrutura:

tipo_arquivo da estruturaExtensões aceitas
csv.csv, .xls, .xlsx
pdf.pdf
  • Tamanho máximo do arquivo: 5 MB. Acima disso a resposta é 413.
  • Arquivo vazio, extensão incompatível com o tipo da estrutura, estrutura inativa ou arquivo ilegível retornam 422. Para estruturas csv, o arquivo precisa ser lido com sucesso pelo mesmo processamento do preview; para pdf, precisa ser um PDF válido.

Endpoints

POST /estrutura-amostras/

Salva a planilha base de uma estrutura que ainda não tem uma. Responde 201 Created.

Parâmetros

Corpo multipart/form-data:

CampoTipoObrigatórioObservações
id_estruturaintsimEstrutura dona da planilha base. Deve estar ativa.
arquivoarquivosimConforme Formatos e limites.

Request

POST /api/v1/estrutura-amostras/
Content-Type: multipart/form-data
 
id_estrutura=12
arquivo=@extrato_modelo.xlsx

Response 201 Created

{
  "status": "success",
  "message": "Planilha base salva com sucesso",
  "data": {
    "id": 31,
    "id_estrutura": 12,
    "nome_arquivo": "extrato_modelo.xlsx",
    "extensao": "xlsx",
    "tamanho_bytes": 20480,
    "data_hora_criacao": "2026-08-05T09:12:44",
    "data_hora_atualizacao": "2026-08-05T09:12:44"
  }
}

Erros: 404 estrutura inexistente; 409 a estrutura já tem planilha base (use PUT para trocar o arquivo); 413 arquivo acima do limite; 422 demais validações.

Escopo: estrutura_amostras:write

GET /estrutura-amostras/estrutura/{id_estrutura}

Devolve os metadados da planilha base de uma estrutura (sem o conteúdo do arquivo).

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
id_estruturarotaintsimID da estrutura

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Planilha base encontrada com sucesso",
  "data": {
    "id": 31,
    "id_estrutura": 12,
    "nome_arquivo": "extrato_modelo.xlsx",
    "extensao": "xlsx",
    "tamanho_bytes": 20480,
    "data_hora_criacao": "2026-08-05T09:12:44",
    "data_hora_atualizacao": "2026-08-05T09:12:44"
  }
}

Retorna 404 quando a estrutura não tem planilha base.

Escopo: estrutura_amostras:read

PUT /estrutura-amostras/{estrutura_amostra_id}

Troca o arquivo da planilha base. As regras de formato e tamanho são as mesmas do POST.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
estrutura_amostra_idrotaintsimID da planilha base.
arquivomultipartarquivosimNovo arquivo.

Request

PUT /api/v1/estrutura-amostras/31
Content-Type: multipart/form-data
 
arquivo=@extrato_modelo_v2.xlsx

Response 200 OK

{
  "status": "success",
  "message": "Planilha base atualizada com sucesso",
  "data": {
    "id": 31,
    "id_estrutura": 12,
    "nome_arquivo": "extrato_modelo_v2.xlsx",
    "extensao": "xlsx",
    "tamanho_bytes": 22016,
    "data_hora_criacao": "2026-08-05T09:12:44",
    "data_hora_atualizacao": "2026-08-06T10:01:12"
  }
}

Erros: 404 planilha base inexistente; 413 arquivo acima do limite; 422 demais validações (inclusive estrutura inativa).

Escopo: estrutura_amostras:write

DELETE /estrutura-amostras/{estrutura_amostra_id}

Remove a planilha base.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
estrutura_amostra_idrotaintsimID da planilha base.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Planilha base removida com sucesso",
  "data": null
}

ID inexistente retorna 404 Not Found.

Escopo: estrutura_amostras:write

GET /estrutura-amostras/{estrutura_amostra_id}/arquivo

Baixa o arquivo da planilha base.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
estrutura_amostra_idrotaintsimID da planilha base.

Request

Sem corpo de requisição.

Response 200 OK

  • Content-Type conforme a extensão: text/csv, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ou application/pdf.
  • Content-Disposition: attachment; filename="<nome ASCII>"; filename*=UTF-8''<nome real>

O download é sempre como anexo. ID inexistente retorna 404.

Sem envelope

Esta rota não responde { status, message, data } - o corpo é o arquivo. Erros saem como { "message": "..." } com o status HTTP real.

Escopo: estrutura_amostras:read

GET /estrutura-amostras/{estrutura_amostra_id}/preview

Gera o preview do arquivo salvo: cabeçalho detectado e até 5 linhas de exemplo, com o mesmo contrato de POST /estruturas/preview (ver EstruturaPreviewResponse).

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
estrutura_amostra_idrotaintsimID da planilha base.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Preview gerado com sucesso",
  "data": {
    "tipo": "csv",
    "colunas_detectadas": ["Data", "Descrição", "Valor"],
    "linhas_amostra": [["05/08/2026", "PIX RECEBIDO", "150,00"]],
    "total_colunas": 3,
    "encoding_detectado": "utf-8",
    "separador_detectado": ";"
  }
}

Retorna 404 quando a planilha base não existe e 400 quando o arquivo salvo não pôde ser lido. Responde com Cache-Control: no-store.

Escopo: estrutura_amostras:read

POST /estrutura-amostras/{estrutura_amostra_id}/copiar

Copia a planilha base para outra estrutura. Responde 201 Created.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
estrutura_amostra_idrotaintsimPlanilha base de origem.

Request

{
  "id_estrutura": 13
}

Response 201 Created

{
  "status": "success",
  "message": "Planilha base copiada com sucesso",
  "data": {
    "id": 32,
    "id_estrutura": 13,
    "nome_arquivo": "extrato_modelo.xlsx",
    "extensao": "xlsx",
    "tamanho_bytes": 20480,
    "data_hora_criacao": "2026-08-06T11:00:00",
    "data_hora_atualizacao": "2026-08-06T11:00:00"
  }
}

Regras da cópia

A estrutura de destino precisa estar ativa, pertencer ao mesmo cliente e ter o mesmo tipo_arquivo da estrutura de origem; caso contrário a resposta é 422. Se o destino já tem planilha base, a resposta é 409. Origem ou destino inexistentes retornam 404.

Escopo: estrutura_amostras:write

Schemas

EstruturaAmostraRead

Item de data em todas as respostas JSON de metadados. Não inclui o conteúdo do arquivo.

CampoTipoObservações
idintID da planilha base.
id_estruturaintEstrutura dona da planilha.
nome_arquivostr (≤ 255)Nome do arquivo enviado, higienizado.
extensaostrcsv, xls, xlsx ou pdf.
tamanho_bytesintTamanho do arquivo em bytes.
data_hora_criacaodatetime | nullCriação.
data_hora_atualizacaodatetime | nullÚltima atualização.

EstruturaAmostraCopiar

Corpo de POST /estrutura-amostras/{estrutura_amostra_id}/copiar.

CampoTipoObrigatórioObservações
id_estruturaintsimEstrutura que recebe a cópia.

Notas

  • Cada estrutura tem no máximo uma planilha base; o POST em uma estrutura que já tem retorna 409.
  • O PUT substitui o arquivo e seus metadados; id_estrutura não muda.
  • Nenhuma resposta JSON inclui o conteúdo do arquivo - ele só sai em GET .../arquivo.