Como interromper e sincronizar notas pelo PlugNotas

A funcionalidade de interromper e sincronizar notas está disponível para ser utilizada tanto via API quanto pela interface web. A seguir, você encontrará detalhes sobre como implementar esses novos recursos.

Interrupção de Notas
A interrupção permite pausar o processamento de uma nota quando há inconsistências ou divergências no retorno da prefeitura. Isso é fundamental para evitar que notas fiquem em estado intermediário (PROCESSANDO/PENDENTE), garantindo a integridade do fluxo de emissão.

Contexto e Importância
O documento NFS-e possui particularidades que exigem atenção constante, devido ao seu dinamismo e à variação entre diferentes prefeituras, principalmente. Os principais pontos de atenção incluem:

• Mudanças no Retorno da Prefeitura: Um dos pontos de atenção e que levam a certo esforço de manutenção, é quando uma prefeitura muda o seu retorno atual, quando devolve um novo retorno ou até mesmo quando o webservice oscila, o que que nos leva a passar por uma readequação de integração com a prefeitura, ou seja, ajustar internamente esses retornos para que nossa produto esteja adaptado.
• Oscilações no Webservice: Instabilidades no serviço da prefeitura podem levar notas a ficarem processando por mais tempo

Quando Utilizar a Interrupção de Notas?
A interrupção é útil nos seguintes cenários:

• Processamento Prolongado: Se uma nota está em processamento por um período excessivo, a interrupção pode ser uma solução para reavaliar a situação. O processamento prolongado pode ocorrer por alguns motivos, como:

  1. Oscilações no Webservice: Quando o serviço da prefeitura apresenta instabilidades, a interrupção evita que as notas fiquem em processamento indefinidamente.

  2. Mudanças no Retorno da Prefeitura: Se a prefeitura altera a estrutura de resposta ou os dados retornados, a interrupção permite que você pause o processamento até que a situação se normalize ou até que nossa equipe técnica realize ajustes e adequações internas para se adaptar a mudança da prefeitura

• Erro na Informação Enviada: Quando um cliente envia várias notas com informações incorretas no JSON, pode ocorrer um cenário em que todas as notas serão rejeitadas com o mesmo erro. Nesse caso, em cidades sequenciais antes de esperar que todas as notas processem uma a uma e sejam rejeitadas, é possível interromper o processamento. Uma informação incorreta no json de envio na NFS-e também pode retornar erros desconhecidos pela prefeitura e as notas podem ficar processando até que a api seja ajustada para o reconhecimento do erro. Se for identificado qual é o campo de ajuste para autorização das nota, elas podem ser interrompidas para serem reenviadas com a informação correta.

  • Atenção: É importante tomar cuidado ao utilizar essa funcionalidade no exemplo citado acima. A interrupção deve ser feita somente quando houver certeza de que a prefeitura rejeitará todas as notas, para evitar duplicidades. Se não houver essa certeza, o melhor a se fazer é permitir que o processo normal de emissão do PlugNotas siga seu curso, rejeitando as notas que forem necessárias e autorizando aquelas que estiverem corretas.

E quando um nota foi interrompida automaticamente pela API?

Isso ocorre quando, no retorno do WebService da prefeitura, é identificada alguma mensagem relacionada à duplicidade de nota, como por exemplo: “Este RPS/DPS já foi utilizado”, e o padrão de integração não disponibiliza um meio de consulta utilizando apenas os dados que a API já possui para realizar a resolução automática da nota.

Nesses casos, a nota é interrompida automaticamente pela API. Essa interrupção tem como objetivo alertar sobre a necessidade de atenção em relação ao registro, pois será necessária uma ação manual para informar algum dado adicional exigido pelo padrão da prefeitura.

Como proceder nesse caso?

1. Verifique manualmente na prefeitura se a nota foi autorizada.

2. Caso a nota encontrada e autorizada seja a mesma enviada pela API, utilize a rota de resolve, informando os dados necessários para o padrão de integração utilizado pela prefeitura.
   ⚠️ Atenção: cada padrão de integração pode exigir informações diferentes para a resolução da nota.

   Para mais detalhes sobre quais dados devem ser informados em cada caso, consulte a documentação específica de Como utilizar a rota Resolve no PlugNotas.

3. Caso a nota encontrada e autorizada não seja a mesma enviada pela API, será necessário corrigir a sequência de RPS/DPS para a numeração correta e reenviar o registro.
   ⚠️ Atenção: O reenvio só é possível quando o campo reenviaNotaInterrompida estiver habilitado no cadastro do prestador.
    

Sincronização de Notas

A sincronização de notas é um processo que pode ser feito para uma nota que está no status INTERROMPIDO, que permite consultar o status atual da NFS-e junto à prefeitura após uma interrupção.

Contexto e Importância

Em um ambiente dinâmico, onde as prefeituras podem alterar o padrão e retornos, a sincronização garante que as informações no PlugNotas estejam atualizadas e corretas.

A importância da sincronização se destaca em diversos aspectos:

• Atualização em Tempo Real: Permite que o PlugNotas tenha acesso às informações mais recentes sobre o status das notas na prefetura, evitando que ações sejam tomadas com base em dados desatualizados.
• Redução de Erros: Ao sincronizar, é possível identificar rapidamente notas que foram rejeitadas ou autorizadas, minimizando o risco de erros no gerenciamento das notas.

Quando Utilizar a Sincronização de Notas
A sincronização de notas deve ser utilizada:

• Após Interrupção: Quando uma nota for interrompida, a sincronização deve ser realizada para verificar o status atual. Depois de determinado tempo ou caso houver confirmação de que a nota está autorizada no portal da prefeitura, execute a ação de sincronização da nota no PlugNotas. Essa sincronização faz com que o PlugNotas consulte o status dessa nota na prefeitura.:
  • Se a nota for rejeitada, o mesmo idIntegracao pode ser reutilizado e outro json pode ser enviado
  • Se a nota for autorizada, siga o fluxo de emissão
  • Caso a prefeitura retornar uma mensagem não tratada ou inesperada, a nota pode se manter em processamento, portanto, interrompa a nota novamente e envie um novo json com um idIntegracao diferente. Posteriormente, pode ser aberto um chamado para nossa equipe realizar um tratamento de readequação do retorno que foi mudada pela prefeitura.

Na prática...

Passo a passo:

1. Interrupção: Se uma nota estiver processando por um período prolongado, recomendamos que ela seja interrompida. Para isto, é necessário adaptar sua aplicação para que receba este novo status. A partir do momento que uma nota foi interrompida, antes de enviar um segundo json com os mesmos dados (tomador e valor) desta primeira, é fundamental que seja realizada a tentativa de sincronização da primeira nota.
2. Sincronização: Depois de determinado tempo ou caso houver confirmação de que a nota está autorizada no portal da prefeitura, execute a ação de sincronização da nota no PlugNotas. Essa sincronização faz com que o PlugNotas consulte o status dessa nota na prefeitura.:
   • Se após a tentativa de sincronização a nota for rejeitada, o mesmo idIntegracao pode ser reutilizado no próximo json a ser enviado
   • Se após a tentativa de sincronização a nota for autorizada, siga o fluxo de emissão das demais notas
   • Se após a tentativa de sincronização, a prefeitura retornar uma mensagem não tratada ou inesperada, a nota pode se manter em processamento, portanto, interrompa a nota novamente e envie um novo json com um idIntegracao diferente. Posteriormente, pode ser aberto um chamado para nossa equipe realizar um tratamento de readequação do retorno que foi mudada pela prefeitura.

Tanto a interrupção quanto a sincronização de notas podem ser feitas tanto via API quanto via interface web:

VIA API

Clique aqui para acessar a documentação das rotas POST e GET para interrupção das notas. É possível interromper até 50 notas por vez. 

Clique aqui para acessar a documentação das rotas POST e GET para sincronização de notas. 

VIA INTERFACE WEB

Interromper:

Ao logar na interface web https://app2.plugnotas.com.br/#/nfse, na seção NFS-e, pesquise o prestador e a nota que deseja interromper. Posteriormente, na nota, identifique o botão , para interromper o processamento. É importante lembrar que, nem todas as notas que estão em PROCESSAMENTO exibirão o botão de interromper, pois, em algumas cidades, esse botão só fica disponível após 5 minutos de processamento da nota.

Sincronizar:

Para sincronizar a nota, identifique o botão "Sincronizar".

Obs.: 

1. Nossa aplicação não permite o envio de uma nota com o mesmo idIntegracao de uma nota que está no status INTERROMPIDO devido ao risco de ocorrer duplicidade de notas, pois existe a possibilidade da primeira nota estar autorizada na prefeitura, sendo necessário sincronizá-la.

2. Conforme mencionado no decorrer da documentação, sua aplicação deve ser adequada para conseguir pegar o novo status do PlugNotas: INTERROMPIDO. Para conferir todos os possíveis status retornados pelo PlugNotas, acesse esta documentação.