Exportações (exports e export-templates)

Rotas base v5/exports e v5/export-templates, disponíveis no Admin e no Console.

A exportação gera uma planilha com os registros de uma listagem (empréstimos, agentes, usuários, cobranças, consultas etc.) exatamente como o usuário filtrou na tela. O pedido não é processado na hora: ele entra em uma fila, um serviço em segundo plano gera o arquivo, compacta em .zip, guarda no armazenamento da empresa e deixa o download disponível na lista Minhas Exportações até o fim do prazo configurado.

As colunas e a ordem delas vêm de um modelo de exportação, cadastrado pelo usuário para cada funcionalidade.

Somente pelo front

Os endpoints de exportação são do front (sessão de usuário). Usuários de API não têm acesso.

Fluxo

1. O usuário escolhe ou cadastra um modelo para a funcionalidade (por exemplo, "Empréstimos — financeiro").
2. Na listagem, aplica os filtros e o texto de busca de sempre e pede a exportação, escolhendo o modelo, o formato (Excel por padrão, ou CSV) e, se quiser, o nome do arquivo.
3. O pedido é validado e entra na fila como Pendente. A resposta já traz a quantidade de registros que serão exportados.
4. O serviço de exportação pega o pedido e refaz a mesma consulta da tela, com as permissões do usuário que pediu, para saber quais registros entram. Depois lê esses registros em lotes de até mil, buscando no banco só as colunas do modelo, e escreve a planilha aos poucos, para não sobrecarregar o banco. Alguns campos são montados pelo sistema e não existem como coluna (por exemplo, os dados do tomador do empréstimo e do pagador da cobrança); quando o modelo usa algum deles, esse lote também lê o registro completo.
5. Ao terminar, o arquivo é compactado, enviado ao armazenamento e o pedido fica Concluído, com o link de download.
6. Quando o prazo de disponibilidade termina, o pedido some da lista e o arquivo é apagado do armazenamento.

O filtro da exportação

O pedido leva os mesmos campos de filtro (filters), o mesmo texto de busca (searchText) e a mesma ordenação da listagem. O retrato do filtro e das colunas é gravado no pedido: alterar o filtro da tela ou o modelo depois não muda uma exportação que já está na fila.

A consulta respeita o nível de acesso do usuário que pediu (unidade, parceiro, agência, agente, grupos). Se o usuário perder a permissão de consultar a funcionalidade antes do processamento, o pedido falha.

Configurações

Em Configurações › Sistema › Exportação, por empresa:

Configuração	Padrão	Uso
Exportações simultâneas por usuário e funcionalidade	2	Quantos pedidos de uma mesma funcionalidade cada usuário pode ter pendentes ou em processamento. Acima disso o pedido é recusado (1089010).
Máximo de registros por exportação	100000	Pedidos cujo filtro passa desse total são recusados (1089011). O limite é conferido no pedido e de novo no processamento.
Disponibilidade do arquivo exportado (horas)	72	Tempo em que o pedido aparece na lista e o arquivo pode ser baixado. Vale também para pedidos com falha ou cancelados.

Permissões

Recurso	Permissão	Endpoints
Exportação	Acessar	GET /v5/exports/{id}, POST /v5/exports/search, GET /v5/exports/{id}/download, DELETE /v5/exports/{id}
Exportação	Exportar	POST /v5/exports, POST /v5/exports/{id}/cancel
Modelo de Exportação	Acessar	GET /v5/export-templates/{id}, POST /v5/export-templates/search, GET /v5/export-templates/features/{feature}
Modelo de Exportação	Cadastrar, Editar, Excluir	POST, PUT, DELETE de /v5/export-templates
Modelo de Exportação	Gerenciar Modelos da Empresa	Criar ou alterar modelos com visibilidade "Toda a empresa".

Além disso, para exportar uma funcionalidade o usuário precisa ter a permissão Acessar dela (por exemplo, Acessar Empréstimos para exportar empréstimos).

Rotas implementadas

Rota	Verbo	Resumo
/v5/exports/features	GET	Funcionalidades que o usuário pode exportar.
/v5/exports/features/{feature}	GET	Catálogo de colunas disponíveis de uma funcionalidade.
/v5/exports	POST	Pede uma exportação (entra na fila).
/v5/exports/search	POST	Minhas exportações ainda disponíveis.
/v5/exports/{id}	GET	Detalhe do pedido, com progresso.
/v5/exports/{id}/cancel	POST	Cancela um pedido pendente, reagendado ou em processamento.
/v5/exports/{id}/download	GET	Gera um link de download novo para o arquivo.
/v5/exports/{id}	DELETE	Remove da lista um pedido já finalizado e apaga o arquivo.
/v5/exports/filters	GET	Campos de filtro da lista de exportações.
/v5/export-supports	GET	Status, formatos e configurações em vigor.
/v5/export-templates	POST	Cadastra um modelo.
/v5/export-templates/{id}	GET, PUT, DELETE	Busca, altera ou exclui um modelo.
/v5/export-templates/features/{feature}	GET	Modelos ativos que o usuário pode usar na funcionalidade, o padrão primeiro.
/v5/export-templates/search	POST	Busca paginada de modelos.
/v5/export-templates/filters	GET	Campos de filtro da lista de modelos.
/v5/export-template-supports	GET	Funcionalidades exportáveis com seus catálogos, visibilidades e status.

Modelo de exportação

Campo	Descrição
name	Nome do modelo. Único por funcionalidade entre os modelos que o usuário enxerga.
description	Texto livre.
feature	Funcionalidade exportada (key de Feature). Não muda depois do cadastro.
visibility	private (só quem criou vê e usa) ou company (toda a empresa vê e usa).
isDefault	Modelo sugerido ao exportar. Marcar um modelo como padrão desmarca o anterior do mesmo escopo.
status	active ou inactive. Só modelos ativos aparecem na exportação.
columns	Lista ordenada de colunas. Cada item tem a key do catálogo da funcionalidade e, opcionalmente, um label próprio; sem label, a planilha usa o rótulo padrão do catálogo.

Só quem criou um modelo privado pode alterá-lo. Modelos da empresa podem ser alterados por quem tem a permissão de gerenciar modelos da empresa.

Se uma coluna deixar de existir no catálogo, ela é ignorada na exportação e aparece no modelo com available = false.

Pedido de exportação

Corpo do POST /v5/exports:

Campo	Descrição
feature	Funcionalidade da listagem.
templateId	Modelo usado. Precisa ser da mesma funcionalidade, estar ativo e visível ao usuário.
format	xlsx (padrão) ou csv.
fileName	Nome do arquivo, sem extensão. Sem ele, o nome é a funcionalidade com a data e hora do pedido.
filters	Campos de filtro da listagem, no mesmo formato enviado ao search da funcionalidade.
searchText	Texto de busca da listagem.
sort	Ordenação da listagem, quando houver.

Principais campos devolvidos:

Campo	Descrição
status	Situação do pedido (ver Domínios › Exportações).
totalRecords / processedRecords	Total de registros do filtro e quantos já foram escritos. Servem para mostrar o progresso.
columns	Retrato das colunas usadas.
filters / filterSearchText	Retrato do filtro usado.
lastError	Motivo da última falha.
attemptCount	Tentativas de processamento. Falhas temporárias são reprocessadas automaticamente algumas vezes antes de o pedido ficar com falha.
completedAt	Fim do processamento (conclusão, falha ou cancelamento).
expiresAt	Até quando o pedido aparece na lista e o arquivo pode ser baixado.
file / fileSizeBytes	Arquivo .zip gerado e seu tamanho.
downloadUrl / downloadUrlExpiresAt	Link gerado na conclusão, válido por poucos minutos. Para baixar depois, use GET /v5/exports/{id}/download, que sempre gera um link novo.
isAvailable	Indica se o arquivo pode ser baixado agora.

Arquivo gerado

• Um .zip com um único arquivo dentro, .xlsx ou .csv, com o nome do pedido.
• No Excel: a primeira linha traz os rótulos das colunas em negrito, fica congelada e já vem com filtro. Números, valores em reais, percentuais, datas e datas com hora são gravados como valores do Excel, com formatação brasileira. Datas com hora ficam no fuso horário do usuário.
• No CSV: separador ponto e vírgula, codificação UTF-8 com BOM (abre direto no Excel em português), números com vírgula decimal e datas no formato dia/mês/ano.
• O arquivo é guardado no armazenamento da empresa, na pasta Sistema › Exportação.

Erros

Código	Situação
1089002	A funcionalidade não está disponível para exportação.
1089003	O usuário não tem permissão para consultar a funcionalidade.
1089004 a 1089008	Modelo não informado, não encontrado, de outra funcionalidade, inativo ou sem colunas válidas.
1089009	Formato inválido.
1089010	Limite de exportações simultâneas atingido.
1089011	O filtro passa do máximo de registros por exportação.
1089012	O filtro não retorna registros.
1089013	O pedido não pode mais ser cancelado.
1089014 / 1089015	O arquivo não está disponível ou o prazo para baixar terminou.
1089016	Não é possível excluir um pedido ainda em andamento.
108901001 a 108901014	Validações do modelo de exportação (nome, funcionalidade, colunas, visibilidade e permissão).

Processamento em segundo plano

Dois serviços do Semear.Tools.Jobs cuidam da fila:

Job	O que faz
export_request	Pega os pedidos pendentes ou reagendados, gera os arquivos e conclui os pedidos. Parâmetros: pedidos por rodada, pedidos em paralelo, registros por consulta (até mil) e tempo máximo de trava. Um pedido travado por um processo que caiu volta para a fila depois do tempo de trava.
export_cleanup	Expira os pedidos cujo prazo terminou e apaga os arquivos do armazenamento.