Operações de emissão e pré-visualização de NF-e e NFC-e.
A NF-e (Nota Fiscal Eletrônica, modelo 55) é o documento fiscal digital utilizado em operações entre empresas ou com consumidor final quando há circulação de mercadorias, substituindo a nota fiscal em papel.
A NFC-e (Nota Fiscal de Consumidor Eletrônica, modelo 65) é voltada ao comércio varejista e às operações com consumidor final não contribuinte, substituindo o cupom fiscal e a NF modelo 2.
O que esta seção cobre
- Transmissão da NF-e/NFC-e para a SEFAZ - o XML é validado, assinado digitalmente e enviado ao ambiente autorizador, que retorna autorizado, rejeitado ou denegado.
- Pré-visualização do documento antes do envio oficial, útil para conferência visual e homologação.
Resultados possíveis da transmissão
- Autorizado – a nota foi validada e aceita pela SEFAZ.
- Rejeitado – alguma regra de validação foi violada (XML inválido, CFOP incorreto, dados inconsistentes, etc.).
- Denegado – a operação não pode ser realizada devido a irregularidades cadastrais do emitente ou destinatário.
Nota: Os eventos da NF-e/NFC-e (carta de correção, cancelamento, manifestação do destinatário e inutilização de numeração) ficam agrupados na seção Eventos NF-e / NFC-e.
Transmitir NFe / NFCe
Transmite uma NF-e ou NFC-e para o ambiente autorizador da SEFAZ.
Quando usar
Use este endpoint sempre que for necessário emitir uma NF-e ou NFC-e no ambiente de homologação ou produção, registrando oficialmente a operação na SEFAZ.
Como funciona na API
O endpoint recebe o objeto completo da nota fiscal e processa internamente:
- Validação do XML conforme o schema oficial.
- Assinatura digital utilizando o certificado da empresa.
- Transmissão ao ambiente autorizador da SEFAZ.
- Retorno com o protocolo de autorização e detalhes da resposta oficial.
Nota: Certifique-se de que todos os dados obrigatórios estejam corretamente preenchidos e que o certificado digital esteja válido para evitar rejeições. Os possíveis resultados da transmissão (autorizado, rejeitado, denegado) estão descritos na visão geral da seção.
Esta rota não dispara webhook. Para emissão em lote com notificação assíncrona via webhook, use
/EnviarNotaFiscalLote. Veja também Webhooks.
Headers
TokenToken de identificação da empresa. Obrigatório em todas as operações fiscais (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e, Consultas, Escriturações, Energia e Comunicação) e nos métodos da seção Empresas que atuam sobre uma empresa específica (Buscar, Editar, Alterar Certificado, Verificar Certificado, Gerar Link de Ativação, Deletar, Consultar Numeração, Atualizar Numeração). Não é exigido em Adicionar nem em Buscar Todas.
Transmitir NFe / NFCe › Request Body
SerieSérie da Nota Fiscal.
Informe este campo somente se utilizar mais de uma série ou se desejar controlar o valor manualmente. Se deixado em branco, o Brasil NFe fará o controle automático conforme configurado no painel.
Controle automático
Se deixados em branco, Serie, Numero e Lote são gerenciados automaticamente pela Brasil NFe (próximo número disponível por empresa + modelo + série + ambiente). Envie valores apenas se precisar controlar manualmente (ex: migração de sistema, múltiplas séries).
Ver também
NumeroNúmero da nota fiscal.
Preencha este campo apenas se desejar controlar o valor manualmente. Se estiver vazio, o Brasil NFe assumirá o controle automático conforme configurado no painel.
Controle automático
Se deixados em branco, Serie, Numero e Lote são gerenciados automaticamente pela Brasil NFe (próximo número disponível por empresa + modelo + série + ambiente). Envie valores apenas se precisar controlar manualmente (ex: migração de sistema, múltiplas séries).
Ver também
LoteLote da Nota Fiscal.
Preencha este campo apenas se desejar controlar o valor manualmente. Se estiver vazio, o Brasil NFe assumirá o controle automático conforme configurado no painel.
Controle automático
Se deixados em branco, Serie, Numero e Lote são gerenciados automaticamente pela Brasil NFe (próximo número disponível por empresa + modelo + série + ambiente). Envie valores apenas se precisar controlar manualmente (ex: migração de sistema, múltiplas séries).
Ver também
CodigoCódigo numérico que compõe a Chave de Acesso. Número gerado pelo emitente para cada NF-e.
Preencha este campo apenas se desejar controlar o valor manualmente. Se estiver vazio, o Brasil NFe assumirá a geração do código
DataEntradaSaidaData e Hora da saída ou de entrada do produto/serviço.
Default automático
Se não enviada, a API usa a data/hora atual do servidor (timezone -03:00 Brasília). Envie apenas para backdating autorizado (ajuste, complementar) - a SEFAZ aceita até 30 dias antes da transmissão.
DataEmissaoData e Hora da saída ou de entrada do produto/serviço (Envia a data atual caso não informada).
Default automático
Se não enviada, a API usa a data/hora atual do servidor (timezone -03:00 Brasília). Envie apenas para backdating autorizado (ajuste, complementar) - a SEFAZ aceita até 30 dias antes da transmissão.
JustificativaUtilizar quando o tipo de emissão for diferente de normal.
Acionamento automático
A Brasil NFe comuta automaticamente para contingência quando a SEFAZ fica offline por mais que o limite configurado na empresa. Os modos são:
- 1 - Normal (online).
- 3 - SCAN (contingência via Sistema de Contingência do Ambiente Nacional).
- 4 - EPEC (Evento Prévio de Emissão em Contingência) - SEFAZ autoriza depois.
- 5 - FS-Offline (Formulário de Segurança offline).
Justificativa é obrigatória quando TipoEmissao ≠ 1.
Ver também
NFReferenciaLista de Chaves de Acesso de Notas Fiscais de Referência.
IndicadorPresencaIndicador de presença do comprador no estabelecimento comercial no momento da operação.
Rejeição SEFAZ
- 787 - NFC-e com
IndicadorPresenca=4(entrega a domicílio) exige identificação do destinatário (Cliente com CPF/CNPJ e endereço).
Ver também
Valores Possíveis:
0: Não se aplica
1: Operação presencial
2: Operação não presencial, pela Internet
3: Operação não presencial, Teleatendimento
4: NFC-e com entrega a domicílio
5: Presencial fora do estabelecimento
9: Operação não presencial, outros
IndicadorIntermediadorIndicador de intermediador/marketplace.
Valores Possíveis:
falso: Operação sem intermediador
verdadeiro: Operação em site ou plataforma de terceiros
ConsumidorFinalIndica operação com Consumidor final.
Valores Possíveis:
falso: Normal
verdadeiro: Consumidor final
CalcularIBPTEfetuar cálculo do IBPT automaticamente.
Cálculo automático
Com CalcularIBPT=true, a API consulta a tabela IBPT por NCM e preenche vTotTrib (tributos federais, estaduais e municipais estimados) em cada item e no total da nota. Exigência da Lei 12.741/2012.
Valores Possíveis:
falso: Não Calcular
verdadeiro: Calcular
NaturezaOperacaoDescrição da Natureza da Operação.
ModeloDocumentoCódigo do modelo do Documento Fiscal.
Restrição
NFC-e (ModeloDocumento=65) aceita apenas CFOPs de saída de venda a consumidor final (5101, 5102, 5103, 5104, 5115, 5405, 5656, 5667, 5933, 6108, 6109, 6110). Outros CFOPs são rejeitados.
Rejeições SEFAZ
- 725 - CFOP inválido para NFC-e.
- 386 - CFOP incompatível com CSOSN em NFC-e.
Valores Possíveis:
55: NF-e
65: NFC-e
FinalidadeFinalidade da emissão da NF-e.
Valores Possíveis:
1: Normal
2: Complementar
3: Ajuste
4: Devolução
TipoAmbienteIdentificação do Ambiente.
Ambiente de emissão
- 1 (Produção) - o documento emitido tem validade fiscal real e é reportado ao destinatário.
- 2 (Homologação) - ambiente de teste; a SEFAZ descarta o documento após alguns dias, sem efeito fiscal.
Use homologação durante o desenvolvimento e a integração; só alterne para produção depois que o fluxo estiver validado.
Valores Possíveis:
1: Produção
2: Homologação
ObservacaoObservação da NF.
ObservacaoFiscoObservação Fisco da NF.
IdentificadorInternoIdentificador Interno do sistema emissor.
Dados do Cliente (Destinatário) da Nota Fiscal.
Lista de produtos ou serviços da Nota Fiscal.
Lista de pagamentos efetuados.
Detalhes de Fatura e Parcelas para cobrança.
Informações sobre o Transporte e Frete.
EnviarEmailIndica se deve enviar o e-mail da nota fiscal automaticamente ao destinatário após a autorização.
Informações do local de Entrega (se diferente do Destinatário).
Informações referente a exportação.
Retenções federais totais da nota (IRRF, PIS/COFINS/CSLL retidos, Previdência). Gera a tag retTrib no XML.
Transmitir NFe / NFCe › Responses
Successful operation
Base64XmlXML da nota fiscal codificado em Base64.
Base64FileArquivo da nota fiscal (ex: PDF/DANFE) codificado em Base64.
Informações de retorno e valores da Nota Fiscal.
ErrorMensagem de erro do Brasil NFe quando a operação falha. Vazia em caso de sucesso.
AvisosLista de avisos não-bloqueantes da emissão (vazia em sucesso sem ressalvas).
Transmitir NFe em Lote
Transmite múltiplas NF-e em um único lote para o ambiente autorizador da SEFAZ e dispara um webhook ao final do processamento.
Quando usar
Use esta rota quando precisar emitir várias notas em sequência sem manter a conexão HTTP aberta durante todo o processamento — ideal para integrações de alto volume, importações em lote vindas de ERP e cargas de retaguarda.
Diferença para /EnviarNotaFiscal
/EnviarNotaFiscal— síncrona, uma nota por requisição. A resposta HTTP já contém o protocolo da SEFAZ, XML em base64 e DANFE. Não dispara webhook./EnviarNotaFiscalLote— aceita uma lista de notas (nFInfos). A resposta HTTP é apenas o aceite do lote. O resultado real (autorização, rejeição, chaves de acesso) é entregue de forma assíncrona via webhook no eventonfe.lote.finalizado.
Pré-requisito: webhook configurado
Para receber o resultado em push, é necessário ter um webhook ativo cadastrado no painel e vinculado à empresa. Se nenhum webhook estiver configurado (ou se todas as 5 tentativas de entrega falharem), o lote continua sendo processado normalmente — basta consultar o resultado depois via /ConsultarLoteNFe usando o CodLote retornado por este endpoint.
Detalhes de cadastro, formato do envelope, headers e verificação da assinatura HMAC: veja Webhooks.
Fluxo
- Cliente envia
POST /EnviarNotaFiscalLotecom a lista de notas. - Brasil NFe valida os payloads, persiste as notas e inicia a transmissão à SEFAZ.
- Cliente recebe a resposta HTTP confirmando o aceite (com o
CodLote). - Ao concluir o processamento, Brasil NFe faz
POSTno webhook do cliente com o eventonfe.lote.finalizado. - Cliente responde
2xxem até 15s.
Headers
TokenToken de identificação da empresa.
Transmitir NFe em Lote › Request Body
TipoAmbienteIdentificação do ambiente de processamento.
Valores Possíveis:
1: Produção
2: Homologação
Lista de notas fiscais a serem transmitidas neste lote. Cada item segue a mesma estrutura usada em /EnviarNotaFiscal (schema Envio).
ModeloDocumentoCódigo do modelo do Documento Fiscal.
Valores Possíveis:
55: NF-e
65: NFC-e
LoteNúmero do lote. Se omitido, o Brasil NFe controla automaticamente.
Transmitir NFe em Lote › Responses
Lote aceito para processamento. O resultado real chega via webhook.
CodLoteEco do código do lote consultado.
StatusLoteStatus agregado do lote.
Valores Possíveis:
1: Aguardando salvar
2: Aguardando transmissão SEFAZ
3: Aguardando finalização
4: Lote finalizado
5: Lote finalizado com erro
DsStatusLoteDescrição textual do StatusLote.
QtdTotalQuantidade total de notas no lote (definida no momento da transmissão).
QtdEmitidaQuantidade de notas autorizadas pela SEFAZ (códigos de status 100 ou 150).
QtdErroQuantidade de notas que receberam resposta da SEFAZ mas não foram autorizadas (códigos diferentes de 100/150).
Detalhe de cada nota processada no lote.
Lista de erros ocorridos na consulta ou no processamento do lote.
avisosAvisos não-bloqueantes associados ao processamento do lote.
statusStatus agregado da resposta (0 quando OK; 2 quando há erros em erros).
Pré-Visualizar Documento
Este artigo explica como é efetuada a pré-visualização de uma NF-e, NFC-e ou CT-e.
A pré-visualização permite gerar o PDF ou XML de um documento fiscal sem realizar a transmissão à SEFAZ. É ideal para validar layout, conferência de dados e inspeção das informações antes da emissão oficial.
Como funciona a pré-visualização
A API permite duas formas de envio:
- XML em BASE64, Pode conter uma ou várias notas.
- Objeto com os dados da nota, Também é possível enviar um lote com múltiplos documentos.
Resultado da operação
- Se houver apenas uma nota, o método retornará o PDF ou XML correspondente.
- Caso sejam enviados múltiplos documentos (via XML contendo várias notas ou lote de objetos), o sistema irá gerar um único PDF consolidado contendo todas as notas processadas.
Quando utilizar este recurso?
Use a pré-visualização quando for necessário:
- Validar o layout da DANFe.
- Revisar informações antes da transmissão.
- Conferir múltiplas notas em conjunto.
- Testar integrações sem afetar o ambiente fiscal.
Como funciona na API
Este endpoint processa os dados fornecidos, monta o XML ou DANFe, e retorna o conteúdo pré-visualizado, sem gerar protocolo de autorização ou qualquer comunicação com a SEFAZ.
Nota: A pré-visualização não substitui a emissão oficial. Após validar o conteúdo, utilize o endpoint de transmissão para registrar a nota no Fisco.
Headers
TokenToken de identificação da empresa. Obrigatório em todas as operações fiscais (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e, Consultas, Escriturações, Energia e Comunicação) e nos métodos da seção Empresas que atuam sobre uma empresa específica (Buscar, Editar, Alterar Certificado, Verificar Certificado, Gerar Link de Ativação, Deletar, Consultar Numeração, Atualizar Numeração). Não é exigido em Adicionar nem em Buscar Todas.
Pré-Visualizar Documento › Request Body
TipoArquivoTipo do arquivo que deseja pré-visualizar.
Valores Possíveis:
0: XML
1: PDF
TipoEnvioTipo do envio que será usado para gerar o arquivo.
Valores Possíveis:
0: Base64 contendo as informações do XML
1: Objeto contendo as informações da(s) nota(s) fiscal(is)
Base64XmlArquivo XML em Base64 (obrigatório se TipoEnvio for 0).
mostrarTarjaPreVisualizacaoControla a exibição da tarja "SEM VALOR FISCAL - PRÉ-VISUALIZAÇÃO" no PDF.
Objeto contendo as informações da(s) nota(s) fiscal(is) (obrigatório se TipoEnvio for 1).
Pré-Visualizar Documento › Responses
Successful operation
StatusVerdadeiro caso o arquivo seja gerado com sucesso e Falso caso contrário.
Base64FileBase64 contendo o arquivo PDF ou XML. Presente apenas se 'Status' for 'true'.
ErrorDescrição do erro, caso o status retornado for igual a false.
AvisosLista de avisos não-bloqueantes da geração (vazia em sucesso sem ressalvas).