Exportações
Endpoints da WebApiAlcance para consultar o histórico de exportações contábeis - os arquivos gerados a partir de lançamentos contábeis do escritório. Este domínio é somente leitura: cobre a listagem do histórico (com filtros por cliente e período) e o re-download do arquivo TXT já armazenado.
A criação não acontece aqui
Exportações não são criadas por estes endpoints. A geração ocorre no fluxo transacional de POST /api/v1/lancamentos-contabeis/exportar (domínio lancamentos_contabil). Aqui você apenas consulta e re-baixa o que já foi produzido - por isso não há POST/PUT/DELETE nem schemas Create/Update.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/exportacoesEscopos necessários
exportacoes:read- listagem do histórico, re-download do arquivo e resumo de regrasregras_lancamento:read- adicional, exigido porGET /exportacoes/{exportacao_id}/regras
O escopo é derivado da rota: o prefixo /exportacoes vira o recurso exportacoes, e o método HTTP define a ação (read para GET). Como o domínio é somente leitura, apenas exportacoes:read é exercido pelos endpoints públicos abaixo; exportacoes:write existe na convenção de escopos, mas a escrita (criação) ocorre pelo domínio de lançamentos contábeis.
Endpoints
GET /exportacoes/
Lista o histórico de exportações (visão compartilhada do escritório), com filtros opcionais por cliente e período e paginação por limit/offset. Lista vazia é um estado válido - retorna 200 OK com data: [] e message: "Nenhuma exportacao encontrada.".
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
id_cliente | int | query | não | ID do cliente. |
data_inicio | date | query | não | Filtra exportações cujo período começa em ou após esta data (YYYY-MM-DD). |
data_fim | date | query | não | Filtra exportações cujo período termina em ou antes desta data (YYYY-MM-DD). |
limit | int | query | não | Tamanho da página. Default 50, mínimo 1, máximo 500. |
offset | int | query | não | Deslocamento da paginação. Default 0, mínimo 0. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Exportacoes recuperadas com sucesso",
"data": [
{
"id": 42,
"id_usuario_created": 7,
"id_cliente": 1234,
"data_inicio": "2026-01-01",
"data_fim": "2026-01-31",
"data_hora_criacao": "2026-02-03T14:22:05-03:00",
"qtd_lancamentos": 318,
"nome_arquivo_original": "lancamentos_202601.txt",
"tamanho_bytes": 40960,
"hash_arquivo": "9f2b1c8a4e0d...",
"vinculo_lancamentos": true
}
]
}Filtros inválidos (ex.: intervalo de datas inconsistente) retornam 400 Bad Request com o detalhe do erro de validação.
Escopo: exportacoes:read
GET /exportacoes/{exportacao_id}/arquivo
Re-download do arquivo TXT armazenado para a exportação indicada. Diferente dos demais endpoints, a resposta não segue o envelope { status, message, data }: retorna o arquivo diretamente como arquivo (text/plain; charset=utf-8), com um nome amigável no Content-Disposition e nunca o caminho interno de disco.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
exportacao_id | int | path | sim | ID interno da exportação. |
Request
Sem corpo de requisição.
Response 200 OK
Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="lancamentos_202601.txt"
<conteúdo do arquivo TXT>Retorna 404 Not Found quando o registro da exportação não existe ou quando o arquivo não está mais disponível em disco. Ambos os casos mapeiam para 404 com detail explicando o motivo (ex.: "nao encontrada" / "nao esta mais disponivel").
Escopo: exportacoes:read
GET /exportacoes/{exportacao_id}/regras
Resumo "Ver regras" da exportação: quais regras classificaram os lançamentos do TXT, quais ficaram em conflito e quantos lançamentos não tiveram regra. Mesmo formato de GET /importacoes/{importacao_id}/regras; regras_criadas é sempre [] (exportação não cria regra).
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
exportacao_id | int | path | sim | ID interno da exportação. |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Regras da exportacao recuperadas com sucesso",
"data": {
"vinculo_exato": true,
"total_lancamentos": 318,
"lancamentos_sem_regra": 12,
"lancamentos_em_conflito": 3,
"regras_aplicadas": [
{ "id_regra": 15, "qtd_lancamentos": 120, "regra": { "id": 15, "nome": "Tarifa bancaria" } }
],
"regras_em_conflito": [],
"regras_criadas": []
}
}regra traz o mesmo objeto de leitura de GET /regras-lancamento (resumido acima) ou null quando a regra foi excluída depois. Retorna 404 Not Found se a exportação não existe.
Exportações antigas
Quando vinculo_exato é false (vinculo_lancamentos = false na exportação), o conjunto de lançamentos é aproximado por cliente, período e status exportado, e pode incluir lançamentos de outra exportação com período sobreposto.
Escopo: exportacoes:read + regras_lancamento:read
Schemas
ExportacaoRead
Representação completa de uma exportação - serve tanto como item de lista quanto como detalhe.
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador da exportação. |
id_usuario_created | int | Usuário que gerou a exportação. |
id_cliente | int | Cliente ao qual a exportação pertence. |
data_inicio | date | Início do período dos lançamentos exportados. |
data_fim | date | Fim do período dos lançamentos exportados. |
data_hora_criacao | datetime | Data/hora da criação, normalizada para o fuso America/Sao_Paulo (horário de Brasília). |
qtd_lancamentos | int | Quantidade de lançamentos incluídos na exportação. |
nome_arquivo_original | str | Nome original do arquivo gerado. |
tamanho_bytes | int | Tamanho do arquivo em bytes. |
hash_arquivo | str | null | Hash do arquivo, quando disponível. |
vinculo_lancamentos | bool | true quando os lançamentos da exportação estão vinculados com exatidão; false em exportações antigas. |
Notas
- Domínio somente leitura: não há
POST/PUT/DELETE. A criação de exportações acontece no fluxo transacional dePOST /api/v1/lancamentos-contabeis/exportar. - A listagem (
GET /exportacoes/) segue o envelope padrão{ status, message, data }(erros de negócio vêm como{ "message": ... }). - O re-download (
GET /exportacoes/{exportacao_id}/arquivo) não usa envelope: devolve o arquivo TXT diretamente como arquivo (text/plain; charset=utf-8), com um nome de arquivo amigável noContent-Disposition. - A listagem é uma visão compartilhada do escritório - não é restrita ao usuário logado.