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. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/exportacoes

Escopos necessários

exportacoes:read - listagem do histórico e re-download do arquivo

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 (`customer.id`).
`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

{
  "success": true,
  "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..."
    }
  ]
}

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 { success, message, data }: retorna o arquivo diretamente como FileResponse (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

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 (`customer.id`) 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.

Caminho interno não é exposto

O campo interno nome_arquivo_armazenado (caminho em disco) é omitido propositalmente do schema - mesmo padrão do ImportacaoListItem, que esconde path_arquivo. Para obter o conteúdo, use GET /exportacoes/{exportacao_id}/arquivo.

Notas

Domínio somente leitura: não há POST/PUT/DELETE. A criação de exportações acontece no fluxo transacional de POST /api/v1/lancamentos-contabeis/exportar.
A listagem (GET /exportacoes/) segue o envelope padrão { success, message, data } (ou { success: false, message, details } em erro).
O re-download (GET /exportacoes/{exportacao_id}/arquivo) não usa envelope: devolve o arquivo TXT diretamente como FileResponse (text/plain; charset=utf-8), com um nome de arquivo amigável no Content-Disposition.
A listagem é uma visão compartilhada do escritório - não é restrita ao usuário logado.