Desde 2026, a nota de serviço caminha para um padrão único no país: o emissor nacional (nfse.gov.br), no lugar de um sistema diferente em cada prefeitura. A API emite a NFS-e por esse padrão, com as mesmas regras de chave, idempotência e resposta da nota de produto.
Antes da primeira nota
- A empresa precisa estar credenciada no emissor nacional, e o município dela precisa ter aderido. Confira no portal nfse.gov.br.
- Na tela Empresa, preencha a inscrição municipal.
- A chave de API precisa ter a opção de nota de serviço (NFS-e) marcada.
A chamada
curl -X POST https://erp.datafrontier.com.br/api/v1/nfse \
-H "X-Chave-Integracao: dfapp_SUA_CHAVE" \
-H "Idempotency-Key: os-77" \
-H "Content-Type: application/json" \
-d @servico.json{
"ambiente": "homologacao",
"referencia": "os-77",
"dataCompetencia": "2026-09-27",
"tomador": {
"cpfCnpj": "11444777000161",
"nome": "Cliente Serviços LTDA",
"email": "fin@exemplo.com",
"endereco": {
"logradouro": "Rua B", "numero": "1", "bairro": "Centro",
"codigoMunicipio": "3106200", "uf": "MG", "cep": "30110000"
}
},
"servico": {
"codigoTributacaoNacional": "14.05",
"codigoTributacaoMunicipal": "001",
"codigoCnae": "3314710",
"discriminacao": "Manutenção de equipamento"
},
"valorServicos": 1000.00,
"desconto": 0,
"aliquotaIss": 2.00
}| Campo | O que é |
|---|---|
| dataCompetencia | O mês em que o serviço foi prestado, que decide o mês do imposto. |
| codigoTributacaoNacional | O item da lista de serviços (LC 116), como "14.05", ou o código de 6 dígitos. |
| codigoTributacaoMunicipal | O código do serviço na sua prefeitura, quando ela exige. |
| discriminacao | O texto que descreve o serviço, como vai aparecer na nota. |
| aliquotaIss | A alíquota do ISS em %, conforme a lei do seu município. |
A resposta tem o mesmo formato da nota de produto: id, situação, número, chave e os links do XML e do PDF, pelas rotas /api/v1/nfse/{id}/xml e /pdf.
Quando o cliente retém imposto
Muita empresa que contrata serviço desconta parte dos impostos do pagamento e recolhe ela mesma: o ISS e, conforme o caso, IR, CSLL, PIS, COFINS e INSS. A nota precisa dizer isso, para o seu cliente pagar o valor certo. Pela API, são campos a mais no mesmo corpo, todos opcionais: sem eles, a nota sai sem retenção, como no exemplo acima.
{
"valorServicos": 1000.00,
"desconto": 0,
"aliquotaIss": 2.00,
"issRetido": true,
"tributacaoFederal": {
"cst": "01",
"aliquotaPis": 0.65,
"aliquotaCofins": 3.00,
"tipoRetencao": 3,
"irrfRetido": 15.00,
"csllRetida": 10.00,
"cpRetida": 0
}
}| Campo | O que é |
|---|---|
| issRetido | true quando o cliente retém o ISS. Empresa do Simples manda também a aliquotaIss (a alíquota do ISS dentro do Simples); sem ela, a nota é recusada. |
| tributacaoFederal.cst, aliquotaPis, aliquotaCofins | O PIS e a COFINS do serviço. Sem os valores, a API calcula base × alíquota. |
| tributacaoFederal.tipoRetencao | O que o cliente retém de PIS, COFINS e CSLL, com os códigos do emissor nacional: 0 nada, 3 PIS, COFINS e CSLL, 4 PIS e COFINS sem CSLL, 8 só CSLL. |
| irrfRetido, csllRetida, cpRetida | Os valores retidos de IR, CSLL e INSS (a contribuição previdenciária), em reais. |
Neste exemplo, o cliente paga R$ 918,50: os R$ 1.000 do serviço menos o ISS (R$ 20), o IR (R$ 15), a CSLL (R$ 10), o PIS (R$ 6,50) e a COFINS (R$ 30). Esse valor líquido volta calculado pelo emissor nacional. Se as retenções somadas passarem do valor da nota, a API recusa antes de enviar, com a conta no erro.
Os limites de hoje, sem rodeio
- Um serviço (um código da LC 116) por nota. Serviços diferentes vão em notas diferentes.
- O cancelamento vai de fato ao emissor nacional nos dois ambientes, inclusive em homologação.
Na dúvida sobre código de serviço e alíquota, a resposta é do seu contador. A API confere o formato; o enquadramento é da empresa.
Conhecer a API de nota fiscal Documentação completa
Tutorial escrito pela equipe da API em 05 de outubro de 2026, conferido com a versão v1 no ar. Regra fiscal muda: o enquadramento de imposto da sua empresa é com o seu contador. Viu algo desatualizado? Fale com a gente pelo WhatsApp.