NFS-e (Sistema Nacional)

Emissão de NFS-e pelo Sistema Nacional (gov.br/Sefin) pela API de integração. Segue o mesmo padrão assíncrono da NF-e e da DC-e: você cria um job, recebe 202 com jobId e acompanha por polling ou webhook.

Autenticação: header X-Api-Key (veja Autenticação).

O modelo mental

Na NFS-e você declara uma DPS e quem emite a nota é o Sistema Nacional. Ele devolve o número da NFS-e e uma chave de acesso de 50 dígitos (a da NF-e tem 44). Não há lote nem protocolo.

Duas consequências para quem integra:

1. A alíquota efetiva pode diferir da informada. Município parametrizado no Sistema Nacional aplica a alíquota oficial dele. Use os valores que voltam no job, não os que você enviou.
2. Nunca reenvie um pedido cujo resultado você não conhece. Se a resposta se perdeu, o job traz o idDps: consulte por ele. Reenviar a mesma DPS cria uma segunda nota.

Cadastrar serviços (upsert)

O catálogo de serviços é a origem de cTribNac, alíquota e retenções. Upsert idempotente pelo código:

PUT /api/integracao/servicos/{codigo}
X-Api-Key: enfe_...
Content-Type: application/json

{
  "descricao": "Licenciamento de software",
  "itemListaServico": "1.05",
  "codigoTributacaoNacional": "010501",
  "aliquotaIss": 2.00,
  "tributacaoIssqn": 1,
  "retencaoIssqn": 1,
  "aplicarRetencoesFederais": false
}

Resposta 200: { "criou": true, "servico": { … } }.

No serviço, aplicarRetencoesFederais + aliquotaPis|Cofins|Csll|Ir|Inss dizem quais retenções federais o tipo de serviço sofre quando o tomador é pessoa jurídica. Se a nota retém é decidido na emissão — ver Retenções federais.

codigoTributacaoNacional é validado contra a lista nacional de serviços do Sistema Nacional (Anexo I): código inexistente devolve 400 com os códigos do mesmo subitem (evita a rejeição E0310). Em branco, é preenchido pelo itemListaServico quando o subitem tem um único desdobro nacional; com vários, a resposta é 400 pedindo a escolha — o código nunca é inventado com desdobro 00. codigoTributacaoMunicipio é opcional e 000 é recusado (E0315).

Emitir

POST /api/integracao/nfse

{
  "cnpjEmitente": "43636483000128",
  "codigoServico": "SRV001",
  "cpfCnpjTomador": "34363445000158",
  "valorServicos": 1500.00,
  "competencia": "2026-08-01",
  "numeroPedido": "OS-2026-4471",
  "referenciaExterna": "os-4471"
}

Resposta 202:

{ "jobId": "3f2a...", "status": "Pendente" }

referenciaExterna é a chave de idempotência: repetir a mesma referência devolve o job já criado, em vez de emitir de novo.

Campos

Retenções federais

Com aplicarRetencoesFederais omitido, a nota retém PIS, COFINS, CSLL, IR e INSS pela lei, a partir das alíquotas do serviço:

• Tomador pessoa física, do exterior ou não identificado: nada é retido.
• Prestador optante do Simples Nacional: sem PIS/COFINS/CSLL e sem IR; o INSS só fica se o serviço o indicar (atividades do Anexo IV). MEI: nada.
• Dispensa de pequeno valor: PIS+COFINS+CSLL somados até R$ 10,00, IR até R$ 10,00 e INSS abaixo de R$ 10,00 não são retidos.
• Competência a partir de 01/01/2027: só a CSLL (a LC 214/2025 tira PIS e COFINS da retenção).
• A base é o valor bruto (valorServicos), não a base do ISS.

Mudança de comportamento (22/09/2026): antes, aplicarRetencoesFederais omitido seguia o serviço e retinha de qualquer tomador. Para o comportamento antigo, envie true. Casos que o sistema não identifica sozinho (tomador órgão público, tomador do Simples, dispensas de INSS por declaração) ficam com true/false e as alíquotas do serviço. Detalhes e normas em /ajuda/nfs-e.

Evento e obra

Alguns códigos de tributação nacional exigem um grupo de dados a mais na DPS, conforme o Anexo I do Sistema Nacional: os do item 12 da LC 116 (espetáculos, shows, eventos) exigem evento (rejeição E0390 sem ele) e os de obra de construção civil exigem obra (E0370). Mandar um desses blocos num código que não o admite também é recusado (E0392/E0372). As três situações são barradas antes de reservar número: o job termina em Falha com a mensagem do que falta.

"evento": {
  "nome": "Festival de Inverno",
  "dataInicio": "2026-09-12",
  "dataFim": "2026-09-13",
  "endereco": { "cep": "77001002", "logradouro": "Av. Teotônio Segurado", "numero": "100", "bairro": "Plano Diretor Sul" }
}

• evento identifica o local pelo endereco ou pelo codigoEvento que a prefeitura atribuiu, nunca os dois. O CEP precisa ser do município da prestação (codigoMunicipioPrestacao) — para evento e obra o ISS costuma ser devido onde o serviço acontece (LC 116/2003, art. 3º).
• obra identifica a obra por uma forma: codigoObra (CNO/CEI), codigoCib (8 caracteres) ou endereco. inscricaoImobiliaria é opcional.
• Com prestação no exterior (paisPrestacao), o endereco leva codigoPostalExterior, cidadeExterior e estadoExterior no lugar do CEP.

Consultar o job

GET /api/integracao/nfse/{jobId}

{
  "jobId": "3f2a...",
  "status": "Concluido",
  "resultado": {
    "nfseId": "9c1d...",
    "status": "Autorizada",
    "serie": 1,
    "numero": 128,
    "numeroNfse": "435",
    "chaveAcesso": "35499042436364830001280000000000435...",
    "idDps": "DPS354990424363648300012800001000000000000128",
    "valorServicos": 1500.00,
    "valorIss": 30.00,
    "valorLiquido": 1500.00,
    "xmlUrl": "/api/integracao/nfse/{chave}/xml",
    "danfseUrl": "/api/integracao/nfse/{chave}/danfse"
  }
}

status do job: Pendente → Processando → Concluido | Falha. Em Falha, o campo erro traz o motivo de uma validação local (emitente, série, serviço, tomador, cota…) — a DPS nem foi enviada.

Quando o Sistema Nacional recebe e recusa a DPS, o job fica Concluido e o resultado traz a nota com status Rejeitada e motivo com os erros do Sistema Nacional (código e descrição, separados por | quando são vários). O campo orientacao traz, para cada código conhecido, a explicação e os passos — para você mostrar ao usuário em vez do texto cru. Em nota autorizada, ou sem código conhecido, orientacao é uma lista vazia.

"resultado": {
  "status": "Rejeitada",
  "motivo": "E0314 - O código de tributação municipal informado não existe ou não está administrado pelo município de incidência do ISSQN ...",
  "orientacao": [
    {
      "codigo": "E0314",
      "titulo": "O código municipal não existe no município onde o ISS é devido",
      "explicacao": "O código de tributação municipal (cTribMun) é opcional e só vale quando ...",
      "passos": ["Apague o campo Código municipal (cTribMun) e emita de novo — é a correção na maioria dos casos.", "..."],
      "linkAjuda": "/ajuda/nfs-e#rejeicoes-da-nfs-e"
    }
  ]
}

Os códigos cobertos e o que fazer em cada um estão em Rejeições da NFS-e. Para tentar de novo, corrija os dados e envie um novo pedido, com outra referenciaExterna — repetir a mesma devolve o job já concluído.

Cancelar

POST /api/integracao/nfse/cancelamentos

{
  "chaveAcesso": "35499042436364830001280000000000435...",
  "motivo": 1,
  "justificativa": "Erro na emissao - valor do servico incorreto",
  "referenciaExterna": "canc-4471"
}

motivo: 1 erro na emissão · 2 serviço não prestado · 9 outros. A justificativa precisa de no mínimo 15 caracteres. O prazo de cancelamento é definido pelo município.

Downloads

GET /api/integracao/nfse/{chaveAcesso}/xml      → XML da NFS-e (documento legal)
GET /api/integracao/nfse/{chaveAcesso}/danfse   → DANFSe em PDF

Ambos autenticam por X-Api-Key (as rotas /api/nfse/* do portal são de sessão do navegador e devolveriam 401 para um cliente de API).

Webhook

O evento job.concluido passa a carregar nfseId:

{
  "evento": "job.concluido",
  "jobId": "3f2a...",
  "tipo": "EmissaoNfse",
  "status": "Concluido",
  "referenciaExterna": "os-4471",
  "nfseId": "9c1d...",
  "erro": null
}

Veja Webhooks para a validação da assinatura HMAC.

Erros frequentes