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

Escopos necessários

  • exportacoes:read - listagem do histórico, re-download do arquivo e resumo de regras
  • regras_lancamento:read - adicional, exigido por GET /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âmetroTipoLocalObrigatórioDescrição
id_clienteintquerynãoID do cliente.
data_iniciodatequerynãoFiltra exportações cujo período começa em ou após esta data (YYYY-MM-DD).
data_fimdatequerynãoFiltra exportações cujo período termina em ou antes desta data (YYYY-MM-DD).
limitintquerynãoTamanho da página. Default 50, mínimo 1, máximo 500.
offsetintquerynãoDeslocamento 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âmetroTipoLocalObrigatórioDescrição
exportacao_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
exportacao_idintpathsimID 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.

CampoTipoNotas
idintIdentificador da exportação.
id_usuario_createdintUsuário que gerou a exportação.
id_clienteintCliente ao qual a exportação pertence.
data_iniciodateInício do período dos lançamentos exportados.
data_fimdateFim do período dos lançamentos exportados.
data_hora_criacaodatetimeData/hora da criação, normalizada para o fuso America/Sao_Paulo (horário de Brasília).
qtd_lancamentosintQuantidade de lançamentos incluídos na exportação.
nome_arquivo_originalstrNome original do arquivo gerado.
tamanho_bytesintTamanho do arquivo em bytes.
hash_arquivostr | nullHash do arquivo, quando disponível.
vinculo_lancamentosbooltrue 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 de POST /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 no Content-Disposition.
  • A listagem é uma visão compartilhada do escritório - não é restrita ao usuário logado.