Pular para o conteúdo principal

Inscrições municipais

nfe.municipalTaxes (host api.nfse.io) gerencia as inscrições municipais da empresa — pré-requisito para emissão de NFS-e. Espelha stateTaxes.

Métodos​

MétodoDescriçãoRetorno
list(companyId)Lista as inscrições.{ municipalTaxes, hasMore }
create(companyId, data)Cria uma inscrição.MunicipalTax
retrieve(companyId, municipalTaxId)Consulta por id.MunicipalTax
update(companyId, municipalTaxId, data)Substitui a inscrição (HTTP PUT). Veja abaixo.MunicipalTax
delete(companyId, municipalTaxId)Remove.void
updatePrefecture(companyId, municipalTaxId, data)Descontinuado (@deprecated): a plataforma não serve a rota e responde 404.—
getSeries(companyId, municipalTaxId, serie)Descontinuado (@deprecated): a plataforma não serve a rota e responde 404.—

create, retrieve e update devolvem a própria inscrição. A API responde com o envelope { "municipalTax": {…} }, e o SDK o desembrulha desde a 6.0.1.

Exemplo​

const { municipalTaxes = [] } = await nfe.municipalTaxes.list(companyId);

const created = await nfe.municipalTaxes.create(companyId, {
city: { code: '4106902', name: 'Curitiba' },
taxNumber: '123456',
rpsSerialNumber: 'IO',
environment: 'Development',
});

console.log(created.id);

Atualizar: o PUT substitui a inscrição​

update é um PUT de substituição, não uma atualização dos campos enviados. Segundo a documentação da plataforma (nfe/docs@b9e7953, 14/10/2026):

  • taxNumber omitido é apagado;
  • environment omitido volta para Development;
  • os demais campos omitidos não têm garantia de manter o valor.

O caminho seguro é ler a inscrição, alterar só o necessário e enviar o objeto de volta:

const current = await nfe.municipalTaxes.retrieve(companyId, municipalTaxId);
const { rpsNumber, lastRpsSent, ...rest } = current; // omitidos, o contador de RPS é mantido
await nfe.municipalTaxes.update(companyId, municipalTaxId, { ...rest, issRate: 2.5 });
Não reenvie o contador de RPS

rpsNumber e lastRpsSent omitidos mantêm o contador da série. Um valor enviado sobrescreve o contador, inclusive para trás: reenviar o número lido antes de uma emissão repete números de RPS. Só os envie quando quiser mover o contador de propósito, por exemplo ao trocar de série.

O SDK não mediu esse comportamento por conta própria, porque exigiria escrever sobre uma inscrição real. A fonte é a documentação da plataforma.

Rotas que a plataforma não serve​

updatePrefecture e getSeries estão descontinuados: as rotas .../municipaltaxes/{id}/updateprefecture e .../series/{serie} estão declaradas na OpenAPI, mas a plataforma responde 404, igual ao de um caminho inexistente, inclusive sem credencial (medido em 2026-09-02 e de novo em 2026-10-14). Os métodos continuam emitindo a requisição; o 404 vem com essa explicação. Não há substituto na API hoje.

Próximos passos​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.