Variáveis no fluxo de processamento de uma NFS-e entre PlugNotas e as Prefeituras

O PlugNotas se comunica com diversas prefeituras no Brasil, atualmente abrangendo mais de 2 mil cidades, com mais de 160 padrões de webservice, além de possibilitar a emissão da NFS-e Nacional.

O cliente PlugNotas integra por meio de um documento JSON, realiza o envio de sua nota e, em seguida, recebe um webhook notificando que sua nota alcançou um status final, ou pode consultar a situação atual da nota. No entanto, uma dúvida comum surge: em quanto tempo terei minha nota processada? A resposta é: DEPENDE. Esse tempo varia de acordo com diversas situações e fatores, considerando a diversidade de prefeituras e os diferentes padrões que possuem webservices distintos e fluxos variados.

Nessa documentação, iremos detalhar questões que podem interferir na forma em que uma nota é processada. É fundamental que esta documentação seja lida por cada cliente PlugNotas antes de iniciar a integração, a fim de garantir a compreensão dos pontos de atenção relacionados ao processamento de uma NFS-e, entre PlugNotas e prefeitura.

Tipos de envios aceitos pelas Prefeituras

O PlugNotas estabelece uma comunicação eficiente com as prefeituras. Porém, cada uma possui características distintas no processamento de notas e nos métodos disponíveis. Abaixo, apresentamos os tipos de fluxo que cada prefeitura pode vir a ter:

Fluxo Normal

O fluxo normal refere-se ao método padrão de envio de notas fiscais, onde as notas são processadas sem requisitos especiais ou etapas adicionais. Neste fluxo, as notas são enviadas à prefeitura imediatamente após serem recebidas pela API, garantindo um processamento simples e direto.

Fluxo Normal + Envio em lote

Permite que várias notas sejam agrupadas e enviadas simultaneamente em um único comando. Isso otimiza o processo, reduzindo o tempo necessário para a transmissão de um grande número de notas. Ao enviar em lote, o PlugNotas pode gerenciar a comunicação com a prefeitura de forma mais eficiente, facilitando a emissão e o acompanhamento dos status das notas fiscais. Assim, esse modelo combina a simplicidade do fluxo normal com a conveniência do envio em lote, proporcionando uma solução eficaz. É recomendado que clientes que possuam um alto volume de notas, escolham enviar em lote. Caso desejar priorizar uma nota específica diante da fila de notas a serem processadas, pode ser utilizado o campo envioPrioritario = true no json de envio da nota. 

Fluxo Sequencial

Existem prefeituras que exigem que as notas sejam enviadas uma a uma, para que os RPSs autorizem na sequência correta. Ou seja, se você mandar 50 notas, nós enviaremos uma nota para a prefeitura e depois que ela processar, enviaremos a próxima nota, e assim por diante. Enquanto uma nota aguarda ser processada pela prefeitura, as outras ficam em uma fila interna do PlugNotas. Existem prefeituras que exigem que o fluxo seja sequencial, mas para parte da consulta. Nesse caso ela não valida se o número dos RPS estão na sequência, porém, ela bloqueia se tentarmos fazer mais de uma consulta de nota ao webservice, por isso, essas prefeituras também precisam ser sequenciais. Esse fluxo é o PlugNotas quem controla, o cliente não precisa se preocupar em controlar isto. Pode ser enviado várias notas ao mesmo tempo que o PlugNotas irá enfileirar essas notas para enviar ao webservice, com isso, o cliente pode sentir que suas notas demoram mais processar, isso por conta dessa limitação do webservice e não do PlugNotas. 

Sequencial + Envio em Lote 

As notas são agrupadas em lotes, mas é enviado um lote por vez de uma quantidade pré-determinada de notas e o RPS das notas desse lote precisam sempre estar na sequência correta. Se a prefeitura permitir envio em lote em um fluxo sequencial, é possível autorizar mais notas em um menor tempo. Portanto, se uma prefeitura for sequencial e disponibilizar o envio em lote, o prestador pode ativar essa opção para agilizar suas emissões. Para que o PlugNotas envie em lote para a prefeitura, é necessário que o prestador ative essa opção no cadastro da empresa. Para mais detalhes, acesse nossa documentação. 

Sequencial + Envio em Lote + Múltiplas Séries

As notas são agrupadas em lotes, mas é permitido que mais de uma lote seja processado por vez, afinal, cada lote será enviada em uma série diferente. Os RPS das notas de cada lote, precisam sempre estar na sequência correta. Isso resulta em maior eficiência no processamento, pois a prefeitura pode lidar com múltiplos lotes simultaneamente, aumentando a agilidade nas emissões. Neste caso, o prestador precisa ter cadastrado mais de uma série nas configurações da empresa, para que o PlugNotas possa agrupar cada lote em uma série específica. Para que o PlugNotas envie em lote para a prefeitura em múltiplas séries, é necessário que o prestador ative essa opção no cadastro da empresa. Para mais detalhes, acesse nossa documentação. 

Importante!

• O PlugNotas gerencia todos esses processos internamente, garantindo que a sequência correta seja mantida, aliviando o prestador da preocupação com a numeração. Além disso, caso o prestador esteja com a opção de envio em lote marcada, o próprio PlugNotas irá agrupar essas notas para enviar a prefeitura. Assim, esse fluxo proporciona uma solução otimizada para a emissão de notas fiscais, alinhado as exigências das prefeituras. É importante observar que o prestador não pode escolher qual fluxo utilizar, pois isso depende das regras de cada prefeitura. Para verificar quais fluxos são aceitos por cada cidade, é necessário consumir a rota de consulta de informações específicas de cada cidade.
• Caso o prestador decida controlar a numeração do RPS por conta própria, o PlugNotas deixa de realizar esse controle, e isso também faz com o que o prestador perca um outro tratamento que o PlugNotas realiza: o reenvio automático de notas para determinados erros ou oscilação da prefeitura. Por isso, sempre recomendamos que se utilize a numeração automática do PlugNotas, permitindo que o produto faça os tratamentos necessários e mantenha o controle adequado dos RPS por meio dos seus processos automatizados.

Fluxo de Envio de Arquivo (Upload)

O cliente irá enviar um JSON e o PlugNotas transformará esse JSON em um arquivo específico exigido pela prefeitura. Após a conversão, o prestador deverá pegar o arquivo gerado e realizar o upload manualmente no portal da prefeitura. 

Variáveis Adicionais

Cancelamento via Webservice

Algumas prefeituras permitem o cancelamento de notas pelo webservice, enquanto outras não. Para consultar se a cidade aceita o cancelamento, consulte a rota de cidades. 

Substituição de Notas

Algumas prefeituras aceitam a substituição de notas via webservice, enquanto outras não. Para consultar se a cidade aceita o cancelamento, consulte a rota de cidades.  

Interrupção e sincronização de notas

A interrupção e sincronização de notas são uma funcionalidade do próprio PlugNotas e permite pausar o processamento de uma nota quando há inconsistências ou divergências no retorno da prefeitura para posteriormente sincronizá-las novamente. Isso é fundamental para evitar que notas fiquem em estado intermediário (PROCESSANDO), garantindo a integridade do fluxo de emissão. Para mais detalhes, consulte nossa documentação. 

Agora que compreendemos as variáveis para o processamento das notas com base nas exigências de cada prefeitura, vamos abordar um próximo ponto muito importante.

Tempo médio de processamento

O tempo médio de processamento das notas pode variar de acordo com a cidade e a prefeitura. O PlugNotas normalmente consegue processar as notas entre 20 segundos à 2 minutos. No entanto, consideramos cerca de 3 à 4 minutos como tempo aceitável para autorizar uma nota ou cada lote, levando em conta apenas o tempo de processamento do PlugNotas, sem incluir o tempo de resposta da prefeitura. 

Caso a prefeitura estiver oscilando ou demorando para processar, é possível baixar o histórico de comunicação do PlugNotas com a prefeitura. Essa funcionalidade está disponível tanto pela interface quanto pela API.

VIA INTERFACE WEB

VIA API

• Documentação da rota para baixar o histórico de comunicação de uma nota utilizando um idIntegracao da nota.
• Documentação da rota para baixar o histórico de comunicação de uma nota utilizando um idIntegracao + cnpj.

É importante ressaltar que uma nota pode ser autorizada pela prefeitura em apenas 1 minuto, enquanto o PlugNotas pode levar 3 minutos para processar o retorno, que engloba efetuar o tratamento do XML, atualizar as notas na base, gerar o PDF e o XML, enviar notificações via webhook e enviar o e-mail correspondente.

Portanto, antes de qualquer questionamento à nossa Consultoria Técnica sobre tempo de processamento, é essencial verificar o tempo de resposta da prefeitura por meio do histórico de comunicação e considerar os 3 minutos que o PlugNotas pode levar para concluir a nota.

Obs.: Conforme mencionado anteriormente, quando o fluxo de emissão de notas é sequencial, enviaremos as notas para a prefeitura uma a uma. Isso significa que, após o processamento de uma nota, somente então enviaremos a próxima. Se você enviou 50 notas às 16h, elas serão registradas em nossa base nesse mesmo horário. No entanto, o tempo de processamento exibido na interface começa a contar a partir do momento em que enviamos a nota para a prefeitura.
Dessa forma, é possível que você perceba que a última nota foi enviada há 30 minutos e ainda não foi processada. Isso é normal, pois se trata de um processo sequencial. Além disso, pode acontecer dessa nota processar e o tempo de processamento ficar em apenas 30 segundos. Isso ocorre devido ao fato de que o cálculo do tempo de processamento é feito a partir do envio à prefeitura e não a partir do horário de registro da nota em nossa base. 

Pela interface web é possível verificar o tempo de processamento de cada nota:

Este campo exibe o tempo de processamento total que inclui tanto o tempo do PlugNotas quanto o da prefeitura. Ele não mede o tempo desde o instante em que o cliente enviou a nota para a API, mas sim, o tempo decorrido a partir do momento em que o PlugNotas enviou a nota para a prefeitura até o momento em que recebe o retorno da prefeitura e gere os arquivos requeridos. Portanto, para verificar o tempo da prefeitura, é necessário abrir o histórico e identificar o horário entre as comunicações.

Exemplos:

Exemplo 1: se o tempo total de processamento de uma nota na interface está em 1:30 e no histórico de comunicação da prefeitura for visto que a prefeitura demorou 1 minuto pra processar, isso significa que o PlugNotas levou 30 segundos para processar a parte que cabia a ele, concluindo em um tempo aceitável por parte do produto, pois o processamento dessa nota estava dentro dos 3 minutos previstos.

Exemplo 2: se o tempo de processamento de uma nota estiver em 8 minutos na interface, e for visto no histórico de comunicação que a prefeitura levou 1 minuto pra processar, o Plugnotas levou então 7 minutos para processar a parte que cabia a ele. Nesse caso, o acionamento à nossa Consultoria Técnica passa a ser recomendada para que possamos analisar se existe algum ajuste específico que precisa ser realizado para o caso em questão.

O que fazer quando uma nota está Processando no PlugNotas, mas, ao consultar na Prefeitura, ela já estiver como Autorizada

Quando isso ocorrer, as possíveis causas são:

1 - Lentidão ou falha no retorno do WebService
O que fazer?
Baixando o histórico de comunicação do registro, é possível identificar as tentativas de consulta e os retornos do WebService. Caso o retorno ainda não corresponda à NFSe gerada no portal da prefeitura, é possível que o WebService não tenha recebido o arquivo e, por isso, ainda não tenha respondido à nossa API.

Aguarde alguns instantes e realize a chamada do Resolve.

2 - Mudança no layout de retorno
O que fazer?
Baixando o histórico de comunicação do registro, é possível identificar as tentativas de consulta e os retornos do WebService. Caso o retorno corresponda à NFSe gerada no portal da prefeitura, é possível que o WebService tenha alterado o layout de retorno sem aviso prévio. Dessa forma, nossa API pode não conseguir interpretar o XML de resposta, mantendo o registro em situação intermediária.

Acesse à nossa Consultoria Técnica e reporte o cenário para que nossa equipe possa tratar devidamente o retorno.

3 - Ausência de novas consultas ao WebService por parte da API
O que fazer?
Baixando o histórico de comunicação do registro, é possível verificar se houve ou não novas tentativas de consulta ao WebService. Caso não haja registros de novas consultas, é possível que nossa API tenha encerrado indevidamente o processamento do registro.

Realize a chamada do Resolve e, se o problema persistir, reporte à nossa Consultoria Técnica.