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
-
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" }]}' -
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:
| Campo | Onde aparece | Regras |
|---|---|---|
observacao | Discriminação do serviço no DANFSe/XML | Texto livre, até 2.000 caracteres |
informacoes-complementares | Seção “Informações Complementares” do DANFSe/XML | Texto 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-retido | Indicador de retenção da nota | "1" = ISS retido pelo tomador (substituição tributária), "2" = não retido. Padrão "2" quando omitido |
indicador-operacao | Indicador 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:
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" } ] }'| Campo | Regra |
|---|---|
endereco.pais | ISO 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, bairro | Opcionais 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-estrangeiro | Obrigató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-resultado | ISO alfa-2; obrigatório com tributação "3" (E0590), proibido nas demais (E0591) |
comercio-exterior | Grupo 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.
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" } ] }'| Campo | Regra |
|---|---|
vencimento | Obrigató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 nota | O valor do item tem de ser a soma das cobranças (no exemplo, 700,00 + 70,00 = 770,00) |
| Valores | Todos 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.
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" } ] }'| Campo | Regra |
|---|---|
municipio-imovel | Obrigatório. Código IBGE (7 dígitos) do município onde fica o imóvel |
valor-total | Obrigatório. Valor total do aluguel (a operação inteira, antes da copropriedade) |
percentual-copropriedade | Parte do locador quando o imóvel tem mais de um dono, de 0.01 a 100. Ausente = 100 |
desconto-incondicionado / desconto-condicionado | Opcionais (o incondicionado menor que o valor total). Os descontos vão neste grupo, nunca no item |
vencimento | Vencimento original do aluguel (AAAA-MM-DD), opcional |
indicador-operacao | Anexo 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-tributaria | cClassTrib 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 nota | O 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 |
| Valores | Todos 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).
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" } ] }'| Campo | Regra |
|---|---|
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-operacao | Obrigató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-tributaria | Só 000001 (o padrão, pode omitir); a empresa precisa ter a configuração fiscal de serviço com essa classificação |
| Campos do imóvel | municipio-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 nota | Um só, de serviço 99.04.01 com NBS do Anexo VIII. O valor do item é o valor do aluguel |
| ISS | Não há: iss-retido "1" e tributacao-issqn-nacional diferente de "4" são recusados |
Cadastro de produto de serviço
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
curl "$BASE/nfse?dataInicial=2026-05-01&page=1&page_size=20" \ -H "Authorization: Token $TOKEN"Cancelamento
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:
| Aspecto | Comportamento |
|---|---|
| Numeração | Alguns municípios numeram, outros usam a chave municipal |
| Cancelamento | Prazo varia (geralmente até virada do mês) |
| Item de serviço | Lista 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
| Mensagem | Causa |
|---|---|
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 |