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-amostrasEscopos necessários
estrutura_amostras:read- consulta de metadados, download e preview (rotasGET).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 estrutura | Extensõ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 estruturascsv, o arquivo precisa ser lido com sucesso pelo mesmo processamento do preview; parapdf, 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:
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_estrutura | int | sim | Estrutura dona da planilha base. Deve estar ativa. |
arquivo | arquivo | sim | Conforme Formatos e limites. |
Request
POST /api/v1/estrutura-amostras/
Content-Type: multipart/form-data
id_estrutura=12
arquivo=@extrato_modelo.xlsxResponse 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
id_estrutura | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
estrutura_amostra_id | rota | int | sim | ID da planilha base. |
arquivo | multipart | arquivo | sim | Novo arquivo. |
Request
PUT /api/v1/estrutura-amostras/31
Content-Type: multipart/form-data
arquivo=@extrato_modelo_v2.xlsxResponse 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
estrutura_amostra_id | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
estrutura_amostra_id | rota | int | sim | ID da planilha base. |
Request
Sem corpo de requisição.
Response 200 OK
Content-Typeconforme a extensão:text/csv,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheetouapplication/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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
estrutura_amostra_id | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
estrutura_amostra_id | rota | int | sim | Planilha 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.
| Campo | Tipo | Observações |
|---|---|---|
id | int | ID da planilha base. |
id_estrutura | int | Estrutura dona da planilha. |
nome_arquivo | str (≤ 255) | Nome do arquivo enviado, higienizado. |
extensao | str | csv, xls, xlsx ou pdf. |
tamanho_bytes | int | Tamanho do arquivo em bytes. |
data_hora_criacao | datetime | null | Criação. |
data_hora_atualizacao | datetime | null | Última atualização. |
EstruturaAmostraCopiar
Corpo de POST /estrutura-amostras/{estrutura_amostra_id}/copiar.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_estrutura | int | sim | Estrutura que recebe a cópia. |
Notas
- Cada estrutura tem no máximo uma planilha base; o
POSTem uma estrutura que já tem retorna409. - O
PUTsubstitui o arquivo e seus metadados;id_estruturanão muda. - Nenhuma resposta JSON inclui o conteúdo do arquivo - ele só sai em
GET .../arquivo.