Melhorias Xml Center
v2.12.0-r
Apresenta as melhorias estruturais e funcionais implementadas no Xml-Center entre 2024 e 2025, com otimizações em performance, auditoria, conformidade SEFAZ e controle de requisições para download de documentos fiscais eletrônicos.
- Título
- Melhorias Xml Center
- Slug
- melhorias-xml-center
- Sistema(s)
- "XmlCenter [15]"
- Chamado
- "0000542489"
- Categoria
- user_manual
- Tipo
- how-to
- Publico
- "Equipe de suporte e configuração do XmlCenter"
- Keywords
- XmlCenter NSU SEFAZ NF-e CT-e consumo indevido server.ini auditoria reconsulta
- Versão Pipeline
- 2.5.2
- Ultima Revisao
- "2026-06-11"
- Aprovado em
- ""
- Release
- ""
- Autor
- Mauricio Issami Fujimoto
- Setor
- Qualidade
- Modulo
- XML Center
--- title: Melhorias Xml Center slug: melhorias-xml-center sistema: - "XmlCenter [15]" chamado: "0000542489" categoria: user_manual tipo: how-to publico: "Equipe de suporte e configuração do XmlCenter" keywords: - XmlCenter - NSU - SEFAZ - NF-e - CT-e - consumo indevido - server.ini - auditoria - reconsulta versao_pipeline: 2.5.2 ultima_revisao: "2026-06-11" aprovado_em: "" release: "" autor: Mauricio Issami Fujimoto setor: Qualidade modulo: XML Center --- ## Visão Geral Entre 2024 e 2025 o Xml-Center passou por melhorias estruturais e funcionais com foco em performance, estabilidade, auditoria e conformidade com as regras da SEFAZ. As atualizações otimizaram a reconsulta de NSUs (Números Sequenciais Únicos) faltantes, reduziram riscos de consumo indevido, aprimoraram o controle de logs e auditoria, e trouxeram novas parametrizações para maior eficiência operacional. Também foram implementadas melhorias na interface, no controle de limites de requisições e na estabilidade do sistema. ## Pular NSUs não localizados na reconsulta (chamado 0000533743) Verificando os logs, identificou-se que a reconsulta de NSUs faltantes era executada mesmo quando a SEFAZ não localizava o documento, gerando ciclos infinitos sobre os mesmos NSUs. Exemplo de ocorrência nos logs: ``` Verificando NSUs de NF_E_4 faltantes da empresa 0001 Consulta para a empresa "0001" do NSU "344048": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344049": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344050": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344051": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344052": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344053": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344054": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344055": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344056": status :137 - Resposta receita: Nenhum documento localizado. Consulta para a empresa "0001" do NSU "344057": status :137 - Resposta receita: Nenhum documento localizado. Verificação de NSUs de NF_E_4 faltantes da empresa 0001 finalizada ``` Isso **impedia que o processo avançasse**. A rotina foi otimizada: quando a Receita retorna o status 137 (Nenhum documento localizado), **o sistema registra o NSU como "não localizado", ignorando-o em execuções futuras**. Dessa forma obtém-se simultaneamente: a) Uma **auditoria da reconsulta de NSUs faltantes** — é possível visualizar diretamente na tela de NSUs que houve tentativa de reconsulta, mas que a **SEFAZ não localizou o documento**:  b) Uma **otimização na reconsulta de NSUs faltantes** — o sistema não tentará consultar esses NSUs não localizados novamente, **acelerando o processo** ao avançar diretamente para os próximos NSUs. Isso é controlado pela seguinte tag do `server.ini`: ``` CONSULTA_NSUS_FALTANTES_PULAR_NAO_LOCALIZADOS = T ``` Com essa tag ativa, o sistema salva os NSUs não localizados na SEFAZ, **pulando-os nas próximas consultas**, e só tenta reconsultá-los quando não houver mais NSUs faltantes. ## Configurar limite de dias na reconsulta de NSUs faltantes (chamado 0000533743) A SEFAZ só permite a manifestação da **ciência até 10 dias** após a emissão do documento, conforme a NT 2020.001: | Evento | Prazo legal (Ajuste SINIEF 44/20) | |---|---| | Ciência da Emissão | 10 dias contados a partir da data de autorização da NF-e (Nota Fiscal Eletrônica) | | Confirmação da Operação | 180 dias contados a partir da data de autorização da NF-e | | Desconhecimento da Operação | 180 dias contados a partir da data de autorização da NF-e | | Operação Não Realizada | 180 dias contados a partir da data de autorização da NF-e | Fonte: NT 2020.001 Além disso, a SEFAZ **só disponibiliza o XML completo das NF-es** para os destinatários **após a ciência** ser manifestada. Recomenda-se configurar a tag **CONSULTA_NSUS_FALTANTES_LIMITE_DIAS** no `server.ini` com o valor **10**, pois mesmo que o sistema reconsulte um NSU de uma NF-e com mais de 10 dias de emissão, **não será possível** manifestar a ciência e, consequentemente, **não será possível obter o XML completo nem importar o documento**, por conta dessa limitação da SEFAZ. > **Nota:** Esta regra não se aplica a empresas que atuam como **transportadoras** da NF-e, nem a CT-es (Conhecimentos de Transporte Eletrônico), pois somente o destinatário da NF-e precisa manifestar a ciência. Para empresas transportadoras, recomenda-se configurar **90** (últimos 90 dias) na tag **CONSULTA_NSUS_FALTANTES_LIMITE_DIAS**, pois a SEFAZ só disponibiliza documentos até 90 dias após a data de emissão. ## Priorizar NSUs mais recentes na reconsulta (chamado 0000533743) A tag **CONSULTA_NSUS_FALTANTES_ORDEM_DECRESCENTE** no `server.ini` define a ordem de consulta dos NSUs faltantes: ``` CONSULTA_NSUS_FALTANTES_ORDEM_DECRESCENTE = T ``` - **T** — o sistema prioriza os NSUs mais **recentes**. - **F** — o sistema prioriza os NSUs mais **antigos**. De modo geral, recomenda-se deixar esta tag ativa por conta do limite de 10 dias para ciência mencionado anteriormente. ## Usar o ultNSU retornado pela consulta anterior (chamado 0000535931) Identificou-se que consultas realizadas por **chave de acesso** geravam **lacunas nos NSUs**, pois salvavam o NSU no banco de dados de forma isolada. O sistema utilizava o **maior NSU registrado na base** como ponto de partida para a próxima busca, saltando registros intermediários ainda não processados. ### Mudanças realizadas - **Nova origem:** A consulta periódica passou a utilizar o **último NSU retornado pela própria rotina de consulta**, em vez de buscar o maior valor da base. - **Objetivo:** Garantir a continuidade da sequência e evitar a necessidade de reconsultas individuais para preencher lacunas nos NSUs. ## Melhorias na auditoria (chamado 0000534623) ### Reestruturação e gestão de logs A gravação dos logs do Xml-Center foi reestruturada para armazenamento isolado e organizado por hierarquia de modelo, empresa e data:  Nessa pasta `server/log/xml-center` serão armazenados os registros dos últimos **30 dias**. ### Auditoria em CSV Foi implementada a geração de arquivos CSV para auditoria das seguintes rotinas: 1. Consulta de NF-e; 2. Consulta de CT-e; 3. Reconsulta de NSUs faltantes; 4. Download automático. A funcionalidade é controlada pela tag **CONSULTA_DOCS_EMIT_AUDIT** no `server.ini`:  Os arquivos CSV são salvos no mesmo diretório dos logs para facilitar a correlação de dados:  Exemplo do conteúdo do CSV de consulta sequencial de NF-e, com colunas Retorno, Status, ultNSU, maxNSU, indCont, NSU e dhEmi:  Exemplo do conteúdo do CSV de reconsulta de NSUs faltantes, com colunas NSU, id, empresaC, docEData, docEChav, docETipo, docEVers, docEEmite e docESitua:  ### Menu NSUs — visibilidade e status em tempo real O menu NSUs passou a exibir o **último NSU consultado** em comparação ao **último NSU disponível na SEFAZ**, permitindo verificar rapidamente se existem NSUs pendentes: - Se o último NSU consultado for **menor** do que o último disponível na SEFAZ, há NSUs pendentes que serão **automaticamente consultados** na próxima consulta periódica (hora da última consulta + minutos configurados nas tags `CONSULTA_DOCS_EMIT_INTERVALO` e `CONSULTA_DOCS_EMIT_CTE_INTERVALO`). - Se o último NSU consultado for **igual** ao último disponível na SEFAZ, o sistema **consultou todos os NSUs gerados pela SEFAZ** até o momento.  Também foi adicionada a exibição do horário exato da última consulta e do status recebido, permitindo identificar diretamente na tela do Xml-Center se o sistema recebeu consumo indevido da SEFAZ, se encontrou documentos ou se não há mais documentos disponíveis:   ## Corrigir salvamento de NSUs zerados e otimizar listagem (chamado 0000527344) Identificou-se que registros com **NSU zerado** causavam travamentos e falhas na reconsulta. A causa raiz não foi confirmada (suspeita-se de retornos específicos da Receita em consultas por chave). Foram adotadas as seguintes medidas: - **Estabilidade da interface:** A exibição de NSUs faltantes foi limitada a 30 registros, evitando sobrecarga de memória e travamento da tela. - **Correção da reconsulta:** A rotina foi ajustada para ignorar NSUs zerados, focando apenas em sequências válidas. - **Monitoramento e integridade:** Foi bloqueada a sobrescrita de NSUs e configurados alertas no Rocket Chat para notificar imediatamente caso novos registros zerados sejam detectados. ## Marcar manualmente situação de NF-e ou CT-e (chamado 0000534012) Para que o TeoremaEE marque uma NF-e (Nota Fiscal Eletrônica) ou CT-e como cancelada no Xml-Center, é **necessário** que ele receba, pela rotina periódica de consulta de NSU sequencial, **o evento de cancelamento**. Conforme a NT 2014.002 e o MOC da NF-e, quando uma NF-e ou CT-e é cancelada, a SEFAZ gera um NSU do evento de cancelamento, que é recebido pelo Xml-Center durante a consulta periódica e marca o documento como cancelado. Se isso não ocorreu, há duas possibilidades: a) Ocorreu algum erro durante a consulta periódica (erro de rede, caractere não reconhecido no XML, etc.) de modo que o sistema não conseguiu processar o NSU do evento de cancelamento. b) O servidor da SEFAZ não gerou o NSU do evento de cancelamento — já foram observados casos em que todos os NSUs foram corretamente consultados, mas o servidor da SEFAZ não gerou o NSU da nota ou do evento, possivelmente por falha na comunicação entre a SEFAZ estadual do emitente e o servidor da SEFAZ nacional. > ⚠️ **Atenção:** Conforme a NT 2014.002, a **SEFAZ não permite mais de 20 consultas por NSU específico** por hora. Por conta desse limite, pode levar algumas horas até que o sistema reconsulte todos os NSUs dependendo do número total de NSUs faltantes. Foi implementada uma solução paliativa: a marcação manual de uma nota como cancelada diretamente pela interface, por meio do modal de **Ajuste manual**:  ## Consultar ultNSU individualmente ao receber consumo indevido (chamado 0000539661) No chamado 0000535779, o servidor da SEFAZ retornava **consumo indevido** nas tentativas de consulta periódica. A causa identificada foi que o sistema do contador do cliente também consultava na SEFAZ as notas emitidas contra o CNPJ do cliente. Conforme a NT 2014.002, o consumo indevido na consulta sequencial ocorre nas seguintes situações: > 3.11.4.1 - O uso indevido relativo ao Web Service NFeDistribuicaoDFe na consulta com tag:distNSU é baseado nos critérios descritos abaixo: > > 1) Não há mais documentos a distribuir e usuário continua consultando. > > 2) Usuário não está consultando os NSU de forma sequencial: O usuário deve sempre realizar a consulta baseada no ultNsu retornado na consulta anterior, ou seja, deve usar os valores do ultNSU retornados pelo serviço nas chamadas subsequentes. O valor do ultNSU corresponde ao ponto de onde a leitura dos blocos de documentos deve continuar. **Quando ultNSU for igual ao valor do maxNSU retornado pelo serviço, quer dizer que não existem mais documentos para serem recuperados**. Neste caso, para não haver bloqueio por uso indevido, deve-se aguardar 1 hora para realização de novas consultas. > > **Se consultar fora da sequência, será bloqueado. Decorrido o intervalo de tempo, o desbloqueio será automático.** O campo xMotivo traz a seguinte mensagem: "Rejeicao: Consumo Indevido. Deve ser utilizado o ultNSU nas solicitacoes subsequentes. Tente apos 1 hora" > > **Atenção: Se diversas aplicações do mesmo ator** (emitente ou destinatário ou transportador na NF-e ou indicado no campo autxml) **da NF-e efetuarem consultas por NSU para o mesmo CNPJ** (14 dígitos – informado na requisição xml), **essas devem seguir a mesma sequência de numeração ordenada e de forma ascendente. Caso contrário, enquadrar-se-ão na categoria de uso indevido.** Para verificar se outro sistema está buscando XMLs para o mesmo CNPJ, observe nos logs a tag **ultNSU** do XML de retorno da SEFAZ. Se ela for **maior** do que o NSU que o Xml-Center consultou, significa que **outro sistema consultou NSUs para o mesmo CNPJ**. Exemplo — o Xml-Center consultou a partir do NSU **23632** e a SEFAZ retornou: ```xml <retDistDFeInt xmlns="http://www.portalfiscal.inf.br/nfe" versao="1.00"> <tpAmb>1</tpAmb> <verAplic>1.7.5</verAplic> <cStat>656</cStat> <xMotivo>Rejeicao: Consumo Indevido (Deve ser utilizado o ultNSU nas solicitacoes subsequentes. Tente apos 1 hora)</xMotivo> <dhResp>2025-08-26T11:42:53</dhResp> <ultNSU>000000000023636</ultNSU> <maxNSU>000000000000000</maxNSU> </retDistDFeInt> ``` A SEFAZ retornou um `ultNSU` maior (23636), indicando que outro sistema consultou os NSUs 23632 a 23636. Vale ressaltar que a Teorema não possui outros sistemas buscadores de XML além do Xml-Center. Caso exista outro sistema realizando buscas, trata-se de uma aplicação de terceiros. O ideal é que o cliente que usa o Xml-Center **não utilize outros sistemas buscadores de XML para o mesmo CNPJ**, pois se usar, estes terão que seguir a mesma sequência de NSUs, o que só é possível mediante integração entre os dois sistemas. **Caso contrário, a SEFAZ retornará consumo indevido e bloqueará temporariamente o CNPJ do cliente**. Foi implementada uma solução que permite ao cliente utilizar mais de um sistema buscador de XMLs: quando parametrizado, a consulta sequencial do Xml-Center utiliza automaticamente o **maxNSU (último NSU disponível na SEFAZ)** para prosseguir, "pulando" os NSUs que o outro sistema consultou. Os NSUs pulados serão posteriormente **consultados pela reconsulta de NSUs faltantes**. Esse comportamento é ativado pela tag **CONSULTA_NSUS_FALTANTES_USAR_MAX_NSU** no `server.ini`: ``` CONSULTA_NSUS_FALTANTES_USAR_MAX_NSU = T ``` > ⚠️ **Atenção:** Essa solução só funciona se o **fluxo de notas do cliente for relativamente baixo**, pois como serão geradas lacunas intencionais nos NSUs para que a reconsulta as preencha, o Xml-Center conseguirá preencher no máximo 20 NSUs por hora (limite da SEFAZ). Se o cliente tiver mais de 20 notas emitidas contra ele por hora, o processo não conseguirá preencher a fila de NSUs faltantes. Nesse caso, a solução é utilizar apenas o Xml-Center como buscador de XMLs. Portanto, essa tag **só deve ser ativada** em casos onde o cliente use mais de um buscador de XMLs e esteja recebendo consumo indevido na consulta sequencial. ## Guia de configuração das tags de reconsulta de NSUs faltantes (chamado 0000542440) O processo de reconsulta serve para identificar e preencher "lacunas" na sequência numérica dos NSUs (ex.: se a base possui os NSUs 10 e 15, o sistema buscará os registros 11, 12, 13 e 14). ### Tags de controle de execução - **CONSULTA_NSUS_FALTANTES_SERVICE**: Define se o serviço está ativo (**T**) ou inativo (**F**). - **CONSULTA_NSUS_FALTANTES_HORA**: Define a janela de execução (ex.: 20:00-04:00). Recomenda-se rodar à noite pois a SEFAZ limita a **20 consultas por hora** (NSU ou chave). Rodar em horário comercial pode consumir essa cota e impedir que usuários realizem manifestações ou downloads manuais. - **CONSULTA_NSUS_FALTANTES_INTERVALO**: Tempo em minutos entre o início de uma consulta e outra. Se o intervalo for maior que a janela de horas, o sistema executará apenas uma vez por dia. Recomenda-se intervalos de **60 minutos ou mais** para evitar bloqueios da SEFAZ. ### Tags de volume e abrangência - **CONSULTA_NSUS_FALTANTES_QTD**: Quantidade máxima de NSUs consultados por execução. Se a janela for noturna, pode-se usar valores próximos ao limite da SEFAZ (15 ou 20). Se for diurna, recomenda-se valores baixos (5 ou 10). Lógica de fila: se houver 10 NSUs faltantes e a tag for 5, o sistema buscará os 5 primeiros em uma execução e os 5 restantes no próximo intervalo programado. - **CONSULTA_NSUS_FALTANTES_LIMITE_DIAS**: Define a retroatividade da busca (padrão: 10 dias). O limite máximo da SEFAZ é 90 dias. Para destinatários, não costuma ser útil ultrapassar 10 dias; para transportadores, pode-se aumentar até 90 dias. ### Tags avançadas - **CONSULTA_NSUS_FALTANTES_ORDEM_DECRESCENTE (T/F)**: Define se a prioridade é buscar os documentos mais recentes (**T**, padrão) ou os mais antigos (**F**). - **CONSULTA_NSUS_FALTANTES_PULAR_NAO_LOCALIZADOS (T/F)**: Evita que o sistema "trave" tentando consultar repetidamente um NSU que a SEFAZ reporta como inexistente. Se ativada, o sistema pula o registro e avança na fila. - **CONSULTA_NSUS_FALTANTES_USAR_MAX_NSU (T/F)**: Utilizada para contornar erros de consumo indevido em clientes que utilizam dois sistemas de consulta simultâneos. Permite que a reconsulta preencha a base individualmente quando a consulta sequencial é bloqueada. ### Exemplo de fluxo (intervalo de 90 min / janela 20h–04h) 1. **20:00** — 1ª consulta (busca X notas conforme a tag QTD). 2. **21:30** — 2ª consulta. 3. **23:00** — 3ª consulta. 4. Sucessivamente até as **04:00**. Consultas agendadas para após as 04:00 são descartadas até o dia seguinte. Valores padrão recomendados: ``` CONSULTA_NSUS_FALTANTES_SERVICE = T CONSULTA_NSUS_FALTANTES_HORA = 20:00-05:30 CONSULTA_NSUS_FALTANTES_INTERVALO = 71 CONSULTA_NSUS_FALTANTES_QTD = 15 CONSULTA_NSUS_FALTANTES_PULAR_NAO_LOCALIZADOS = T CONSULTA_NSUS_FALTANTES_LIMITE_DIAS = 10 CONSULTA_NSUS_FALTANTES_ORDEM_DECRESCENTE = T ``` ## Implementar evento de ator interessado (chamado 0000501897) Ao clicar nos três pontos de um documento, estão disponíveis as opções:  1. **Copiar chave de acesso**: Ao abrir chamado do Xml-Center para o desenvolvimento, usar este recurso para passar a chave de acesso **como texto em vez de enviar um print**. 2. **Autorizar transportador**: No momento da emissão da NF-e, muitas vezes o emitente ainda não definiu o transportador responsável pela entrega da mercadoria, impedindo que essa informação conste no campo específico da NF-e (tag: CNPJ/CPF, id: X04/X05) ou no grupo de pessoas autorizadas a acessar o XML (tag: autXML, Id: GA01). Em vários outros casos, o responsável pelo transporte é o destinatário, que também não tem condições de informar o transportador no XML da NF-e. **O objetivo deste evento é permitir que o emitente informe a identificação do transportador a qualquer momento, como uma das pessoas autorizadas a acessar o XML da NF-e**. No caso em que o transporte não é de responsabilidade do emitente, o destinatário poderá gerar o evento com o mesmo objetivo. **Nos casos de redespacho ou subcontratação, definido o transportador contratado, este poderá também autorizar outro transportador participante da mesma operação de transporte a acessar o XML da NF-e.** O transportador precisa dos dados da NF-e para instrumentalizar seus processos de transporte e, a partir da geração deste evento, fica autorizado a buscar o XML da NF-e no Ambiente Nacional. Fonte: NT 2014.002 Essa ação também pode ser feita **em massa** selecionando vários documentos e usando o botão de chave na toolbar:  ## Adicionar menu Limites com informações de requisições (chamado 0000535924) Para facilitar o entendimento sobre o limite de consultas por NSU ou chave de acesso, foram implementadas as seguintes melhorias: O sistema passou a registrar a **origem de cada consulta** salva. Agora, as consultas são acompanhadas por descrições que indicam se partiram: a) da reconsulta de NSUs faltantes; b) da consulta manual por chave; c) da tentativa de download após a ciência; ou d) da busca por notas manifestadas sem XML. O menu **Limites** foi disponibilizado no front-end do Xml-Center:  Nessa tela são exibidas as consultas realizadas filtradas pela empresa logada, com as colunas Data e Hora, Origem, Payload e Usuário:  Assim é possível visualizar as consultas individuais realizadas e identificar o que fez com que o limite de 20 consultas por hora fosse atingido — se foi por algum processo automático ou pela ação de algum usuário. ## Otimizar consulta de documentos emitidos contra a empresa (chamado 0000542139) A lista de documentos emitidos contra a empresa (menu Documentos do Xml-Center) demorava para carregar e em casos extremos causava travamentos e erros no servidor. A consulta foi otimizada e agora carrega significativamente mais rápido, mesmo para grandes volumes de documentos. Exemplos de tempos medidos após a otimização: | Número de documentos consultados | Tempo em segundos | |---|---| | 241 | 0.073 | | 869 | 0.262 | | 1511 | 0.582 | | 2027 | 1.147 | | 3210 | 1.828 | | 7114 | 3.576 | ## Informações do documento > Autor: Mauricio Issami Fujimoto > > Setor: Qualidade > > Módulo: XML Center > > Chamado: 0000542489 > > Versão do Sistema: > > Versão do documento: 01 > > Revisão: Paulo Bley > > Aprovado em: 02/2026 --- > 📎 **Arquivos originais:** [Melhorias Xml Center.docx](https://drive.google.com/uc?export=download&id=1Mk_76AC8TSMb42ZKTdslyliq2_FIVd6C) · [Melhorias Xml Center.pdf](https://drive.google.com/uc?export=download&id=1lZx8WTl8BfKr4FHeC71nryAr0abgYJHU)
Tags IA:
center
melhorias
melhorias-xml-center
xml
Prioridade: 7