Layout CSV — Estoque Diário (Importação)

Documentação do formato de arquivo CSV de estoque diário.

---

1. Características Gerais do Arquivo

Item	Valor
Extensão	.csv
Encoding	UTF-8 (recomendado; o leitor decodifica como UTF-8)
Delimitador	; (ponto e vírgula) — preferencial. Aceita , (vírgula) como fallback se nenhum campo for detectado
Quebra de linha	\r\n ou \n
Cabeçalho	Obrigatório na primeira linha; nomes de colunas case-insensitive
Locale numérico	pt-BR — decimais com vírgula (ex.: 6427,78); milhar opcional com .
Locale de datas	pt-BR — formato dd/MM/yyyy (ex.: 05/12/2025)
Ordem das colunas	Livre — o leitor identifica colunas pelo nome do cabeçalho
Colunas extras	Permitidas — colunas desconhecidas são ignoradas e logadas como "Coluna inesperada"

Importante: Apenas a coluna DATA_REFERENCIA (alias fund_date) é estritamente obrigatória — sua ausência ou valor vazio causa erro no parsing. Todas as demais colunas são opcionais sob a ótica do leitor, mas é fortemente recomendado preencher os identificadores e valores principais (CNPJ do fundo, documentos do cedente/sacado, valores e datas) para que o título seja útil para o negócio.

2. Convenções de Tipos

Tipo	Formato	Exemplo	Vazio aceito?
string	texto livre, trim aplicado	FIDC EXEMPLO I	sim → null
documento (CNPJ/CPF)	string com ou sem pontuação; pontuação é removida automaticamente	00000000000191 ou 00.000.000/0001-91	sim → null
decimal	pt-BR, vírgula como separador decimal	6427,78	sim → null (exceto MORA/MULTA/JUROS que assumem 0)
int	número inteiro	165	sim → null
date	dd/MM/yyyy	05/12/2025	sim → null (exceto DATA_REFERENCIA)

3. Tabela de Colunas

Legenda de obrigatoriedade:

• 🔴 Obrigatório — falha o parsing se vazio
• 🟡 Recomendado — opcional para o leitor, mas necessário para uso de negócio
• ⚪ Opcional — pode ficar em branco

#	Coluna (preferencial)	Aliases aceitos	Tipo	Obrig.	Descrição
1	NM_FUNDO	NOME_FUNDO, fund_name	string	🟡	Nome do fundo (FIDC)
2	NU_CNPJ	DOC_FUNDO, fund_document	documento	🟡	CNPJ do fundo (pontuação é removida)
3	DATA_FUNDO	report_date	date	⚪	Data de referência cadastral do fundo
4	NOME_ORIGINADOR	originator_name	string	🟡	Nome do originador
5	DOC_ORIGINADOR	originator_document	documento	🟡	CNPJ/CPF do originador
6	NOME_CEDENTE	assignor_name	string	🟡	Nome do cedente
7	DOC_CEDENTE	assignor_document	documento	🟡	CNPJ/CPF do cedente
8	NOME_SACADO	borrower_name	string	🟡	Nome do sacado (devedor)
9	DOC_SACADO	borrower_document	documento	🟡	CNPJ/CPF do sacado
10	SEU_NUMERO	external_id	string	🟡	Identificador externo do título (do cliente/originador)
11	NU_DOCUMENTO	contract_number	string	🟡	Número do documento/título
12	TIPO_RECEBIVEL	asset_type	string	🟡	Espécie do recebível (ex.: Duplicata de Servico, Duplicata Mercantil, CCB, NP)
13	VALOR_NOMINAL	face_value	decimal	🟡	Valor de face do título
14	VALOR_PRESENTE	present_value	decimal	🟡	Valor presente (descontado) do título
15	VALOR_AQUISICAO	purchase_value	decimal	🟡	Valor de aquisição na cessão
16	VALOR_PDD	bad_provision_value	decimal	⚪	Provisão para devedores duvidosos
17	FAIXA_PDD	bad_provision_range	string	⚪	Faixa/aging de PDD (ex.: A, B, C)
18	DATA_REFERENCIA	fund_date	date	🔴	Obrigatória — data de corte da posição
19	DATA_VENCIMENTO_ORIGINAL	maturity_date	date	🟡	Vencimento original do título
20	DATA_VENCIMENTO_AJUSTADA	adjusted_maturity_date	date	⚪	Vencimento ajustado (renegociação)
21	DATA_EMISSAO	issue_date	date	🟡	Data de emissão do título
22	DATA_AQUISICAO	purchase_date	date	🟡	Data de aquisição/cessão
23	PRAZO	total_duration	int	⚪	Prazo original em dias
24	PRAZO_ATUAL	present_duration	int	⚪	Prazo atual (dias até vencimento)
25	SITUACAO_RECEBIVEL	—	string	⚪	Ex.: A Vencer, Vencido, Liquidado, Protestado
26	TAXA_CESSAO	—	decimal	⚪	Taxa de cessão (ex.: 0,1799998839)
27	TX_RECEBIVEL	purchase_rate_of_return	decimal	⚪	Taxa do recebível (spread/fee)
28	COOBRIGACAO	—	string	⚪	Indicador de coobrigação (ex.: SIM / NAO)
29	COD_ORIGINADOR	—	string	⚪	Código sistêmico do originador
30	CHAVE_NFE	—	string	⚪	Chave de acesso da NFe vinculada (44 dígitos)
31	NOSSO_NUMERO	DS_NOSSO_NUMERO	string	⚪	Identificador bancário (nosso número)
32	MORA	—	decimal	⚪	Valor de mora (default 0 quando vazio)
33	MULTA	—	decimal	⚪	Valor de multa (default 0 quando vazio)
34	JUROS	—	decimal	⚪	Valor de juros (default 0 quando vazio)

4. Regras de Validação e Parsing

4.1 Strings

• Espaços em branco no início/fim são trimados.
• Strings vazias são convertidas para null.

4.2 Documentos (CNPJ/CPF)

• Pontuação (., /, -) é removida automaticamente.
• Aceita ambos os formatos: 00.000.000/0001-91 e 00000000000191.
• O leitor não valida dígito verificador; o cliente deve garantir documentos válidos na origem.

4.3 Decimais

• Use vírgula como separador decimal: 6427,78 ✅ — 6427.78 ❌.
• Negativos são aceitos: -100,50.
• Valor vazio → null (exceto MORA, MULTA e JUROS, que assumem 0).
• Valor inválido (ex.: abc) → erro de parsing: Não é possível converter {Campo} com valor '{valor}'.

4.4 Datas

• Formato esperado: dd/MM/yyyy (cultura pt-BR).
• DATA_REFERENCIA (fund_date) é a única obrigatória: vazio ou inválido causa erro.
• Demais datas: vazio → null; inválido (ex.: 2025-12-05) → erro de parsing.

4.5 Inteiros

• Apenas dígitos. Vazio → null. Inválido → erro de parsing.

4.6 Cabeçalhos

• Comparação case-insensitive (NM_FUNDO = nm_fundo = Nm_Fundo).
• Colunas não reconhecidas são ignoradas e logadas (não bloqueiam o processamento).
• A primeira linha do arquivo é sempre tratada como cabeçalho.

5. Exemplo de Arquivo

Os CNPJs e nomes abaixo são fictícios, apenas para fins de demonstração de formato. Substitua pelos dados reais ao gerar o arquivo de produção.

Cabeçalho (todas as colunas)

NM_FUNDO;NU_CNPJ;DATA_FUNDO;NOME_ORIGINADOR;DOC_ORIGINADOR;NOME_CEDENTE;DOC_CEDENTE;NOME_SACADO;DOC_SACADO;SEU_NUMERO;NU_DOCUMENTO;TIPO_RECEBIVEL;VALOR_NOMINAL;VALOR_PRESENTE;VALOR_AQUISICAO;VALOR_PDD;FAIXA_PDD;DATA_REFERENCIA;DATA_VENCIMENTO_ORIGINAL;DATA_VENCIMENTO_AJUSTADA;DATA_EMISSAO;DATA_AQUISICAO;PRAZO;PRAZO_ATUAL;SITUACAO_RECEBIVEL;TAXA_CESSAO;TX_RECEBIVEL;COOBRIGACAO;COD_ORIGINADOR;CHAVE_NFE;NOSSO_NUMERO

Linhas de exemplo

FIDC EXEMPLO I;00000000000191;05/12/2025;ORIGINADORA EXEMPLO LTDA;11111111000111;CEDENTE EXEMPLO LTDA;22222222000122;SACADO EXEMPLO LTDA;33333333000133;000000000001;0000000001;Duplicata de Servico;6427,78;6415,13;5767,60;0,00;A;04/12/2025;09/12/2025;09/12/2025;15/04/2025;15/04/2025;165;3;A Vencer;0,1799998839;0,1800011238;NAO;CLI0001;00000000000000000000000000000000000000000001;000000000001
FIDC EXEMPLO I;00000000000191;05/12/2025;ORIGINADORA EXEMPLO LTDA;11111111000111;CEDENTE EXEMPLO LTDA;22222222000122;SACADO EXEMPLO LTDA;33333333000133;000000000002;0000000002;Duplicata de Servico;3970,43;3962,61;3562,64;0,00;A;04/12/2025;09/12/2025;09/12/2025;15/04/2025;15/04/2025;165;3;A Vencer;0,1799998839;0,1800000164;NAO;CLI0001;00000000000000000000000000000000000000000002;000000000002

Exemplo mínimo (apenas colunas recomendadas)

NU_CNPJ;DOC_CEDENTE;DOC_SACADO;NU_DOCUMENTO;TIPO_RECEBIVEL;VALOR_NOMINAL;VALOR_PRESENTE;VALOR_AQUISICAO;DATA_REFERENCIA;DATA_VENCIMENTO_ORIGINAL;DATA_EMISSAO
00000000000191;22222222000122;33333333000133;0000000001;Duplicata de Servico;6427,78;6415,13;5767,60;04/12/2025;09/12/2025;15/04/2025

6. Erros Comuns e Como Evitar

Sintoma	Causa	Correção
Arquivo não é um CSV válido	Cabeçalho ausente ou delimitador diferente de ; e ,	Garantir 1ª linha de cabeçalho com ; como separador
Não é possível converter DataReferencia com valor ''	DATA_REFERENCIA vazia	Preencher DATA_REFERENCIA (obrigatória) em todas as linhas
Não é possível converter ValorNominal com valor '6427.78'	Decimal com . em vez de ,	Usar pt-BR: 6427,78
Não é possível converter DataVencimentoOriginal com valor '2025-12-09'	Data em formato ISO	Usar dd/MM/yyyy: 09/12/2025
Coluna ignorada silenciosamente	Nome de cabeçalho fora da lista de aceitos/aliases	Renomear coluna para o nome preferencial da tabela
Caracteres acentuados quebrados	Encoding diferente de UTF-8 (ex.: ANSI/Latin1)	Salvar arquivo como UTF-8
Documento com formato inválido após import	Dígito verificador errado	Validar CNPJ/CPF na origem antes de gerar o CSV