Como consultar municípios com instabilidade na emissão de NFS-e pelo PlugNotas

O PlugNotas conta com mecanismos automáticos de monitoramento e tratamento de instabilidades nos serviços de emissão de NFS-e das prefeituras.

Esses mecanismos permitem identificar situações em que os serviços municipais apresentam falhas de comunicação, indisponibilidade ou comportamento instável, aplicando tratamentos para reduzir os impactos no processamento das notas fiscais.

Neste artigo, explicamos como utilizar essas consultas e interpretar os resultados. A seguir, você encontra:

1. Como funciona o tratamento de instabilidades?
2. Como consultar municípios com instabilidade?
   1. Consultar todos os municípios com instabilidade
   2. Filtrar municípios por situação
3. Como consultar a situação de um município específico?
4. Como interpretar as situações retornadas?
5. Como saber se a emissão está liberada?
6. Quais outras informações estão disponíveis?
7. Como utilizar essas informações na sua aplicação?
8. Documentação técnica
9. Considerações importantes

1. Como funciona o tratamento de instabilidades?

O PlugNotas monitora continuamente o comportamento dos serviços de emissão das prefeituras.

Quando identifica instabilidades, a plataforma pode aplicar medidas automáticas de controle do processamento, buscando evitar que problemas em determinado município prejudiquem as emissões realizadas em outras cidades.

Dependendo da situação identificada, as notas fiscais podem apresentar maior tempo de processamento ou, em situações específicas, ter seu envio temporariamente interrompido.

Quando os serviços municipais voltam a apresentar condições adequadas, o processamento pode retornar automaticamente ao fluxo habitual.

Importante: essas medidas não significam necessariamente que existe um problema na sua integração. Elas podem decorrer de dificuldades de comunicação ou indisponibilidade dos serviços mantidos pelas próprias prefeituras.

2. Como consultar municípios com instabilidade?

O PlugNotas disponibiliza duas formas de consulta:

• Consulta geral: retorna os municípios que apresentam alguma situação de alerta.
• Consulta individual: permite verificar a situação de um município específico por meio de seu código IBGE.

Ambas as consultas utilizam o método GET e exigem autenticação por meio da sua chave de API (x-api-key).

2.1. Consultar todos os municípios com instabilidade

Endpoint:

GET /nfse/cidades/status

Essa consulta retorna os municípios que apresentam alguma situação de alerta no momento.

Municípios operando normalmente não aparecem na lista.

Exemplo de requisição:

curl --request GET \
  --url 'https://api.plugnotas.com.br/nfse/cidades/status' \
  --header 'x-api-key: SUA_API_KEY'

Exemplo de resposta:

{
  "atualizacao": "2026-09-15T10:40:22-03:00",
  "cidades": [
    {
      "codigoIbge": "4113700",
      "cidade": "Londrina",
      "uf": "PR",
      "situacao": "INTERROMPIDA",
      "emissao": "RECUSADA",
      "mensagem": "A emissão de NFS-e pelo emissor municipal encontra-se temporariamente interrompida.",
      "motivo": "Webservice da prefeitura fora do ar",
      "desde": "2026-09-15T09:15:00-03:00",
      "previsao": "2026-09-20T12:00:00-03:00"
    }
  ]
}

Os dados apresentados são ilustrativos, baseados nos exemplos da documentação.

Filtrar municípios por situação

É possível utilizar o parâmetro opcional situacao para consultar apenas municípios que estejam em determinada condição.

Exemplo: consultar somente municípios com emissão interrompida.

GET /nfse/cidades/status?situacao=INTERROMPIDA

Os valores aceitos são:

• INTERROMPIDA
• INSTAVEL
• MONITORADA

3. Como consultar a situação de um município específico?

Para consultar um município individualmente, utilize seu código IBGE.

Endpoint:

GET /nfse/cidades/status/{codigoIbge}

Substitua {codigoIbge} pelo código IBGE do município desejado, composto por sete dígitos.

Exemplo: consultar Maringá/PR.

curl --request GET \
  --url 'https://api.plugnotas.com.br/nfse/cidades/status/4115200' \
  --header 'x-api-key: SUA_API_KEY'

Exemplo de resposta:

{
  "codigoIbge": "4115200",
  "cidade": "Maringá",
  "uf": "PR",
  "situacao": "INSTAVEL",
  "emissao": "LIBERADA",
  "mensagem": "A prefeitura desta cidade está com instabilidade. Você pode emitir NFS-e, mas o processamento pode demorar.",
  "desde": "2026-09-15T08:02:10-03:00",
  "atualizacao": "2026-09-15T10:40:22-03:00"
}

Nesse exemplo, o município apresenta instabilidade, mas a emissão de notas permanece liberada.

Isso significa que as requisições continuam sendo aceitas, embora possam apresentar maior tempo de processamento.

4. Como interpretar as situações retornadas?

A API pode retornar quatro situações:

🟢 NORMAL

Nenhuma instabilidade está registrada para o município.

A emissão segue o funcionamento habitual.

Essa situação aparece somente na consulta individual de um município.

🟡 MONITORADA

O município começou a apresentar falhas e está sendo acompanhado pelos mecanismos automáticos do PlugNotas.

A emissão permanece liberada, sem alteração no fluxo habitual de recebimento das requisições.

🟠 INSTAVEL

O serviço da prefeitura apresenta instabilidade.

A emissão permanece liberada, mas o processamento e a autorização das notas podem demorar mais do que o habitual.

🔴 INTERROMPIDA

A emissão pelo serviço municipal está temporariamente interrompida.

Nessa condição, novas requisições de emissão pelo emissor municipal são recusadas enquanto a interrupção estiver vigente.

Importante: empresas configuradas para utilizar o emissor da NFS-e Nacional não são afetadas por essa condição de interrupção do emissor municipal.

Municípios migrados para o emissor nacional não aparecem como interrompidos nessas consultas.

5. Como saber se a emissão está liberada?

Além do campo situacao, a API retorna o campo emissao, que indica se novas requisições de emissão são aceitas naquele momento.

Os valores possíveis são:

O retorno RECUSADA ocorre somente quando a situação é INTERROMPIDA.

Atenção: o campo emissao indica se a plataforma aceita novas requisições, não representa uma garantia de autorização imediata pela prefeitura.

6. Quais outras informações estão disponíveis?

Dependendo da situação, a resposta também pode apresentar:

Atenção à atualização das informações

As situações são verificadas periodicamente.

Por isso, pode existir uma pequena diferença entre o momento da consulta e a situação efetiva do serviço municipal.

O campo atualizacao permite identificar quando a informação foi apurada.

7. Como utilizar essas informações na sua aplicação?

As consultas podem ser utilizadas para melhorar a experiência dos usuários da sua aplicação.

Alguns exemplos:

Antes de enviar uma nota fiscal

Consultar a situação do município para identificar se existe alguma instabilidade conhecida.

Ao identificar demora na autorização

Verificar se o município está classificado como INSTAVEL, ajudando a compreender possíveis atrasos no processamento.

Para comunicar seus clientes

Utilizar as informações retornadas para apresentar avisos sobre municípios com instabilidade ou emissão interrompida.

Para acompanhar municípios específicos

Consultar periodicamente as cidades mais utilizadas pela sua operação.

Essas possibilidades permitem oferecer maior transparência sobre as condições de emissão, sem depender exclusivamente da abertura de chamados de atendimento.

8. Documentação técnica

Para consultar todos os detalhes de implementação, parâmetros, estruturas de resposta e possíveis retornos da API, acesse a documentação oficial do PlugNotas:

Documentação técnica: docs.plugnotas.com.br

No menu Auxiliares, estão disponíveis as operações:

• Consultar cidades com instabilidade
• Consultar situação de uma cidade

9. Considerações importantes

As consultas apresentam as situações identificadas pelos mecanismos de monitoramento do PlugNotas e não substituem a verificação do retorno individual de cada nota fiscal.

Uma cidade classificada como NORMAL pode apresentar falhas pontuais que ainda não tenham sido identificadas pelo monitoramento.

Da mesma forma, uma cidade classificada como INSTAVEL pode continuar autorizando notas, embora exista possibilidade de lentidão.

O objetivo do recurso é ampliar a transparência e permitir que sua aplicação identifique situações conhecidas que possam afetar a emissão de NFS-e.