A NFS-e (Nota Fiscal de Serviços Eletrônica) é o documento fiscal digital utilizado para registrar a prestação de serviços e é de responsabilidade das prefeituras municipais. Diferentemente de outros documentos fiscais brasileiros - centralizados na SEFAZ - cada município adota seu próprio provedor (sistema, layout e regras), o que torna a emissão heterogênea entre cidades.
Particularidades
- Provedores múltiplos – cada prefeitura define o layout e o padrão de integração (ex.: Abrasf, Ginfes, ISS.net, Tinus, entre outros).
- Processamento síncrono ou assíncrono – algumas prefeituras autorizam no ato da transmissão; outras retornam apenas um número de lote, que precisa ser consultado posteriormente.
- Regras próprias de cancelamento – prazos, justificativas obrigatórias e até a exigência de NFS-e substituta variam por município.
O que esta seção cobre
- Transmissão da NFS-e para o provedor municipal.
- Consulta de status do lote (essencial em prefeituras assíncronas).
- Cancelamento da NFS-e já emitida, seguindo as regras do município.
Status de retorno mais comuns
- Status 2 – Em processamento: a prefeitura ainda não concluiu a análise.
- Processado com sucesso: NFS-e gerada e disponível para consulta ou download.
- Erro ou rejeição: a resposta indicará o motivo para correção.
Nota: Consulte sempre a documentação do provedor municipal do seu destino - comportamento, campos obrigatórios e prazos podem divergir entre cidades.
Transmitir NFS-e
Transmite uma NFS-e ao provedor municipal da prefeitura de destino.
Como funciona na API
O endpoint recebe os dados da nota de serviço, normaliza para o layout específico do provedor da prefeitura, transmite ao ambiente oficial e retorna:
- O número do lote gerado para acompanhamento.
- O número da NFS-e autorizada, quando a prefeitura retorna de forma síncrona.
Quando usar
Use este endpoint para emitir uma NFS-e em homologação ou produção. Em prefeituras assíncronas, guarde o número do lote retornado para consultar o status posteriormente através do endpoint Consultar Status.
Nota: O comportamento síncrono/assíncrono e os prazos de retorno variam entre prefeituras - veja a visão geral da seção para detalhes.
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 NFS-e › Request Body
TipoAmbienteTipo de Ambiente de Transmissão.
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
LoteNúmero do lote de envio.
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
Lista contendo as informações dos documentos fiscais.
Transmitir NFS-e › Responses
Successful operation
DataRecebimentoData que o lote foi recebido.
LoteNúmero do Lote das NFS-e (Número interno da prefeitura/sistema).
CodLoteNúmero do Lote do Brasil NF-e.
ProtocoloNúmero do Protocolo/Lote das NFS-e retornado pela prefeitura.
CodTipoAmbienteTipo de Ambiente de Transmissão.
Valores Possíveis:
1: Produção
2: Homologação
DsTipoAmbienteDescrição do ambiente de transmissão.
MunicipioEnvioNome do município de transmissão da NFS-e.
StatusLoteStatus da transmissão do lote.
Valores Possíveis:
1: Lote processado
2: Aguardando processamento
3: Ocorreu um erro ao processar o lote
4: Ocorreu um erro ao analisar as informações do lote
ErrorDescrição do erro, caso o status do lote retornado for igual a 3.
AvisosLista de avisos não-bloqueantes do lote (vazia em sucesso sem ressalvas).
Base64XmlLoteConteúdo do XML do lote enviado à prefeitura, em Base64 (quando disponível).
TempoRequisicaoPrefeituraTempo, em milissegundos, da requisição ao webservice da prefeitura.
Lista das NFS-e contidas no lote.
Consultar Status
Este artigo explica como funciona a consulta de informações de um lote de NFS-e.
A consulta de lote permite verificar o status de processamento de uma NFS-e enviada à prefeitura, especialmente em municípios que operam de forma assíncrona, onde a transmissão não retorna imediatamente o número da nota autorizada.
Para que serve a consulta de lote?
Com o número do lote em mãos, é possível:
- Verificar se o lote já foi processado pela prefeitura.
- Identificar se a NFS-e foi autorizada, rejeitada ou retornada com erro.
- Obter o número da NFS-e emitida (quando disponível).
- Monitorar integrações que dependem de processamento assíncrono.
Como funciona na API
Este endpoint envia uma requisição ao provedor municipal utilizando o número do lote informado. A prefeitura retorna o estado atual do processamento e, quando finalizado, disponibiliza os dados completos da NFS-e.
Cenários comuns
- Status 2 – Em processamento: A prefeitura ainda não concluiu a análise do lote.
- Processado com sucesso: A NFS-e foi gerada e estará disponível para consulta ou download.
- Erro ou rejeição: A resposta indicará o motivo para correção.
Nota: O comportamento e o tempo de processamento variam conforme o provedor municipal. Alguns municípios podem demorar mais para finalizar o lote.
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.
Consultar Status › Request Body
codLoteCódigo do Lote.
RpsNúmeros de RPS.
Consultar Status › Responses
Successful operation
DataRecebimentoData que o lote foi recebido.
LoteNúmero do Lote das NFS-e (Número interno da prefeitura/sistema).
CodLoteNúmero do Lote do Brasil NF-e.
ProtocoloNúmero do Protocolo/Lote das NFS-e retornado pela prefeitura.
CodTipoAmbienteTipo de Ambiente de Transmissão.
Valores Possíveis:
1: Produção
2: Homologação
DsTipoAmbienteDescrição do ambiente de transmissão.
MunicipioEnvioNome do município de transmissão da NFS-e.
StatusLoteStatus da transmissão do lote.
Valores Possíveis:
1: Lote processado
2: Aguardando processamento
3: Ocorreu um erro ao processar o lote
4: Ocorreu um erro ao analisar as informações do lote
ErrorDescrição do erro, caso o status do lote retornado for igual a 3.
AvisosLista de avisos não-bloqueantes do lote (vazia em sucesso sem ressalvas).
Base64XmlLoteConteúdo do XML do lote enviado à prefeitura, em Base64 (quando disponível).
TempoRequisicaoPrefeituraTempo, em milissegundos, da requisição ao webservice da prefeitura.
Lista das NFS-e contidas no lote.
Cancelamento
Este artigo explica como é efetuado o cancelamento de uma NFS-e.
O cancelamento é utilizado quando a nota de serviço foi emitida com informações incorretas ou quando a operação fiscal precisa ser anulada. O processo de cancelamento depende das regras do provedor municipal, podendo exigir justificativa, autorização prévia ou seguir restrições específicas de cada prefeitura.
Quando posso cancelar uma NFS-e?
Cada município possui legislações e prazos próprios, mas geralmente é permitido cancelar quando:
- A nota foi emitida com erro e ainda está dentro do prazo legal de cancelamento.
- A prestação de serviço não ocorreu.
- A prefeitura permite cancelamento sem substituição.
Situações comuns
- Cancelamento imediato, algumas prefeituras autorizam o cancelamento de forma direta e síncrona.
- Cancelamento assíncrono, outras retornam Status 2 – Em processamento, exigindo consulta posterior.
- Cancelamento condicionado, municípios que exigem aprovação manual, justificativa detalhada ou anexos.
Como funciona na API
Este endpoint envia a solicitação de cancelamento ao provedor municipal contendo:
- Dados da NFS-e.
- Número da nota ou número do lote (segundo o provedor).
- Justificativa do cancelamento (quando exigido).
A prefeitura retorna o status da operação e, quando aprovado, o protocolo de cancelamento.
Observações importantes
- O cancelamento de NFS-e não segue um padrão nacional, cada prefeitura possui regras específicas.
- Alguns municípios exigem emissão de NFS-e Substituta em vez de cancelamento direto.
Nota: Consulte sempre as regras do provedor municipal para garantir que o cancelamento seja feito corretamente dentro dos prazos estabelecidos.
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.
Cancelamento › Request Body
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
TipoDocumentoTipo do documento fiscal.
SEMPRE COLOCAR 1 PARA NFS-e
Valores Possíveis:
0: NF-e, NFC-e, MDF-e, CT-e
1: NFS-e
NumeroNFSeNúmero da NFS-e a ser cancelada
CodCancelamentoNFSeCódigo do motivo de cancelamento da NFS-e
Valores Possíveis:
1: Erro na emissão
2: Serviço não prestado
3: Duplicidade da nota
9: Outros
Cancelamento › Responses
Successful operation
DsMotivoDescrição do status do evento emitido
DsEventoDescrição do evento emitido
DsAmbienteDescrição do ambiente em que foi emitido o evento
NuProtocoloNúmero de protocolo do evento
CodStatusRespostaSefazCódigo de status de resposta da SEFAZ
NumeroSequencialNúmero sequencial do evento
StatusStatus do evento
Valores Possíveis:
1: Evento Processado
2: Aguardando Processamento do Evento
3: Ocorreu um erro ao processar o evento
ErrorDescrição do erro quando ocorrer
AvisosLista de avisos não-bloqueantes do evento (vazia em sucesso sem ressalvas).