Emissão NFS-e Passo a Passo
RPS, conversão em NFS-e, DANFSE PDF e cancelamento municipal.
A NFS-e (Nota Fiscal de Serviços Eletrônica) acoberta a prestação de serviços sujeita ao ISSQN. A NFER opera com cobertura de 100% dos municípios brasileiros (5.571 cidades) para MEI e mais de 2.870 cidades ativas para emissão geral (Simples Nacional, ME e EPP) através de um único contrato REST JSON unificado.
Para circulação de produtos físicos ou comércio mercantil, consulte os guias de Emissão de NF-e (modelo 55) ou NFC-e (modelo 65).
Exemplos de Criação de NFS-e
A API aceita duas formas de identificação do tomador do serviço: envio direto (inline), ideal para emissões diretas sem necessidade de cadastro prévio, ou informando o customerId de um cliente já existente na sua conta. Ambos os exemplos incluem o bloco de IBS e CBS da Reforma Tributária com indicação de preenchimento opcional.
1. Emissão com Tomador Inline (Dados Completos)
Envia os dados e o endereço do tomador diretamente no payload. A NFER faz a validação e o registro transparente na base sem que sua aplicação precise fazer duas chamadas de API:
2. Emissão com Tomador por ID (customerId)
Para clientes recorrentes previamente cadastrados via painel ou via endpoint POST /v1/customers, basta informar o UUID:
Fluxo de Emissão em 3 Etapas
Criar Rascunho DPS
Gera o rascunho da declaração, valida retenções de ISSQN e responde 201 Created em ~50ms com o ID da nota.
Transmitir ao ADN
Assina o XML da DPS com Certificado A1 e transmite à Receita Federal / SEFIN via fila assíncrona (202 Accepted).
Obter Resultado
Assim que autorizada, o NFER dispara o webhook nfse.autorizada com os links de download do DANFSE oficial em PDF e do XML com protocolo.
Estrutura do Payload
Principais blocos que compõem a emissão de serviços:
| Bloco | Campo | Propósito e Conteúdo |
|---|---|---|
| Modo de Emissão | transmit | Boolean (opcional, padrão false). Se true, enfileira automaticamente a transmissão ao SEFIN Nacional / ADN logo após salvar a DPS (emissão direta em 1 passo). Se false, grava a nota em rascunho em ~40ms para conferência prévia. Aliases aceitos: "transmitir" e "emitir". |
| Tomador do Serviço | tomador | Dados do cliente tomador (CPF/CNPJ, Razão Social, e-mail e endereço). Se já cadastrado, informe customerId. |
| Disparo de E-mail | enviarEmail | Boolean (opcional). Controla o envio de e-mail ao tomador contendo o link da consulta pública do DANFSE e o XML após a autorização no ADN/município. Se true, força o envio; se false, suprime o envio deste serviço. Se omitido, respeita a configuração da empresa. |
| Serviço Prestado | codigoServico, descricao | Código nacional de 6 dígitos (cTribNac da LC 116) e discriminação detalhada dos serviços executados. |
| Valores & ISSQN | valorServico, tribIssqn | Valor bruto do serviço, indicador de tributação do ISSQN (1 Tributável, 2 Exportação, etc.) e alíquota. |
| Competência / Data | dCompet | Data ou mês de competência do serviço (fato gerador do ISSQN). Aceita formatos AAAA-MM-DD, AAAA-MM, MM/AAAA ou MM.AAAA (ex.: "2026-09-01" ou "09/2026"). Se omitido, assume a data atual de emissão. |
| Local da Prestação | cLocPrestacao | Código IBGE de 7 dígitos do município onde o serviço foi fisicamente executado (determina incidência territorial). |
| Intermediário | intermediario | Opcional para serviços mediados por plataformas ou agências: CPF/CNPJ e Razão Social do intermediador. |
| Reforma Tributária | ibsCbs | Classificação tributária (cClassTrib), código da operação (cIndOp) e alíquotas de IBS/CBS na prestação de serviço. |
Catálogo de Serviços vs. Envio Inline
Você pode emitir a NFS-e enviando todos os dados fiscais diretamente no corpo da nota (codigoServico, descricao, valorServico) ou utilizar o Catálogo de Serviços pré-cadastrado na NFER:
Ideal para sistemas que já possuem catálogo próprio. Basta passar o código de 6 dígitos (cTribNac), descrição e valor na chamada de POST /v1/nfse.
Cadastre seus serviços uma única vez via painel (/dashboard/services) ou via API (POST /v1/services) com discriminação padrão, NBS e regras de IBS/CBS.
Nota: O campo aliqIss é opcional. Para empresas optantes pelo Simples Nacional, a alíquota de ISS é determinada automaticamente pela faixa de receita do PGDAS ou na tela de envio da nota, evitando erros cadastrais.
Operações Relacionadas
Endpoints dedicados para o ciclo completo da NFS-e e gestão de serviços:
| Operação | Método e Rota | Referência Técnica |
|---|---|---|
| Cadastrar Serviço no Catálogo | POST /v1/services | Ver Parâmetros → |
| Listar Catálogo de Serviços | GET /v1/services | Ver Listagem → |
| Criar DPS / NFS-e | POST /v1/nfse | Ver Parâmetros & Presets → |
| Transmitir ao ADN | POST /v1/nfse/:id/send | Ver Envio Assíncrono → |
| Consultar NFS-e (Status) | GET /v1/nfse/:id | Ver Retorno e Chave ADN → |
| Baixar DANFSE (PDF) | GET /v1/nfse/:id/danfse | Ver Download do PDF → |
| Baixar XML da NFS-e | GET /v1/nfse/:id/xml | Ver Download do XML → |
| Cancelar NFS-e | POST /v1/nfse/:id/cancel | Ver Cancelamento → |
| Substituir NFS-e | POST /v1/nfse/:id/substituir | Ver Substituição Oficial → |
Próximos Passos
- Teste requisições com exemplos de código na Referência da API NFS-e.
- Consulte o catálogo de códigos e alíquotas em Códigos de Serviço Padronizados.
- Veja como monitorar notas de serviço tomadas em Monitor Fiscal de NFS-e.