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

   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

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.

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)

Dica

Nome e endereço em qualquer alfabeto (3.9.0). Na emissão de NFS-e, a razão social e o endereço do tomador no exterior podem vir em chinês, coreano ou japonês, exatamente como estão no documento dele — o Padrão Nacional aceita. O que acontece com cada parte:

• Razão social: vai na nota como você enviou.
• Logradouro, número e bairro: o Padrão Nacional só aceita caracteres latinos nesses três campos; enviados em outro alfabeto, eles saem como - na nota. Cidade e província aceitam qualquer alfabeto.
• Cadastro do cliente: guarda um nome latino — o que o cliente já tinha, ou NIF <documento>. É o que GET /clientes/{NIF} devolve; a nota é que leva o nome em ideogramas.

Continuam recusados emoji e caractere de controle (a mensagem diz o campo e o caractere, ex. U+1F600, e que nada foi transmitido). observacao, informacoes-complementares e /clientes continuam só em caracteres latinos (ISO-8859-1).

Nota

Tributável × exportação, o indicador-operacao (100302, 100102, 100502…) e os valores do comercio-exterior são decisão fiscal de quem emite — confirme com a contabilidade. O exemplo acima só ilustra o formato. O cliente também pode ser informado pelo NIF já cadastrado ("cliente": "91440300MA5G123456"), e /clientes aceita o mesmo endereço no exterior (GET/PUT/DELETE /clientes/{NIF}).

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