JSON da NFS-e Nacional

Objetivo: este documento explica como montar o JSON que seu sistema deve enviar para a nossa rota de emissão da NFS-e Nacional. Ele descreve campos, tipos, tamanhos, obrigatoriedade, regras de negócio e traz exemplos práticos. Seu cliente não precisa conhecer o XML nem o PHP interno — basta seguir este JSON.

Visão geral

• Formato: JSON UTF-8.
• Casas decimais: valores monetários com ponto (.) como separador decimal. Ex.: "0.01", "1250.30".
• Datas:
  • Data/hora: ISO-8601, ex.: "2025-11-03T10:10:35" (fuso opcional Z ou -03:00).
  • Data (apenas dia): "YYYY-MM-DD".
• Códigos de município (IBGE): sempre 7 dígitos com zeros à esquerda.
• Strings numéricas: quando indicado, enviar apenas dígitos (sem pontos, barras, etc.).
• API PRDODUÇÃO/HOMOLOGAÇÃO: https://nfapi.diletec.com.br/api/v1/
• API HOMOLOGAÇÃO/DESENVOLVIMENTO: https://nfapi.diletec.dev.br/api/v1/
• Rota de emissão NFS-e: POST /api/v1/nfse/emitir
• Rota de cancelar: PUT /api/v1/nfse/cancelar
• Rota de consultar: GET /api/v1/nfse/consultar/{idEmissao}
• DOC: https://nfapi.diletec.dev.br/api/doc
• Autenticação: x-api-customer, x-api-public, x-api-secret
• Certificado digital: /api/v1/cliente/certificado enviando file, cnpj e pass (senha), no formato A1 (pfx).

Estrutura do JSON (alto nível)

{
  "version": "1",
  "ambiente": "2",
  "DadosNFSE": { /* ver seções abaixo */ }
}

Campos de topo

DadosNFSE – Campos gerais

{
  "Serie": "00900",
  "Numero": 269,
  "CodigoVerificacao": "1d9da",
  "DataEmissao": "2025-11-03T10:10:35",
  "NaturezaOperacao": "1",
  "RegimeEspecialTributacao": "0",
  "OptanteSimplesNacional": "3",
  "RegimeApuracaoSN": "2",
  "IncentivadorCultural": 2,
  "Competencia": "2025-11-03T10:10:00",
  "OutrasInformacoes": "Texto livre",
  "Servico": { ... },
  "PrestadorServico": { ... },
  "TomadorServico": { ... },
  "IntermediarioServico": { ... },
  "OrgaoGerador": { ... },
  "ConstrucaoCivil": { ... }
}

Importante (E0166): se OptanteSimplesNacional = "3" (ME/EPP), obrigatoriamente envie RegimeApuracaoSN.

Importante (E0128): endereço do prestador não deve ir no XML quando o próprio prestador é o emitente. O seu JSON pode trazer PrestadorServico.Endereco, mas será ignorado na montagem do XML.

DadosNFSE.Servico

"Servico": {
  "Valores": { ... },
  "ItemListaServico": "010301",
  "CodigoCnae": "6201500",
  "CodigoTributacaoMunicipio": "004",
  "Discriminacao": "Descrição do serviço",
  "CodigoMunicipio": "3106200"
}

Valores

"Valores": {
  "ValorServicos": "0.01",
  "IssRetido": "1",
  "Aliquota": "6",
  "AliquotaRetencao": "0.0201",
  "ValorIss": "0.00",
  "ValorLiquidoNfse": "0.01"
}

Regra do pAliq: só enviaremos a tag pAliq para o Nacional se OptanteSimplesNacional = "1" e RegimeEspecialTributacao = "0". Caso contrário (MEI ou ME/EPP, ou com regime especial), não envia pAliq — exigência do leiaute nacional.

PrestadorServico

"PrestadorServico": {
  "Cnpj": "34640331000108",
  "InscricaoMunicipal": "11715050015",
  "RazaoSocial": "Empresa XYZ Ltda",
  "Endereco": { ... } // será ignorado no XML nacional
}

TomadorServico

"TomadorServico": {
  "IdentificacaoTomador": {
    "CpfCnpj": { "Cnpj": "29373005000141" },
    "InscricaoMunicipal": "04276830019"
  },
  "RazaoSocial": "Cliente ABC Ltda",
  "Endereco": {
    "Endereco": "Rua X",
    "Numero": "123",
    "Complemento": "Sala 10",
    "Bairro": "Centro",
    "CodigoMunicipio": "1501782",
    "Uf": "PA",
    "Cep": "68488000"
  },
  "Contato": {
    "Telefone": "",
    "Email": ""
  }
}

OrgaoGerador

"OrgaoGerador": { "CodigoMunicipio": "3106200", "Uf": "MG" }

• Recomendado informar CodigoMunicipio (IBGE) do local de emissão.

Regras de negócio importantes (e erros comuns)

1) Simples Nacional x Regime de Apuração (E0166)

• Se OptanteSimplesNacional = "3" (ME/EPP), envie RegimeApuracaoSN ("1", "2" ou "3").
• Ausência desse campo causa rejeição E0166.

2) Endereço do prestador (E0128)

• Quando o próprio prestador emite a DPS, não se informa endereço do prestador no XML nacional. No seu JSON pode vir, mas o nosso emissor ignora para evitar E0128.

3) Grupo de tributos para ME/EPP (E0712)

• Para ME/EPP, apenas um dos grupos de totais é permitido no XML (vTotTrib ou pTotTrib ou pTotTribSN).
• Nosso emissor envia pTotTribSN (mínimo), evitando conflito.

4) Estrutura trib no XML (RNG9997)

• O Nacional exige a sequência trib/tribMun, trib/tribFed e trib/totTrib.
• Mesmo que tribFed não tenha valores, o bloco deve existir.
• Faltas nessa sequência geram RNG9997 – Erro de esquema.

5) Código municipal do serviço – CodigoTributacaoMunicipio

• Esse código é da prefeitura (não é o da LC 116). Ex.: em Belo Horizonte a linha equivalente a “Outros serviços de processamento de dados” usa "004".
• Como o cliente encontra: consultar a tabela de serviços/códigos de tributação publicada pela prefeitura do município de incidência (site da SEFAZ/finanças municipal ou manual do contribuinte). Cada cidade tem seus códigos e descrições.

6) ItemListaServico (6 dígitos)

• Deve representar o item nacional (LC 116) no formato sempre com 6 dígitos (ex.: "010301"). Nosso emissor valida esse comprimento.

7) pAliq (alíquota municipal)

• Só incluímos pAliq no XML quando Não Optante (OptanteSimplesNacional = "1") e RegimeEspecialTributacao = "0".
• O valor vem de Valores.Aliquota, que pode ser percentual (ex.: "6") ou decimal ("0.06").

Exemplo completo – ME/EPP com retenção

{
  "version": "1",
  "ambiente": "2",
  "DadosNFSE": {
    "Serie": "00900",
    "Numero": 269,
    "DataEmissao": "2025-11-03T10:10:35",
    "NaturezaOperacao": "1",
    "RegimeEspecialTributacao": "0",
    "OptanteSimplesNacional": "3",
    "RegimeApuracaoSN": "2",
    "Competencia": "2025-11-03T10:10:00",
    "OutrasInformacoes": "Teste",
    "Servico": {
      "Valores": {
        "ValorServicos": "0.01",
        "IssRetido": "1",
        "AliquotaRetencao": "0.0201",
        "ValorIss": "0.00",
        "Aliquota": "6",
        "ValorLiquidoNfse": "0.01"
      },
      "ItemListaServico": "010301",
      "CodigoCnae": "6201500",
      "CodigoTributacaoMunicipio": "004",
      "Discriminacao": "NF referente a invoice INV-188813",
      "CodigoMunicipio": "3106200"
    },
    "PrestadorServico": {
      "Cnpj": "34640331000108",
      "InscricaoMunicipal": "11715050015",
      "RazaoSocial": "DILETEC PROCESSAMENTO DE DADOS E SOFTWARE LTDA"
    },
    "TomadorServico": {
      "IdentificacaoTomador": {
        "CpfCnpj": { "Cnpj": "29373005000141" },
        "InscricaoMunicipal": "04276830019"
      },
      "RazaoSocial": "Naldo Sat Ltda",
      "Endereco": {
        "Endereco": "Rua Sergipe",
        "Numero": "34",
        "Complemento": "Loja",
        "Bairro": "Liberdade",
        "CodigoMunicipio": "1501782",
        "Uf": "PA",
        "Cep": "68488000"
      }
    },
    "OrgaoGerador": { "CodigoMunicipio": "3106200", "Uf": "MG" }
  }
}

Exemplo – Não Optante (sem retenção)

{
  "version": "1",
  "ambiente": "1",
  "DadosNFSE": {
    "Numero": 98765,
    "DataEmissao": "2025-11-06T14:22:00-03:00",
    "RegimeEspecialTributacao": "0",
    "OptanteSimplesNacional": "1",
    "Competencia": "2025-11-01",
    "Servico": {
      "Valores": {
        "ValorServicos": "2500.00",
        "IssRetido": "2",
        "Aliquota": "3.5"
      },
      "ItemListaServico": "010302",
      "CodigoTributacaoMunicipio": "123",
      "Discriminacao": "Consultoria em TI",
      "CodigoMunicipio": "3550308"
    },
    "PrestadorServico": {
      "Cnpj": "11222333000144",
      "InscricaoMunicipal": "123456",
      "RazaoSocial": "Empresa ABC Ltda"
    },
    "TomadorServico": {
      "IdentificacaoTomador": { "CpfCnpj": { "Cpf": "12345678901" } },
      "RazaoSocial": "Fulano de Tal",
      "Endereco": { "CodigoMunicipio": "3550308", "Uf": "SP", "Cep": "01001000" }
    },
    "OrgaoGerador": { "CodigoMunicipio": "3550308", "Uf": "SP" }
  }
}

Checklist rápido (evite rejeições)

• ItemListaServico com 6 dígitos.
• CodigoTributacaoMunicipio da tabela municipal de incidência.
• OptanteSimplesNacional corretamente mapeado (1 Não Optante, 2 MEI, 3 ME/EPP).
• Se OptanteSimplesNacional = "3" → enviar RegimeApuracaoSN.
• Para Não Optante sem regime especial → enviar Valores.Aliquota (em % ou decimal) se quiser que pAliq conste na NFS-e.
• CodigoMunicipio (IBGE) sempre 7 dígitos.

Dúvidas frequentes

Onde encontro o CodigoTributacaoMunicipio? Em cada prefeitura, na tabela de códigos/serviços do ISS. Procure por “código de tributação”/“código do serviço” no portal da Secretaria Municipal de Finanças do município de incidência.

Aliquota é em % ou decimal? Aceitamos ambos. Ex.: "6" (6%) ou "0.06". O emissor normaliza automaticamente.

Posso omitir a Serie? Sim. Se omitida, a série padrão do emissor é utilizada.

Tenho retenção pelo tomador. O que envio? Coloque "IssRetido": "2" e, se quiser registrar sua base, use "AliquotaRetencao" (decimal). Essa alíquota não vai para o XML – é informativa/cálculo.

Contato

Se precisar, envie um exemplo do seu JSON que validamos rapidamente antes de integrar.

Diletec
cp.diletec.com.br
31 9 9332-0829