NFS-e Nacional (Serviço)

Emitir NFS-e (Nacional / ADN)

Cria a Declaração de Prestação de Serviço (DPS) da NFS-e Nacional no padrão unificado (Resolução CGSN 189 / Ambiente de Dados Nacional - ADN / SPED). Suporta emissão direta em 1 passo ("transmit": true) com transmissão imediata ao ADN/Prefeitura ou modo rascunho em 2 passos para conferência prévia de tomador e retenções federais/municipais. Consulte também o guia de Emissão de NFS-e.

Fluxo de Emissão Direta NFS-e (1 Passo):
1.
Envio da Requisição (`POST /v1/nfse`): Envie o JSON com "transmit": true (ou aliases "transmitir": true / "emitir": true). O NFER valida o schema nacional da DPS (cTribNac de 6 dígitos, regras municipais e retenções de ISS/federais).
2.
Retorno Imediato (`201 Created`): A DPS é salva com status "processando" e número reservado, sendo enfileirada no motor assíncrono de transmissão para o Ambiente de Dados Nacional (ADN) do Governo Federal ou prefeitura conveniada, sem travar sua conexão HTTP.
3.
Webhook de Autorização (`nfse.autorizada`): Assim que a autorização é confirmada pelo ADN/Sefin Nacional, seu webhook recebe a notificação contendo o ID, número da NFS-e, código de verificação, link direto da consulta pública do DANFSE e o XML unificado. O e-mail automático para o tomador também é disparado se enviarEmail estiver ativo.
POST
https://api.nfer.me
/v1/nfse

Authorizations

X-API-Key
string
header
required

Chave de API emitida no painel NFER enviada no header da requisição.

Content-Type
string
header
required

application/json

Body

application/json
transmit
boolean
opcional
default:false
Define o modo de emissão da NFS-e:
•
true: Emissão Direta — o NFER valida, grava a DPS e enfileira imediatamente a transmissão para o Ambiente de Dados Nacional (ADN / SEFIN Nacional / Prefeitura) com status "processando", dispensando chamar o endpoint POST /v1/nfse/:id/send. Ideal para checkouts, SaaS, bots e integrações via API.
•
false ou omitido (padrão): Modo Rascunho — grava a DPS com status "rascunho" em ~40ms para conferência prévia de retenções e dados do tomador antes do envio definitivo.

Aliases aceitos para total compatibilidade: "transmitir" e "emitir".

Exemplo:true
environment
"homologacao" | "producao"
opcional
default:da empresa

Sobrepõe o ambiente salvo da conta para esta emissão ("homologacao" ou "producao"). Se omitido, utiliza a configuração da empresa.

Exemplo:homologacao
enviarEmail
boolean
opcional
default:da empresa

Controla o envio automático de e-mail ao tomador contendo o link da consulta pública do DANFSE e o XML da NFS-e após a autorização no ADN/município. Se true, força o envio para o e-mail do tomador. Se false, suprime o envio para este serviço. Se omitido, respeita a preferência global cadastrada na NFER.

Exemplo:true
customerId
string<uuid>
opcional

UUID do tomador previamente cadastrado na NFER via /v1/customers. Opcional se o bloco "tomador" inline for informado.

Exemplo:c1f7b882-990a-41d9-95e2-6320a0ee1234
tomador
object
opcional

Dados completos do cliente tomador informados inline. Permite emitir em uma única chamada de API sem necessidade de cadastro antecipado em /v1/customers. Obrigatório se "customerId" não for informado.

codigoServico
string
required

Código de Tributação Nacional com 6 dígitos numéricos (cTribNac conforme LC 116 nacional).

Exemplo:010701
descricao
string
required

Discriminação clara e detalhada dos serviços prestados (1 a 2000 caracteres).

Exemplo:Desenvolvimento e manutenção contínua de software sob demanda.
valorServico
number
required

Valor total do serviço prestado (deve ser maior que zero).

Exemplo:2500.00
dCompet
string
opcional

Data de competência da prestação do serviço (fato gerador do ISSQN). Formatos aceitos: "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 (hoje). Aliases aceitos: "dataCompetencia", "competencia".

Exemplo:2026-09-01
serie
integer
opcional
default:1

Número de série da DPS (default: 1).

finNFSe
integer (0, 1, 2)
opcional
default:0

Finalidade da emissão da DPS/NFS-e Nacional: 0 (NFS-e Regular - padrão), 1 (NFS-e de Ajuste a Crédito / Estorno IBS-CBS), 2 (NFS-e de Ajuste a Débito / Complementar IBS-CBS).

regEspTrib
integer (0 a 9)
opcional
default:0

Regime Especial de Tributação conforme tabela oficial SEFIN Nacional: 0 (Nenhum - padrão), 1 (Ato Cooperado), 2 (Estimativa), 3 (Microempresa Municipal), 4 (Notário/Cartório), 5 (Profissional Autônomo), 6 (Sociedade de Profissionais / Uniprofissional - ISS Fixo pago por cota anual à Prefeitura sem destaque de alíquota nem retenção na nota). Se omitido, herda a configuração da empresa.

Exemplo:6
tribIssqn
integer
opcional
default:1

Tributação do ISS: 1 (Tributável no município), 2 (Exportação), 3 (Não Incidência), 4 (Imunidade). Default: 1.

tpRetIssqn
integer
opcional
default:1

Tipo de retenção do ISS: 1 (Não Retido), 2 (Retido pelo Tomador), 3 (Retido pelo Intermediário). Default: 1.

cLocPrestacao
string
opcional

Código IBGE de 7 dígitos do município da prestação do serviço. Se omitido, usa o cMun da empresa prestadora.

Exemplo:3550308
cNbs
string
opcional

Código da Nomenclatura Brasileira de Serviços (NBS) com até 9 dígitos.

Exemplo:101011100
cTribMun
string
opcional

Código de subitem de tributação municipal complementar (até 20 caracteres).

ibsCbs
object
opcional

Campos da Reforma Tributária (IBS e CBS) no padrão DPS / ADN da NFS-e Nacional (NT SE/CGNFS-e nº 009).

reservarNumero
boolean
opcional
default:true

Se true (padrão), reserva atomicamente o próximo número de DPS na sequência.

retFed
object
opcional

Retenções de tributos federais na fonte (IRRF, CSLL, PIS, COFINS, INSS/CP).

Response

application/json

NFS-e (DPS) criada com sucesso. Suporta Emissão Direta ("transmit": true -> status "processando" com número reservado e transmissão assíncrona ao ADN/Prefeitura enfileirada) ou Modo Rascunho ("transmit": false -> status "rascunho" em ~40ms para conferência prévia e envio posterior via POST /v1/nfse/:id/send).

id
string<uuid>

Identificador único do recurso.

Exemplo:e9b5a201-9231-4828-b0a3-a7c3df95a001
company_id
string<uuid>

Identificador único da empresa emissora.

Exemplo:a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
customer_id
string<uuid>

Identificador único do cliente destinatário.

Exemplo:c1f7b882-990a-41d9-95e2-6320a0ee1234
numero
integer

Número da nota fiscal.

Exemplo:329
serie
integer

Série da nota fiscal.

Exemplo:1
status
string

Status atual do processamento da nota.

Exemplo:processando
environment
string

Ambiente de emissão (homologacao ou producao).

Exemplo:homologacao
codigo_servico
string

Exemplo retornado: "010701"

Exemplo:010701
descricao
string
Exemplo:Desenvolvimento e manutenção contínua de software sob demanda.
valor_servico
string

Exemplo retornado: "2500.00"

Exemplo:2500.00
c_loc_prestacao
string

Exemplo retornado: "3550308"

Exemplo:3550308
trib_issqn
integer
Exemplo:1
tp_ret_issqn
integer
Exemplo:1
origem
string

Origem da emissão.

Exemplo:api
created_at
string<date-time>

Data e hora de criação do registro.

Exemplo:2026-10-24T23:50:00.000Z
updated_at
string<date-time>

Data e hora da última atualização.

Exemplo:2026-10-24T23:50:00.000Z
curl --request POST \
  --url https://api.nfer.me/v1/nfse \
  --header 'X-API-Key: <sua_chave_api>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transmit": true,
  "codigoServico": "010701",
  "descricao": "Desenvolvimento e licenciamento de software sob demanda.",
  "valorServico": 2500,
  "serie": 1,
  "tribIssqn": 1,
  "tpRetIssqn": 1,
  "cLocPrestacao": "3550308",
  "tomador": {
    "tipoPessoa": "J",
    "cpfCnpj": "00000000000191",
    "nome": "EMPRESA CONTRATANTE LTDA",
    "email": "financeiro@contratante.com.br",
    "endereco": {
      "logradouro": "Avenida Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "cMun": "3550308",
      "xMun": "São Paulo",
      "UF": "SP",
      "CEP": "01310100"
    }
  },
  "ibsCbs": {
    "cClassTrib": "000001",
    "cIndOp": "100301",
    "cMunIncidencia": "3550308",
    "aliqCbs": 0.9,
    "aliqIbsUf": 0.1,
    "aliqIbsMun": 0
  }
}'
{
  "id": "e9b5a201-9231-4828-b0a3-a7c3df95a001",
  "company_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "customer_id": "c1f7b882-990a-41d9-95e2-6320a0ee1234",
  "numero": 329,
  "serie": 1,
  "status": "processando",
  "environment": "homologacao",
  "codigo_servico": "010701",
  "descricao": "Desenvolvimento e licenciamento de software sob demanda.",
  "valor_servico": "2500.00",
  "c_loc_prestacao": "3550308",
  "trib_issqn": 1,
  "tp_ret_issqn": 1,
  "origem": "api",
  "created_at": "2026-10-24T23:50:00.000Z",
  "updated_at": "2026-10-24T23:50:00.000Z"
}