Pular para o conteúdo

Emitir uma NFSe (Nota Fiscal de Serviço)

A NFSe é emitida pelo município (não pela SEFAZ estadual) e cada cidade tem regras um pouco diferentes. A API do FazNota abstrai essas diferenças.

Pré-requisitos

  • Empresa com inscrição municipal ativa.
  • Município com integração suportada pela FazNota (verificar com o suporte).
  • Cliente e serviços (produtos tipo: "S") cadastrados.

Fluxo

  1. Emitir a NFSe

    Terminal window
    curl -X POST $BASE/nfse/emissao \
    -H "Authorization: Token $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "numero-origem": "OS-2026-00088",
    "observacao": "Serviço de consultoria realizado em maio/2026.",
    "informacoes-complementares": "ISS retido pelo tomador conforme art. 6º da LC 116/2003. Contrato 4471/2026.",
    "iss-retido": "1",
    "indicador-operacao": "100301",
    "nome-contato": "João Silva",
    "telefone-contato": "11987654321",
    "data-fim": "2026-05-31",
    "cliente": "12345678000199",
    "itens": [
    { "produto": "SRV-CONSULT", "quantidade": "10", "valor-unitario": "250.00" }
    ]
    }'
  2. Consultar pelo recibo

    Terminal window
    curl $BASE/nfse/nota/{recibo} \
    -H "Authorization: Token $TOKEN"

Discriminação, informações complementares e ISS retido

Três campos opcionais do corpo da emissão que costumam ser confundidos:

CampoOnde apareceRegras
observacaoDiscriminação do serviço no DANFSe/XMLTexto livre, até 2.000 caracteres
informacoes-complementaresSeção “Informações Complementares” do DANFSe/XMLTexto livre, até 2.000 caracteres. Seção diferente da discriminação — os dois podem ter conteúdos distintos na mesma nota. Alguns municípios truncam antes (ex.: 255 ou 1.000 caracteres), o que é tratado automaticamente
iss-retidoIndicador de retenção da nota"1" = ISS retido pelo tomador (substituição tributária), "2" = não retido. Padrão "2" quando omitido
indicador-operacaoIndicador de operação de fornecimento (ADN / reforma tributária)Opcional. Barueri e Osasco recusam a nota sem ele. O código vem do Anexo VII; qual vale depende do item da LC 116 do serviço (Anexo VIII). Sempre 6 dígitos, com zero à esquerda: "100301", "030101", "020201" — com 5 dígitos o grupo IBS/CBS sai da nota. Na locação de imóvel (serviços 99.03), desde a 3.19.0, 020201 é recusado: o padrão é 020101 (veja Locação de imóvel)

Tomador no exterior (3.8.0)

Para emitir NFS-e a um tomador sem CPF/CNPJ, com endereço fora do Brasil (ex.: vendedor estrangeiro de marketplace), envie o cliente como objeto com endereco.pais diferente de BR:

Terminal window
curl -X POST $BASE/nfse/emissao \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"numero-origem": "SHOPEE-2026-07-CN-0001",
"data-fim": "2026-07-31",
"observacao": "Comissao de afiliado - julho/2026",
"indicador-operacao": "100302",
"tributacao-issqn-nacional": "1",
"cliente": {
"tipo": "J",
"razao-social": "SHENZHEN EXAMPLE TECHNOLOGY CO LTD",
"documento-estrangeiro": "91440300MA5G123456",
"endereco": {
"pais": "CN", "cidade": "Shenzhen", "provincia": "Guangdong",
"codigo-postal": "518000", "rua": "Keyuan Road", "numero": "88",
"bairro": "Nanshan District"
}
},
"comercio-exterior": {
"modo-prestacao": "1", "vinculo": "0", "moeda": "220", "valor-moeda": "0.18",
"mecanismo-apoio-prestador": "01", "mecanismo-apoio-tomador": "01",
"movimentacao-temporaria-bens": "1", "enviar-mdic": "0"
},
"itens": [ { "produto": "SRV-AFILIADO", "quantidade": "1", "valor-unitario": "0.94" } ]
}'
CampoRegra
endereco.paisISO 3166 alfa-2 do Anexo A do Padrão Nacional (CN, KR, HK…). Ausente ou BR = endereço nacional de sempre. ZZ não é aceito
cidade, provincia, codigo-postal, rua, numero, bairroOpcionais na emissão de NFS-e (3.9.0): o que faltar sai como - na nota, como o Padrão Nacional aceita. Obrigatórios em /clientes. cep, estado e complemento são recusados junto com pais estrangeiro (o endereço no exterior não tem complemento)
documento-estrangeiroObrigatório (NIF). Não há emissão para tomador no exterior sem NIF: motivo-sem-documento-estrangeiro é recusado. cpf/cnpj são recusados
tributacao-issqn-nacional"1" tributável, "2" imunidade, "3" exportação, "4" não incidência. Sem padrão
pais-resultadoISO alfa-2; obrigatório com tributação "3" (E0590), proibido nas demais (E0591)
comercio-exteriorGrupo comExt: todos os campos obrigatórios quando o grupo é enviado; numero-di/numero-re conforme movimentacao-temporaria-bens (E0352/E0354/E0356). O Padrão Nacional exige o grupo para tomador no exterior (E0330)

Condomínio edilício (3.11.0)

A NFS-e das taxas condominiais (serviço 99.05.01, NT SE/CGNFS-e 009 v1.01, obrigatória a partir de 01/12/2026) vai no grupo opcional condominio do POST /nfse/emissao. Só vale para empresa marcada como condomínio edilício no FazNota e para nota com um único item, do serviço 99.05.01. O município do imóvel e o enquadramento no IBS/CBS vêm do cadastro da empresa, não da API.

Terminal window
curl -X POST $BASE/nfse/emissao \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"numero-origem": "COND-2026-12-AP101",
"cliente": "12345678909",
"condominio": {
"vencimento": "2026-12-10",
"cobrancas": [
{
"tipo": "01", "valor": "700.00",
"detalhamento": [
{ "tipo": "003", "valor": "650.00" },
{ "tipo": "008", "valor": "50.00" }
]
},
{ "tipo": "05", "valor": "70.00" }
],
"descontos": [
{ "tipo": "2", "descricao": "Desconto por pontualidade", "valor": "50.00" }
]
},
"itens": [ { "produto": "SRV-CONDOMINIO", "quantidade": "1", "valor-unitario": "770.00" } ]
}'
CampoRegra
vencimentoObrigatório. Vencimento original das taxas do mês para o condômino (AAAA-MM-DD)
cobrancas[]Obrigatório, de 1 a 20. tipo: 01 condomínio ordinário, 02 condomínio privativo, 03 fundo de promoção e propaganda, 04 impostos e taxas, 05 fundo de reserva, 99 outra cobrança (exige descricao, até 150). Cada tipo só uma vez, exceto o 99
cobrancas[].detalhamento[]Opcional, até 20. tipo 001 a 036 (ex.: 003 cond. comum fixo, 008 água, 014 gás, 018 multa, 030 fundo de reserva, 034 taxa extra) ou 999 outro (exige descricao). Quando informado, os itens têm de somar o valor da cobrança
descontos[]Opcional, até 10: tipo 1 incondicionado ou 2 condicionado (ex.: pontualidade), descricao (até 150) e valor
Item da notaO valor do item tem de ser a soma das cobranças (no exemplo, 700,00 + 70,00 = 770,00)
ValoresTodos em texto, com ponto e duas casas

Locação de imóvel (3.18.0)

A NFS-e do aluguel (serviços 99.03.01 a 99.03.05, NT SE/CGNFS-e 009, grupos imovel e gLocacao do IBS/CBS) vai no grupo opcional locacao. Só vale para empresa marcada para NFS-e de locação no FazNota e para nota com um único item, de um serviço 99.03 com NBS de imóvel (1.1002.10.00 residencial ou 1.1002.20.00 não residencial). Não combina com condominio.

Terminal window
curl -X POST $BASE/nfse/emissao \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"numero-origem": "ALUG-2026-12-0001",
"cliente": "12345678909",
"locacao": {
"municipio-imovel": "4127700",
"valor-total": "1500.00",
"percentual-copropriedade": "100",
"vencimento": "2026-12-10",
"indicador-operacao": "020101",
"classificacao-tributaria": "200027",
"unidades": [
{
"inscricao-imobiliaria": "12345",
"cep": "85900010",
"logradouro": "Rua Barao do Rio Branco",
"numero": "250",
"bairro": "Centro",
"ajustes": [
{ "tipo": "01", "valor": "85.40" },
{ "tipo": "03", "valor": "320.00" },
{ "tipo": "04", "valor": "600.00" },
{ "tipo": "99", "descricao": "Taxa de coleta de lixo", "valor": "12.50" }
]
}
]
},
"itens": [ { "produto": "SRV-ALUGUEL", "quantidade": "1", "valor-unitario": "1500.00" } ]
}'
CampoRegra
municipio-imovelObrigatório. Código IBGE (7 dígitos) do município onde fica o imóvel
valor-totalObrigatório. Valor total do aluguel (a operação inteira, antes da copropriedade)
percentual-copropriedadeParte do locador quando o imóvel tem mais de um dono, de 0.01 a 100. Ausente = 100
desconto-incondicionado / desconto-condicionadoOpcionais (o incondicionado menor que o valor total). Os descontos vão neste grupo, nunca no item
vencimentoVencimento original do aluguel (AAAA-MM-DD), opcional
indicador-operacaoAnexo VIII 1.02.00. Ausente = 020101. 020102 só no imóvel não residencial; 030101 só com classificacao-tributaria 200048 (hotelaria e parques), no 99.03.01 residencial. 020201 é recusado desde a 3.19.0, com a mensagem do código esperado
classificacao-tributariacClassTrib do IBS/CBS. Ausente = 200027. 200026 (zona reabilitada) só no 99.03.01, e a empresa precisa ter a configuração fiscal de serviço com essa classificação
unidades[]Obrigatório, de 1 a 99. Cada unidade com o cib (dispensa o endereço) ou o endereço completo (cep, logradouro, numero, bairro, complemento); inscricao-imobiliaria (IPTU) opcional
unidades[].ajustes[](3.19.0) Ajustes da base de cálculo (gAjusteBCLocImoveis), opcional, até 1000 por unidade. tipo: 01 tributos (IPTU), 02 emolumentos, 03 condomínio, 04 redutor social (só no imóvel residencial, NBS 1.1002.10.00), 99 outras (exige descricao, até 150; não vale nos demais). valor maior que zero, e é o total da parcela (não a parte do coproprietário). A soma dos ajustes não pode passar do valor-total
Item da notaO valor do item tem de ser percentual-copropriedade × valor-total (arredondamento half even, como no Anexo VI). No exemplo, 100% × 1.500,00 = 1.500,00
ValoresTodos em texto, com ponto e duas casas

Locação de bem móvel (3.23.0)

A NFS-e do aluguel de máquina, equipamento, veículo ou caçamba (serviço 99.04.01, NT SE/CGNFS-e 009, grupo bensMoveis do IBS/CBS) usa o mesmo grupo locacao, com a lista bens-moveis no lugar dos campos do imóvel. Só vale para empresa marcada para NFS-e de locação no FazNota e para nota com um único item, de um serviço 99.04.01 com NBS do grupo 1.1101 ou 1.1102 do Anexo VIII. Locação pura de bem móvel não tem ISS (não incidência): o ISS do item sai zerado. Pelo Anexo VIII, vale a partir de 01/12/2026 (Simples Nacional: 01/01/2027).

Terminal window
curl -X POST $BASE/nfse/emissao \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"numero-origem": "LOC-2026-12-0001",
"cliente": "11222333000181",
"locacao": {
"indicador-operacao": "010103",
"bens-moveis": [
{ "ncm": "84295190", "descricao": "Retroescavadeira", "quantidade": "1" },
{ "ncm": "84748090", "descricao": "Betoneira 400 litros", "quantidade": "2" }
]
},
"itens": [ { "produto": "SRV-LOCBEM", "quantidade": "1", "valor-unitario": "4800.00" } ]
}'
CampoRegra
bens-moveis[]Obrigatório, de 1 a 1000 bens. ncm (8 dígitos), descricao (até 150) e quantidade (inteiro de 1 a 999, em texto)
indicador-operacaoObrigatório — o modo de entrega do bem: 010101 retirada no estabelecimento do locador, 010102 retirada fora dele, 010103 entrega no endereço do locatário ou 010106 aquisição centralizada
classificacao-tributariaSó 000001 (o padrão, pode omitir); a empresa precisa ter a configuração fiscal de serviço com essa classificação
Campos do imóvelmunicipio-imovel, valor-total, percentual-copropriedade, descontos, vencimento e unidades não valem junto com bens-moveis: a nota é de imóvel ou de bem móvel
Item da notaUm só, de serviço 99.04.01 com NBS do Anexo VIII. O valor do item é o valor do aluguel
ISSNão há: iss-retido "1" e tributacao-issqn-nacional diferente de "4" são recusados

Cadastro de produto de serviço

Terminal window
curl -X POST $BASE/produtos \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"referencia": "SRV-CONSULT",
"nome": "Consultoria técnica (hora)",
"valor": "250.00",
"medida": "H",
"tipo-produto": "S",
"codigo-servico": "1.04"
}'

codigo-servico segue a lista municipal (varia por cidade — geralmente a lista da Lei Complementar 116/2003 com adaptações locais).

Filtrar listagem por data

Terminal window
curl "$BASE/nfse?dataInicial=2026-05-01&page=1&page_size=20" \
-H "Authorization: Token $TOKEN"

Cancelamento

Terminal window
curl -X POST $BASE/nfse/cancelamento \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"chave": "chave_nfse_aqui",
"motivo": "Cancelamento solicitado pelo tomador — serviço não realizado."
}'

Particularidades por município

Cada município tem variações. Os pontos mais comuns:

AspectoComportamento
NumeraçãoAlguns municípios numeram, outros usam a chave municipal
CancelamentoPrazo varia (geralmente até virada do mês)
Item de serviçoLista padrão LC 116/2003 + adaptações locais
Retenções (INSS, ISS)Calculadas conforme cadastro fiscal do prestador

Verifique com o suporte FazNota se o seu município está homologado e quais campos adicionais são necessários.

Erros comuns

MensagemCausa
Campo nfse@cliente documento não pertence a um cliente cadastrado.Cliente desconhecido
Campo nfse@itens não pode ser vazio.Array de itens vazio
Cliente no exterior incompleto, faltam em cliente@: ...Tomador no exterior sem NIF ou sem nome (na emissão de NFS-e); em /clientes, também sem algum campo do endereço (lista todos de uma vez)
... caractere que a NFS-e não aceita em: ...Emoji, símbolo fora do plano básico ou caractere de controle no nome/endereço do tomador no exterior
... caracteres que não cabem em ISO-8859-1 (latino) em: ...Texto não latino em /clientes, no e-mail, no código postal, na observacao ou nas informacoes-complementares
status: "900" (rejeição municipal)Inscrição municipal incorreta, código de serviço inválido para o município, ou retenção mal calculada