Emissão em lote por CSV

Use o lote quando várias notas já estiverem organizadas em planilha; use a emissão avulsa para preencher e revisar uma nota na tela. Para cobranças repetidas em calendário, prefira a emissão recorrente.

Prepare o arquivo CSV

1. Em 1. Baixe o modelo, clique em Baixar modelo CSV e mantenha uma nota por linha.

2. Salve o arquivo em UTF-8 ou Windows-1252. A leitura aceita ponto e vírgula, vírgula ou tabulação como separador e números como 1.500,00 ou 1500.00.

3. Limite o arquivo a 2 MB e a 50 notas na tela. Na API v1, até 5 linhas podem ser processadas de modo síncrono; acima disso, o envio deve ser assíncrono, que coloca as linhas válidas na fila e aceita até 500 itens.

4. Preencha as colunas conforme o dicionário completo:

Nome exato da coluna	Obrigatória?	O que preencher	Exemplo curto
empresaId	Não	ID da emissora; necessário se houver mais de uma ativa	7
perfilTributarioId	Não	ID inteiro positivo de um perfil ativo da mesma emissora	21
clienteId	Não	ID de cliente salvo	45
tomadorTipo	Sim	CNPJ, CPF ou ESTRANGEIRO	CNPJ
tomadorDoc	Sim	Documento do tomador	12345678000190
tomadorNome	Sim	Nome ou razão social	Cliente Exemplo
tomadorEmail	Sim	E-mail fiscal	fiscal@exemplo.com
tomadorTelefone	Não	Telefone do tomador	11999999999
tomadorCep	Não	CEP sem formatação	01310100
tomadorLogradouro	Não	Logradouro	Av. Paulista
tomadorNumero	Não	Número	1000
tomadorComplemento	Não	Complemento	Sala 10
tomadorBairro	Não	Bairro	Bela Vista
tomadorMunIBGE	Não	Código IBGE do município	3550308
tomadorCidade	Não	Cidade, especialmente no endereço estrangeiro	Lisboa
tomadorUF	Não	Sigla da UF	SP
tomadorNIF	Não	NIF estrangeiro	PT123456789
tomadorCNaoNIF	Não	Motivo de ausência do NIF: 0, 1 ou 2	0
tomadorPaisISO	Não	País ISO com duas letras; obrigatório para estrangeiro	PT
tomadorCodPostalExt	Não	Código postal estrangeiro	1000-001
tomadorEstProvRegiao	Não	Estado, província ou região	Lisboa
descricaoServico	Sim	Descrição da prestação	Consultoria mensal
codigoTribNac	Sim	Código de tributação nacional	010101
codigoTribMun	Sim	Código de serviço municipal	0101
locPrestacaoIBGE	Não	Código IBGE do local da prestação	3550308
dataCompetencia	Sim	Competência em AAAA-MM	2026-08
observacoes	Não	Observações da DPS	Contrato 10
valorServico	Sim	Valor maior que zero	1500,00
valorDesconto	Não	Desconto incondicionado, zero ou positivo	100,00
valorDescontoCondicionado	Não	Desconto condicionado, zero ou positivo	50,00
deducaoBaseISS	Não	Dedução da base, zero ou positiva	200,00
aliquotaISSQN	Não	Percentual do ISS, zero ou positivo	5,00
tpRetISSQN	Não	1, 2 ou 3, conforme a opção fiscal aplicável	1
intermediarioPresente	Não	true/false, 1/0 ou sim/não	false
intermediarioTipo	Não	CNPJ, CPF ou ESTRANGEIRO; exigido se presente	CNPJ
intermediarioDoc	Não	Documento; exigido se presente	11222333000144
intermediarioNome	Não	Nome; exigido se presente	Intermediadora Ltda
intermediarioEmail	Não	E-mail do intermediário	contato@inter.com
intermediarioCep	Não	CEP sem formatação	20040002
intermediarioLogradouro	Não	Logradouro	Rua da Assembleia
intermediarioNumero	Não	Número	10
intermediarioComplemento	Não	Complemento	5º andar
intermediarioBairro	Não	Bairro	Centro
intermediarioMunIBGE	Não	Código IBGE do município	3304557
intermediarioCidade	Não	Cidade estrangeira	Madrid
intermediarioUF	Não	Sigla da UF	RJ
intermediarioNIF	Não	NIF estrangeiro	ES12345678
intermediarioCNaoNIF	Não	Motivo de ausência do NIF: 0, 1 ou 2	0
intermediarioPaisISO	Não	País ISO com duas letras; obrigatório para estrangeiro	ES
intermediarioCodPostalExt	Não	Código postal estrangeiro	28001
intermediarioEstProvRegiao	Não	Estado, província ou região	Madrid
nomeCobranca	Não	Nome da cobrança ou serviço usado no e-mail	Mensalidade agosto
emailPara	Sim	Um ou mais destinatários separados por vírgula	financeiro@exemplo.com
emailCopia	Não	Destinatários em cópia, separados por vírgula	gestor@exemplo.com
emailAssunto	Não	Assunto personalizado	NFS-e de agosto
emailCorpo	Não	Corpo do e-mail	Segue a NFS-e.
emailUsaVariaveis	Não	Se o corpo resolve variáveis: true ou false	true
gerarBoleto	Não	Se deve gerar boleto: true ou false	false
boletoDiasVencimento	Não	Inteiro entre 1 e 180	10
boletoPercentualMulta	Não	Percentual entre 0 e 100	2,00
boletoPercentualJuros	Não	Percentual entre 0 e 100	1,00

Confirme códigos, alíquota, retenção, dedução e demais parâmetros fiscais com o contador antes de enviar o lote.

Confira uma linha completa

O cabeçalho precisa conter todas as colunas obrigatórias; as opcionais podem permanecer vazias. Este exemplo usa o cabeçalho completo do modelo e uma linha:

empresaId;perfilTributarioId;clienteId;tomadorTipo;tomadorDoc;tomadorNome;tomadorEmail;tomadorTelefone;tomadorCep;tomadorLogradouro;tomadorNumero;tomadorComplemento;tomadorBairro;tomadorMunIBGE;tomadorCidade;tomadorUF;tomadorNIF;tomadorCNaoNIF;tomadorPaisISO;tomadorCodPostalExt;tomadorEstProvRegiao;descricaoServico;codigoTribNac;codigoTribMun;locPrestacaoIBGE;dataCompetencia;observacoes;valorServico;valorDesconto;valorDescontoCondicionado;deducaoBaseISS;aliquotaISSQN;tpRetISSQN;intermediarioPresente;intermediarioTipo;intermediarioDoc;intermediarioNome;intermediarioEmail;intermediarioCep;intermediarioLogradouro;intermediarioNumero;intermediarioComplemento;intermediarioBairro;intermediarioMunIBGE;intermediarioCidade;intermediarioUF;intermediarioNIF;intermediarioCNaoNIF;intermediarioPaisISO;intermediarioCodPostalExt;intermediarioEstProvRegiao;nomeCobranca;emailPara;emailCopia;emailAssunto;emailCorpo;emailUsaVariaveis;gerarBoleto;boletoDiasVencimento;boletoPercentualMulta;boletoPercentualJuros
7;21;45;CNPJ;12345678000190;Cliente Exemplo;fiscal@exemplo.com;11999999999;01310100;Av. Paulista;1000;Sala 10;Bela Vista;3550308;São Paulo;SP;;0;;; ;Consultoria mensal;010101;0101;3550308;2026-08;Contrato 10;1500,00;100,00;50,00;0;5,00;1;false;;;;;;;;;;;;;;;;;;Mensalidade agosto;financeiro@exemplo.com;gestor@exemplo.com;NFS-e de agosto;Segue a NFS-e.;true;false;;;

Selecione e envie o arquivo

1. Em 2. Envie o arquivo, escolha o arquivo em Arquivo CSV. Como alternativa, cole todo o conteúdo em Ou cole o CSV.

2. Clique em Emitir lote. Durante o envio, a tela mostra Enviando lote... e Enviando o lote para a fila....

3. Em Lote enviado, confira Total, Enfileiradas e Inválidas. Cada item em Linhas que não entraram na fila informa o número da linha e a validação encontrada.

4. Corrija somente as linhas inválidas, monte um novo CSV com o cabeçalho e essas linhas e envie novamente em Novo lote. O reenvio usa uma nova seleção; a tela não altera o arquivo original.

5. Use Limpar para remover arquivo, texto e resultado antes de começar de novo.

Na resposta síncrona da API v1, uma rejeição pode trazer o código normalizado em codigo e preservar o retorno da prefeitura em codigoOriginal. A tela envia sempre para a fila; consulte o evento do job para o detalhe de uma falha ocorrida depois da validação inicial.

Informe o Perfil tributário no lote

1. Cadastre o perfil antes do envio e obtenha seu ID na tela Perfis tributários.

2. Informe esse número em perfilTributarioId na linha correspondente. O perfil precisa estar ativo, pertencer à conta e à mesma empresa indicada em empresaId.

3. Os campos não nulos do perfil prevalecem sobre aliquotaISSQN, tpRetISSQN, codigoTribNac, codigoTribMun, locPrestacaoIBGE e deducaoBaseISS enviados na linha.

Acompanhe o resultado

1. Depois de Lote enviado, clique em Acompanhar na fila.

2. A Fila mostra o processamento de cada linha válida. Depois do evento de autorização ou rejeição, consulte a nota e seus eventos em Histórico.

Use o mesmo recurso pela API

A API v1 oferece POST /api/v1/nfse/lote em CSV ou JSON, com modo síncrono e assíncrono. Consulte Integrações e API pública para autenticação, limites, idempotência e formato das respostas.

Se algo der errado

• CSV vazio. indica que o arquivo ou o conteúdo colado não tem dados.

• CSV sem cabeçalho. indica que não foi possível identificar a primeira linha de colunas.

• CSV sem colunas obrigatórias lista os nomes que precisam voltar ao cabeçalho.

• Linha N: campo é obrigatório. identifica uma célula obrigatória vazia; corrija a linha informada e reenvie-a.

• Para outras mensagens de arquivo, validação ou processamento, consulte Mensagens de erro e o que fazer.