Layout XLSX Fly5¶

Estrutura do Arquivo¶

Planilha XLSX (Excel) de entrada da Fly5. O arquivo de referência tem o cabeçalho na linha 1, uma linha por título e um totalizador no rodapé.

As colunas são localizadas pelo nome do cabeçalho, não pela posição física: a planilha tem colunas auxiliares de pivot no fim (Mês Venc., Semana Venc., Mês Baixa) e as colunas de CEP e espécie foram acrescentadas depois das originais, então a ordem varia entre arquivos.

A comparação do nome do cabeçalho é insensível a caixa (VALOR FACE = Valor Face), mas sensível a acento — Emissão, Deságio e Espécie precisam vir acentuados.

Somente a primeira planilha da pasta de trabalho é lida.

Localização do cabeçalho¶

O leitor varre as 10 primeiras linhas procurando uma célula com o texto CNPJ Sacado; a linha em que a encontra é o cabeçalho. A folga permite que a planilha tenha um título ou um logo acima da tabela. Se CNPJ Sacado não aparecer nessas 10 linhas, o arquivo é rejeitado.

Fim da leitura¶

Condição	Comportamento
Linha com o texto `TOTAL` em qualquer coluna mapeada	Parada esperada (totalizador do rodapé). Sem aviso
Linha sem `CNPJ Sacado`, sem `NF` e sem `Vencimento`	Parada. As linhas seguintes são ignoradas e um alerta registra o corte no log do job
Última linha utilizada da planilha	Fim normal da leitura

Por que o critério é o texto TOTAL

A linha de totalizador traz as somas de Valor Face, Valor Desembolsado e Deságio preenchidas, então não é possível pará-la por "linha vazia" ou "linha sem valor".

Colunas¶

As letras abaixo são a posição no arquivo de referência, apenas para conferência visual — a leitura é sempre pelo nome do cabeçalho.

Coluna	Cabeçalho	Tipo	Uso	Descrição
A	`#`	Inteiro	Ignorada	Numeração sequencial da linha
B	`Cedente`	Texto	Opcional	Razão social do cedente. O cedente é resolvido pelo CNPJ
C	`CNPJ Cedente`	Texto	Obrigatória	CNPJ do cedente. Deve ser o mesmo em todas as linhas
D	`Sacado`	Texto	Obrigatória	Nome ou razão social do sacado
E	`CNPJ Sacado`	Texto	Obrigatória	CPF ou CNPJ do sacado. É também a coluna usada para localizar a linha do cabeçalho
F	`CEP Sacado`	Texto / Inteiro	Obrigatória	CEP do sacado
G	`NF`	Texto / Inteiro	Obrigatória	Número da nota fiscal, que é o número do documento do título
H	`Emissão`	Data	Obrigatória	Data de emissão do título
I	`Desembolso`	Data	Obrigatória	Data do desembolso ao cedente, usada como data de aquisição
J	`Vencimento`	Data	Obrigatória	Data de vencimento do título
K	`Baixa`	Data	Conferência	Data da baixa na origem. Gera alerta e não é importada
L	`Valor Face`	Decimal	Obrigatória	Valor nominal do título
M	`Valor Desembolsado`	Decimal	Obrigatória	Valor pago ao cedente, usado como valor de aquisição
N	`Deságio`	Decimal	Conferência	Deságio informado pela planilha. Não é importado
O	`Dias Corr.`	Inteiro	Ignorada	Prazo em dias, derivado das datas
P	`Taxa a.m.`	Decimal	Conferência	Taxa mensal como fração (`0,0315` = 3,15% a.m.). Não é importada
Q	`Status`	Texto	Ignorada	Situação derivada da baixa. Chega como `#REF!` na maioria das linhas do arquivo real
R	`Mês Desemb.`	Texto	Ignorada	Auxiliar de pivot (ex.: `2026-06`)
S	`Mês Venc.`	Texto	Ignorada	Auxiliar de pivot (ex.: `2026-07`)
T	`Semana Venc.`	Texto	Ignorada	Auxiliar de pivot (ex.: `2026-07-S4`)
U	`Mês Baixa`	Texto	Ignorada	Auxiliar de pivot (ex.: `2026-07`)
V	`Espécie`	Texto	Obrigatória	Espécie do título

Legenda de uso

Uso	Significado
Obrigatória	A coluna precisa existir no arquivo. Sem ela o arquivo é rejeitado e a mensagem lista as colunas ausentes
Opcional	Lida quando presente; o arquivo é aceito sem ela
Conferência	Lida, mas não gravada — alimenta apenas os alertas de consistência no log do job
Ignorada	Não é lida. É derivada de outras colunas dentro da própria planilha

Espécies de Título¶

A coluna Espécie aceita a sigla da tabela abaixo, ou a descrição da espécie (ex.: Nota Fiscal Serviço). A comparação ignora acento e caixa.

Sigla	Espécie no VHub
`DM`	Duplicata Mercantil
`UR`	Unidade de Recebível
`NFSE`	Nota Fiscal Serviço
`ND`	Nota de Débito
`CCB`	CCB Pré Digital
`NP`	Nota Promissória
`NC`	Nota Comercial
`CT`	Contrato
`NF`	Nota Fiscal
`CPR`	Cédula de Produto Rural
`CTE`	CT-e
`CD`	Confissão de Dívida

A sigla AD (Assunção de Dívida) também é reconhecida, porque as siglas aceitas são derivadas do próprio enumerador de espécies do VHub.

De/Para com o VHub¶

Campos vindos do arquivo

Coluna do arquivo	Campo no VHub
`Cedente`	`Empresa.Nome` (cedente)
`CNPJ Cedente`	`Empresa.Cnpj` (cedente)
`Sacado`	`Sacado.Nome`
`CNPJ Sacado`	`Sacado.CpfCnpj` e `Sacado.TipoPessoa`
`CEP Sacado`	`Sacado.Cep`
`NF`	`Titulo.NumeroDocumento`
`Emissão`	`Titulo.DataEmissao`
`Desembolso`	`Titulo.DataAquisicao`
`Vencimento`	`Titulo.DataVencimento`
`Valor Face`	`Titulo.ValorNominal`
`Valor Desembolsado`	`Titulo.ValorAquisicao`
`Espécie`	`Titulo.Especie`

Campos definidos pelo layout (não vêm do arquivo)

Campo no VHub	Valor
`Titulo.Portador`	`Cedente`
`Titulo.LayoutIntegracaoEntrada`	`Xlsx Fly5` (53)
`Titulo.DisponivelParaMovimentacao`	`true`
`Titulo.OriginadoViaEstoqueDtvm`	`false`

Regras de Conversão¶

Campo	Regra
`CNPJ Cedente`, `CNPJ Sacado`	Mantém somente os dígitos. Qualquer caractere não numérico é removido, inclusive vírgula — `48.851,242/0001-15` vira `48851242000115`
`CEP Sacado`	Somente dígitos, completado com zeros à esquerda até 8 posições. Célula formatada como número perde o zero inicial (`01310100` chega `1310100`) e ele é restaurado
`NF`	Célula numérica é convertida para a forma inteira, sem notação científica
`Emissão`, `Desembolso`, `Vencimento`, `Baixa`	Aceita serial do Excel (número), célula de data e texto em pt-BR (`DD/MM/AAAA`)
`Valor Face`, `Valor Desembolsado`, `Deságio`	Arredondados para 2 casas decimais. Aceita formato invariant (`1234.56`) e pt-BR (`1.234,56`)
`Taxa a.m.`	Não é arredondada em 2 casas: chega como fração e `0,0315` seria zerado para `0,03`
`Espécie`	Só os espaços das pontas são removidos. A resolução da sigla acontece na etapa de mapeamento
Tipo de pessoa do sacado	Documento com até 11 dígitos → Pessoa Física; acima disso → Pessoa Jurídica

Validações¶

Todas as validações abaixo rodam antes da gravação. A gravação é feita em transação única, então qualquer falha rejeita o arquivo inteiro.

Validação	Critério
Cabeçalho encontrado	`CNPJ Sacado` precisa aparecer nas 10 primeiras linhas
Colunas obrigatórias	Todas as colunas obrigatórias precisam existir. A mensagem lista as ausentes
Linha legível	Uma linha que não pode ser lida rejeita o arquivo. A mensagem informa o número da linha
Pelo menos um título	Arquivo sem nenhuma linha de título é rejeitado
Documento do sacado	Precisa ter 11 (CPF) ou 14 (CNPJ) dígitos. A mensagem lista as linhas inválidas
CEP do sacado	Precisa ter 8 dígitos. A mensagem lista as linhas inválidas
Espécie reconhecida	A sigla precisa constar na tabela de espécies. A mensagem lista as linhas e as siglas aceitas
Cedente único	O arquivo precisa ter exatamente um `CNPJ Cedente`. Com mais de um, envie um arquivo por cedente

Alertas¶

Registrados no log do job. Não impedem a importação.

Alerta	Quando ocorre
Títulos já liquidados na origem	Linhas com `Baixa` preenchida. A baixa não é importada e os títulos entram como a vencer
Desembolso posterior ao vencimento	`Desembolso` maior que `Vencimento` na mesma linha
Deságio não fecha	`Valor Face - Valor Desembolsado - Deságio` acima de R$ 0,01. A diferença normalmente é tarifa/TAC
Leitura interrompida	Parada em linha em branco no meio da tabela. O alerta informa a linha do corte e a faixa de linhas ignoradas

Campos Não Importados¶

Campo do título	Motivo
`DataLiquidacao`	A coluna `Baixa` não vem acompanhada de valor pago nem de conciliação. Gravar a liquidação criaria um título liquidado entrando em lote de cessão
`TaxaDesagio`	Recalculada pelo lote a partir do valor de aquisição
`NossoNumero`	Não existe no arquivo
Chave da NF-e / lastro	O arquivo traz apenas o número da NF
Endereço do sacado (logradouro, número, bairro, cidade, UF)	O arquivo traz apenas nome, documento e CEP
Descontos, encargos e valores de conciliação	Não existem no arquivo

Exemplo¶

Cabeçalho e uma linha de dados (representação em pares coluna → valor):

Cabeçalho	Valor
`#`	`1`
`Cedente`	`INDUSTRIA MODELO DE SINALIZACAO LTDA`
`CNPJ Cedente`	`12.345.678/0001-90`
`Sacado`	`COMERCIO SILVA E SOUZA LTDA`
`CNPJ Sacado`	`98.765.432/0001-10`
`CEP Sacado`	`01310-100`
`NF`	`10459`
`Emissão`	`25/05/2026`
`Desembolso`	`26/06/2026`
`Vencimento`	`20/07/2026`
`Baixa`	(vazio)
`Valor Face`	`1.333,34`
`Valor Desembolsado`	`1.298,36`
`Deságio`	`34,98`
`Dias Corr.`	`24`
`Taxa a.m.`	`0,0315`
`Status`	`Liquidado`
`Mês Desemb.`	`2026-06`
`Mês Venc.`	`2026-07`
`Semana Venc.`	`2026-07-S3`
`Mês Baixa`	(vazio)
`Espécie`	`DM`

E o rodapé do arquivo, que encerra a leitura:

Cabeçalho	Valor
`Baixa`	`TOTAL`
`Valor Face`	`180.096,78`
`Valor Desembolsado`	`166.522,27`
`Deságio`	`13.574,51`