Developers / Documentos Fiscais / NFS-e
Documentos Fiscais · NFS-e

Emitir NFS-e POST

Emite uma Nota Fiscal de Serviço eletrônica para o padrão nacional (DPS/ADN) ou para o layout homologado do município do prestador -- a CentralFiscal resolve automaticamente qual provedor/layout usar a partir do município.

Quando utilizar

Sempre que seu sistema precisar emitir uma nota de prestação de serviço em nome do contribuinte cadastrado. Cada chamada gera exatamente um documento -- para emitir várias notas, faça uma chamada por nota (a chave de idempotência evita duplicidade em caso de retry).

Pré-requisitos

  • Contribuinte (prestador) já cadastrado -- POST /v1/contribuintes.
  • Certificado digital A1 vinculado ao contribuinte -- POST /v1/contribuintes/{id}/certificado-digital.
  • Tomador (cliente do prestador) já carregado, se possuir CPF/CNPJ -- POST /v1/contribuintes/{id}/tomadores.
  • Código do item da lista de serviços válido (LC 116/2003, formato NN.NN).

Fluxo da operação

💡
Diferente de NF-e/CT-e/MDF-e: a emissão de NFS-e é síncrona. A própria chamada POST já transmite pra SEFIN/Ambiente Nacional e devolve o resultado final -- não existe um "receber e processar depois" aqui.
POST /v1/nfse/emissoes
Motor fiscal monta e assina o RPS/DPS
Transmite pra SEFIN/ADN (mesma chamada)
200 OK · resultado final

A resposta já vem com status: AUTHORIZED (sucesso) ou REJECTED/ ERROR (falha) -- inclusive falha de validação de campo (ex.: faltou servico.discriminacao) volta como 200 OK com status: ERROR, não como 400. Ver Resposta de erro.

Endpoint

POST https://areacliente.centralfiscal.com.br/v1/nfse/emissoes

Headers

HeaderValor
AuthorizationBearer <sua_api_key>obrigatório
Content-Typeapplication/jsonobrigatório
Idempotency-Keystring livre, definida por vocêopcional -- alternativa ao campo idempotencia no corpo

Body

Clique num campo com pra expandir.

idempotencia
string
Alternativa ao header Idempotency-Key.
id_externo
string
Identificador do pedido/OS no seu ERP.
rps_numero
integer
Número do RPS. Opcional -- se omitido, a CentralFiscal usa e incrementa automaticamente o contador do próprio contribuinte.
rps_serie
string
Série do RPS -- definida livremente por cada município, sem padrão nacional. Se omitida junto com rps_numero, usa a série configurada na área do contribuinte (default "1").
rps_tipo
integer
Default: 1
Enum: 123
1 RPS (uso comum), 2 RPS Nota Fiscal Conjugada/Mista, 3 Cupom.
rps_status
integer
Default: 1
Enum: 12
1 Normal (uso comum). 2 só se aplica à substituição de RPS cancelado antes de virar nota -- não serve para cancelar a NFS-e já emitida.
data_emissaorequired
string <date>
Data de emissão do RPS/NFS-e (AAAA-MM-DD).
competenciarequired
string <date>
Data de competência do serviço prestado (AAAA-MM-DD).
required
object
documentorequired
string
CNPJ/CPF do prestador, cadastrado e autorizado no contrato.
inscricao_municipal
string
Se omitida, usa a inscrição já cadastrada no contribuinte.
razao_social
string
Se omitida, usa a razão social já cadastrada no contribuinte.
regime_tributario
string
Enum: SIMPLES_NACIONALLUCRO_PRESUMIDOLUCRO_REALMEI
municipio_ibge
integer
uf
string
object
Resolvido automaticamente se o documento já foi carregado via POST .../tomadores.
documento
string
razao_social
string
inscricao_estadual
string
inscricao_municipal
string
email
string
telefone
string
object
logradouro
string
numero
string
bairro
string
municipio_ibge
integer
municipio
string
uf
string
cep
string
required
object
codigo_lista_servico
string
Código do item da lista de serviços (LC 116/2003), formato NN.NN.
codigo_tributacao_municipio
string
Código na tabela própria da prefeitura -- formato definido por cada município.
codigo_nbs
string
Nomenclatura Brasileira de Serviços -- usado na classificação de IBS/CBS.
discriminacaorequired
string
Descrição do serviço prestado, impressa na NFS-e/DANFSe.
municipio_prestacao_ibge
integer
Se omitido, usa o município cadastrado do prestador.
municipio_incidencia_ibge
integer
Município onde o ISS é devido. Omita quando coincide com o do prestador; não envie 0.
exigibilidade_iss
integer
Default: 1
Enum: 1234567
1 Exigível, 2 Não incidência, 3 Isenção, 4 Exportação, 5 Imunidade, 6 Suspensa (decisão judicial), 7 Suspensa (processo administrativo).
numero_processo
string
Processo judicial/administrativo p/ exigibilidade 6/7. Aceito pela API; transmissão ao município ainda não implementada nos provedores homologados.
required
object
valor_servicosrequired
number
Valor bruto dos serviços prestados.
valor_deducoes
number
desconto_incondicionado
number
desconto_condicionado
number
base_calculo_iss
number
aliquota_issrequired
number
Percentual, ex.: 2 para 2%.
valor_iss
number
iss_retido
boolean
Indica se o ISS foi retido pelo tomador.
valor_liquido
number
responsavel_retencao
string
Enum: NAO_RETIDOTOMADORINTERMEDIARIO
object
Retenções federais na fonte. Envie só quando houver retenção efetiva -- pis/cofins/csll/ir/inss, cada um com base_calculo/aliquota/valor.
pis
object
cofins
object
csll
object
ir
object
inss
object
object
IBS/CBS (EC 132/2023, LC 214/2025) -- cálculo real via CentralFiscal.NFSe.Tributario.IbsCbsCalculator, não passthrough. Cobre o período de teste 2026 (LC 214/2025, art. 343). O Ambiente Nacional exige a classificação tributária (cst/classificacao_tributaria) quando o prestador NÃO é optante do Simples Nacional nem MEI (que recolhem por fora, sem destacar IBS/CBS na DPS) -- se omitido nesse caso, a API preenche automaticamente com cst=000/classificacao_tributaria=000001 (tributação integral, sem benefício), em qualquer ambiente (homologação e produção). Informe este campo explicitamente se o serviço tiver uma classificação diferente da genérica.

Lista de CST reduzida em relação à NF-e -- mostrando só os 7 códigos que têm ao menos 1 classificação tributária de serviço (nomenclatura NBS) na tabela nacional. Os demais (220/221/400/510/515/550/620/800/810/811/830) são exclusivos de mercadoria/ST/diferimento e não se aplicam a NFS-e.

regime_especial_tributacao
integer
Enum: 123456
Campo de raiz do payload (não dentro de reforma_tributaria). 1 Microempresa Municipal, 2 Estimativa, 3 Sociedade de Profissionais, 4 Cooperativa, 5 MEI, 6 ME/EPP.
optante_simples_nacional
boolean
Campo de raiz. Se regime_especial_tributacao = 5 (MEI), deve ser true.
incentivo_fiscal
boolean
Campo de raiz.
Array of objects
Itens do serviço. Quando ausente, a CentralFiscal considera um item único com os totais de servico/valores.
codigo_lista_servico
string
cnae_codigo
string
descricaorequired
string
tributavel
boolean
Indica se o item é tributável pelo ISS.
quantidaderequired
number
valor_unitariorequired
number
valor_desconto
number
valor_liquido
number
pis_cst
string
cofins_cst
string
codigo_nbs
string
Usado na classificação de IBS/CBS.
object
Dados de obra (LC 116, itens 7.02/7.05). Suporte hoje limitado a municípios atendidos pelo provedor Tecnos; nos demais é ignorado.
codigo_obra
string
art_obra
string
ART (Anotação de Responsabilidade Técnica) do responsável pela obra.
object
validar_tributacao
string
Enum: STRICTWARNOFF
validar_xml_antes_assinatura
boolean
permitir_contingencia
boolean
gerar_qrcode
boolean

Exemplo mínimo

Apenas os campos obrigatórios -- veja o código ao lado.

Exemplo completo

Com tomador, retenções e reforma tributária preenchidos -- veja o código ao lado.

Resposta de sucesso

200 OK -- síncrono, já com o resultado final da transmissão (status: AUTHORIZED). Sem etapa de "consultar depois": numero_documento, protocolo e o XML/DANFSe (em detalhes) já vêm nesta mesma resposta.

Resposta de erro

Dois formatos bem diferentes, dependendo de onde a falha acontece:

  • Pré-requisito não atendido (contrato sem NFS-e, prestador não identificado, sem certificado ativo) -- 400/403/409 de verdade, antes de qualquer tentativa de emissão.
  • Falha de validação de campo ou rejeição do município (ex.: faltou servico.discriminacao) -- a chamada retorna 200 OK normalmente, mas com status: "ERROR" e a mensagem real dentro de mensagem/detalhes. Sempre confira o campo status, não só o código HTTP.

Catálogo completo de erros: Tratamento de Erros.

Próximos passos

  • Já com o resultado na mesma resposta, normalmente não é preciso consultar de novo -- mas GET /v1/nfse/emissoes/{emissao_id} continua disponível pra reconsulta.
  • Baixar o XML e o DANFSe usando as URLs em detalhes.
  • Se precisar corrigir/cancelar, ver POST /v1/nfse/cancelamentos abaixo.

Cancelamento

POST /v1/nfse/cancelamentos -- exige motivo/justificativa com pelo menos 15 caracteres. O jeito mais simples é informar emissao_id (o transmissao_id retornado na emissão) -- a API busca sozinha o número, série e código de verificação da nota original. Sem emissao_id, informe numero_nfse/serie/codigo_verificacao manualmente. Veja o exemplo ao lado.

Outros eventos

📤
Eventos como Emitente. Os eventos abaixo (Substituição, Confirmação e Rejeição do Prestador) são todos do ponto de vista de quem presta o serviço -- NFS-e que o seu próprio contribuinte emitiu. Se em vez disso você precisa se manifestar sobre uma NFS-e que outra empresa emitiu, com o seu contribuinte como tomador (recebeu o serviço) ou como intermediário (plataforma/marketplace que intermediou a prestação), veja Confirmação/Rejeição do Tomador e do Intermediário -- é uma seção diferente.

Exclusivos do Ambiente Nacional (Padrão Nacional) -- não existem no layout de provedores municipais legados (Ginfes, Giss, IPM, etc.), que retornam erro de negócio claro se você tentar usá-los fora do Padrão Nacional. Assim como no cancelamento, informar emissao_id resolve sozinho a chave de acesso da nota original.

  • POST /v1/nfse/substituicoes -- evento e105102 (Cancelamento de NFS-e por Substituição). Cancela a NFS-e original vinculando a chave de uma NFS-e substituta que já precisa ter sido emitida antes desta chamada. Exige chave_substituta (chave de acesso da nota substituta) e codigo_motivo_substituicao (01 Desenquadramento do Simples, 02 Enquadramento no Simples, 03 Inclusão retroativa de imunidade/isenção, 04 Exclusão retroativa de imunidade/isenção, 05 Rejeição pelo tomador/intermediário, 99 Outros).
  • POST /v1/nfse/confirmacoes-prestador -- evento e202201 (Manifestação de NFS-e - Confirmação do Prestador). O evento mais simples: só precisa da chave de acesso da nota, sem motivo nem observação.
  • POST /v1/nfse/rejeicoes-prestador -- evento e202205 (Manifestação de NFS-e - Rejeição do Prestador). Exige codigo_motivo_rejeicao (1 Duplicidade, 2 NFS-e já emitida pelo tomador, 3 Não ocorrência do fato gerador, 4 Erro de responsabilidade tributária, 5 Erro de valor/serviço/data, 9 Outros).
💡
Reconsultar qualquer um desses eventos depois: GET /v1/nfse/substituicoes/{transmissao_id}, GET /v1/nfse/confirmacoes-prestador/{transmissao_id} ou GET /v1/nfse/rejeicoes-prestador/{transmissao_id} (mesmo transmissao_id devolvido na resposta de criação).

Eventos como Tomador/Intermediário

📥
Eventos como Destinatário. Ao contrário da seção anterior, os eventos abaixo são do ponto de vista de quem recebe uma NFS-e emitida por outra empresa -- seu contribuinte não é o prestador do serviço aqui. Volte pra Substituição, Confirmação/Rejeição do Prestador se o cenário for o seu contribuinte se manifestando sobre uma nota que ele mesmo emitiu.

Assim como os eventos do prestador, exclusivos do Ambiente Nacional (Padrão Nacional). O "autor" da manifestação é sempre a identidade fiscal do seu próprio contribuinte (a mesma usada em prestador_documento nos outros endpoints) -- a API não valida se esse CNPJ é de fato o tomador/intermediário identificado dentro da NFS-e de terceiro, porque não há acesso ao XML original emitido pelo prestador pra conferir; a responsabilidade de mandar o evento certo é de quem chama a API.

Como tomador -- use quando seu contribuinte contratou/recebeu um serviço de outra empresa e precisa se manifestar sobre a NFS-e recebida:

  • POST /v1/nfse/confirmacoes-tomador -- evento e203202 (Manifestação de NFS-e - Confirmação do Tomador). Só precisa da chave de acesso da nota recebida, sem motivo nem observação.
  • POST /v1/nfse/rejeicoes-tomador -- evento e203206 (Manifestação de NFS-e - Rejeição do Tomador). Exige codigo_motivo_rejeicao (mesmos códigos 1 a 5/9 de Rejeição do Prestador).

Como intermediário -- use quando seu contribuinte atuou como plataforma/marketplace intermediando a prestação de serviço de um terceiro (nem prestador, nem tomador):

  • POST /v1/nfse/confirmacoes-intermediario -- evento e204203 (Manifestação de NFS-e - Confirmação do Intermediário). Só precisa da chave de acesso da nota, sem motivo nem observação.
  • POST /v1/nfse/rejeicoes-intermediario -- evento e204207 (Manifestação de NFS-e - Rejeição do Intermediário). Exige codigo_motivo_rejeicao (mesmos códigos 1 a 5/9).
💡
Reconsultar qualquer um desses eventos depois: GET /v1/nfse/confirmacoes-tomador/{transmissao_id}, GET /v1/nfse/rejeicoes-tomador/{transmissao_id}, GET /v1/nfse/confirmacoes-intermediario/{transmissao_id} ou GET /v1/nfse/rejeicoes-intermediario/{transmissao_id} (mesmo transmissao_id devolvido na resposta de criação).
⚠️
Eventos que ainda não existem -- o leiaute oficial da NFS-e Nacional (tiposEventos_v1.01.xsd) define 16 eventos ao todo; além de Cancelamento e dos 7 acima (Substituição, Confirmação/Rejeição do Prestador, do Tomador e do Intermediário), faltam apenas eventos exclusivos do fisco municipal: Anulação da Rejeição, Confirmação Tácita (gerada automaticamente pelo sistema, não pela API) e os eventos administrativos (Cancelamento Deferido/Indeferido por Análise Fiscal, Cancelamento/Bloqueio/Desbloqueio por Ofício) -- esses nunca seriam emitidos pela API de qualquer forma, são notificações que chegam do município.