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

   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",
       "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

   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

Nota

iss-retido é uma informação da nota, não do item — vale para a nota inteira. Mesmo com ISS retido, a alíquota e o valor do ISS continuam sendo informados no XML; a retenção indica quem recolhe o imposto, não que ele deixe de existir.

Dica

Os três campos são opcionais. Uma requisição que não os envie continua se comportando exatamente como antes: sem informações complementares e com ISS não retido.

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
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