Layout do CSV de importação de vendas do eNotas

TLDR: O eNotas importa notas a partir de um CSV de 50 colunas fixas separadas por ;. /admin/taxes/export gera esse arquivo com uma linha por sessão faturável, preenchendo 14 colunas e deixando as outras 36 vazias.

Especificação do arquivo

Item Valor
Formato CSV (texto)
Separador de colunas ;
Codificação UTF-8
Linha de cabeçalho Obrigatória, com os 50 nomes na ordem exata
Registros 1 linha por venda/nota
Total de colunas 50
Formato de data DD/MM/AAAA
Separador decimal ponto (12.00) — nunca vírgula
Booleanos SIM / NAO
Tipo de pessoa PF / PJ

Regras de conteúdo que quebram o parsing se violadas:

  • Nenhum ; dentro do conteúdo de um campo — é o separador de colunas
  • Toda linha mantém os 50 delimitadores, mesmo com colunas vazias
  • Cada campo respeita seu limite de tamanho

Colunas preenchidas pelo export

ProfessionalPaymentInvoices::BuildEnotasCsv monta a linha a partir de TaxInvoiceSerializer, na perspectiva do terapeuta (o tomador da nota) — o valor é a taxa retida pela plataforma, não o valor cheio da sessão.

# Coluna Origem Máx.
1 ChaveUnica meeting.id 1000
2 Cliente_NomeRazaoSocial nome do terapeuta 115
4 Cliente_Documento CPF do terapeuta, só dígitos 14
5 Cliente_Email e-mail do terapeuta 80
6 Cliente_EnderecoCidade address.district —
7 Cliente_EnderecoUF address.region_name normalizado para 2 letras 2
8 Cliente_EnderecoCEP address.postcode, 8 dígitos 8
9 Cliente_Endereco address.street 125
10 Cliente_EnderecoNumero address.number 10
12 Cliente_EnderecoBairro address.neighborhood 30
13 Cliente_EnderecoPais "Brasil" quando country_code é BR, senão address.country —
18 Produto_Nome constante "ATENDIMENTO TERAPEUTICO" 255
21 Venda_ValorTotal taxa retida (CalculateFee, 10% do total do repasse), formato 0.00 —
22 Venda_Data order.updated_at em DD/MM/AAAA —

Colunas deixadas vazias

As 36 restantes saem vazias, mas presentes: Cliente_NomeFantasia, Cliente_EnderecoComplemento, Cliente_Telefone, Cliente_TipoPessoa, Cliente_InscricaoMunicipal, Cliente_InscricaoEstadual, Produto_IDExterno, Produto_ValorTotal, Venda_MeioPagamento, Venda_DataVencimento e toda a família NFe_*.

NFe_CNAE e NFe_CodigoServicoMunicipio são opcionais no CSV porque já estão configurados no cadastro da empresa no eNotas (Empresa > Dados municipais). Se essa configuração sair de lá, as duas colunas passam a ser obrigatórias no arquivo.

Normalizações aplicadas

  • UF — aceita tanto a sigla ("SP") quanto o nome por extenso com acento ("São Paulo"), resolvendo ambos para a sigla via STATE_ABBREVIATIONS, com remoção de acentos
  • CEP — só dígitos, preenchido com zeros à esquerda até 8; "00000000" é tratado como ausente
  • ; no conteúdo — substituído por espaço, e espaços em branco consecutivos são colapsados
  • Truncamento — cada valor é cortado no limite da sua coluna (MAX_LENGTHS), sem reticências. Acontece só no CSV: a tela /admin/taxes continua mostrando o valor inteiro

Quais sessões entram

Os critérios de elegibilidade vivem em ProfessionalPaymentInvoices::TaxSummaryQuery: sessão finished, pedido com pagamento paid, payment_method diferente de free e professional_payment_invoice_meetings.total maior que zero. O filtro de período (start_period/end_period, em MM/AAAA) é aplicado sobre orders.updated_at.

O fluxo de repasse que origina esses valores está em invoice_payment_flow.

Checklist antes de importar

  • [ ] Cabeçalho com as 50 colunas na ordem
  • [ ] Separador ; e codificação UTF-8
  • [ ] Campos obrigatórios preenchidos em cada linha (2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 18, 21, 22)
  • [ ] Datas em DD/MM/AAAA e valores com ponto decimal
  • [ ] Nenhum ; dentro de campo
  • [ ] ChaveUnica única por linha, para reimportar sem duplicar