---
title: Layout CSV — Estoque Diário (Importação)
url: https://docs.vehub.com.br/Layouts/%F0%9F%92%B3%20Estoque/Manual/
---
# 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)

```csv
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

```csv
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)

```csv
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 |