Pular para o conteúdo principal

Qual a diferença entre municipalServiceId e municipalServiceCode na emissão de notas fiscais pela API?

Ao agendar uma Nota Fiscal de Serviço (NFS-e) pela API do Asaas, o serviço prestado é informado em um de dois campos: municipalServiceId ou municipalServiceCode. O campo certo depende de a prefeitura disponibilizar uma lista de serviços e de a conta emitir pela prefeitura ou pelo Portal Nacional.

O que é cada campo

CampoO que éQuando usar
municipalServiceIdID interno do Asaas que representa um serviço da lista da prefeitura. É obtido na consulta de serviços municipais (GET /v3/fiscalInfo/services).Quando a conta emite pela prefeitura e a prefeitura disponibiliza a lista de serviços.
municipalServiceCodeO próprio código do serviço, informado manualmente. No Portal Nacional, é o Código de Tributação Nacional (ex.: 01.01.01), seguido do complemento de 3 dígitos quando a prefeitura exigir (ex.: 01.01.01.001).Quando a prefeitura não disponibiliza a lista de serviços ou quando a conta emite pelo Portal Nacional.

Informe apenas um dos dois campos. O municipalServiceName continua obrigatório nos dois casos.

Como saber qual campo usar

Consulte os serviços municipais da conta com GET /v3/fiscalInfo/services:

  • A consulta retornou a lista de serviços: localize o serviço e envie o id retornado no municipalServiceId.
  • A consulta não retornou serviços, ou retornou HTTP 400 com a mensagem “O código de serviços municipais não está habilitado para esta conta.”: envie o código do serviço no municipalServiceCode. Esse retorno indica que a conta emite pelo Portal Nacional ou que a prefeitura não tem lista de serviços.

Exemplo com lista de serviços:

{
  "municipalServiceId": "203561",
  "municipalServiceCode": null,
  "municipalServiceName": "1.01 - Análise e desenvolvimento de sistemas"
}

Exemplo pelo Portal Nacional:

{
  "municipalServiceId": null,
  "municipalServiceCode": "01.01.01",
  "municipalServiceName": "Análise e desenvolvimento de sistemas"
}

O que muda com a migração do Simples Nacional para o Portal Nacional

Em 01/11/2026, as empresas do Simples Nacional que ainda emitem NFS-e pela prefeitura passam a emitir pelo Portal Nacional. A partir da migração:

  • o municipalServiceId deixa de funcionar, porque a lista de serviços não é mais retornada para a conta;
  • as novas notas devem ser agendadas com o municipalServiceCode;
  • os códigos de serviço configurados são apagados, inclusive os das notas agendadas e das assinaturas.

Notas agendadas e assinaturas criadas antes da migração

Em uma nota ou assinatura já criada, o municipalServiceCode não pode ser alterado pela API. Faça o ajuste somente depois da migração, porque os códigos são apagados na virada e um ajuste feito antes se perde:

  • Prefeitura não exige complemento: atualize o Código de Tributação Nacional com o campo federalServiceTaxCode (6 dígitos, ex.: 010101). Para notas, use PUT /v3/invoices/{id}. Para assinaturas, use a configuração de emissão de notas fiscais da assinatura.
  • Prefeitura exige complemento: o federalServiceTaxCode não aceita o complemento. Ajuste o código no cadastro do serviço pela interface web do Asaas, ou cancele e recrie a nota ou a assinatura com o código completo no municipalServiceCode.

Para confirmar se a prefeitura exige complemento e qual é ele, simule uma emissão no Portal Nacional ou consulte a sua contabilidade.

Erro mais comum

“O Código de Serviço municipal deve ser informado para a emissão da Nota Fiscal” (NFe002): o código do serviço não foi enviado ou foi apagado na migração. Em notas novas, envie o municipalServiceCode. Em notas e assinaturas criadas antes da migração, siga as orientações acima.

Saiba mais

Powered by Zendesk