Como investigar falhas de schema e estrutura do XML

Para resolver uma falha de schema, identifique a mensagem enviada, selecione o conjunto de schemas aplicável e localize o primeiro campo ou grupo que o validador recusou. A correção deve ser feita no cadastro ou no gerador do emissor. Reenviar o mesmo arquivo ou alterar sua versão à mão costuma repetir o problema.

Este guia serve para NF-e, modelo 55, NFC-e, modelo 65, e suas operações documentadas. Autorização, consulta, inutilização e eventos utilizam mensagens próprias. Comece pelo serviço que falhou, mesmo que todos apareçam na mesma tela do programa.

Entenda o que está sendo verificado

Um XML bem formado segue as regras básicas da linguagem, como abertura e fechamento dos elementos e tratamento dos caracteres reservados. O schema, arquivo XSD, acrescenta o contrato da mensagem: nomes, ordem, tipos, tamanhos, ocorrências e combinações de campos.

Um documento pode ser legível como XML e ainda contrariar o leiaute fiscal. A validação de schema também não comprova que os tributos estejam corretos ou que a assinatura seja válida. São verificações diferentes, previstas separadamente no MOC 7.0, Anexo I, grupos B, D e F e nas especificações XML e XML Schema do W3C.

Preserve a mensagem que realmente saiu

Peça código e descrição completos, serviço, ambiente, UF ou autorizador, horário, modelo e versão do emissor. Guarde a cópia da mensagem transmitida, sem abrir e salvar novamente, além do relatório de validação disponível.

Diferencie a nota isolada, a mensagem de envio e o arquivo de nota processada com protocolo. Esses arquivos têm estruturas e finalidades diferentes. Validar um deles não prova que outro está correto. Na autorização, o schema percorre a mensagem inteira; uma falha dentro de uma nota pode comprometer todo o lote.

Se o aviso veio do próprio programa antes da transmissão, registre isso. Não atribua um cStat da SEFAZ a um erro local que apenas usa uma descrição parecida.

Escolha o schema por serviço e versão

O suporte deve confirmar quatro pontos:

1. Qual operação e elemento raiz são esperados pelo serviço

2. Qual versão de leiaute a mensagem declara

3. Qual pacote oficial de XSD atende àquela versão e ao ambiente

4. Se todos os arquivos e dependências do pacote estão consistentes

A versão da Nota Técnica, o leiaute da mensagem e a versão do programa não são o mesmo número. A declaração XML 1.0 identifica a linguagem. Na autorização, o leiaute 4.00 continua recebendo alterações por Notas Técnicas; ver “4.00” não basta para identificar o conjunto atualizado de campos.

Obtenha os pacotes nos documentos oficiais da NF-e. Evite misturar arquivos avulsos de versões diferentes ou copiar um XSD de outra operação. Uma consulta não recebe automaticamente a versão da nota, e um evento exige o schema correspondente ao seu tipo e à sua versão.

As datas também importam. O comunicado ENCAT de 05/10/2026 adiou as implantações anunciadas das NTs 2025.002 v1.52, 2026.007 v1.10 e 2026.008 v1.00 para 26/10/2026 em homologação e 16/11/2026 em produção. Em 09/10/2026, essas datas ainda são futuras. O aviso não suspende todas as regras anteriores dessas famílias. Comunicado oficial.

Transforme a mensagem do validador em uma verificação

Elemento inesperado: confira o caminho completo e os elementos anteriores. O campo apontado pode estar correto, mas ter aparecido antes de outro obrigatório. A ordem do leiaute deve ser preservada pelo gerador.

Conteúdo inválido: compare o valor com o tipo, o tamanho e as restrições do campo. Separador decimal, quantidade de casas, data, identificador e domínio de códigos precisam seguir a especificação. Não preencha um valor inventado apenas para satisfazer o teste.

Elemento obrigatório ausente: procure a origem da informação e a condição que tornou o grupo necessário. Uma tag vazia pode continuar inválida. A presença de um grupo também pode tornar obrigatórios campos que não existiriam fora dele.

Elemento raiz ou namespace desconhecido: confira se o arquivo e o schema pertencem à mesma mensagem. Nos dados fiscais, o namespace padrão é http://www.portalfiscal.inf.br/nfe; ele identifica o vocabulário XML e não é o endereço do Web Service. Preserve separadamente o namespace da assinatura. MOC, Visão Geral, seção 4.2.1.

Falha de leitura ou codificação: verifique os bytes e a estrutura antes de interpretar as mensagens seguintes. Acentos são representáveis em UTF-8. Caracteres reservados exigem representação correta, e trocar somente a palavra “encoding” não converte um arquivo.

A TecnoSpeed relaciona nomes, formatos e campos ausentes entre as causas investigáveis. Use esses indícios com o relatório concreto, sem fazer uma limpeza indiscriminada de espaços ou caracteres.

Use o código para seguir o artigo certo

• 243: leitura de XML malformado

• 215 e 225: falhas de schema, conforme o serviço; a 225 da autorização pode alcançar conteúdo dentro da nota

• 493: schema específico de detEvento, escolhido por tpEvento e verEvento

• 239: versão não suportada no contexto técnico correspondente

• 402: codificação diferente de UTF-8

• 404 e 587: verificações distintas de prefixo e namespace

Consulte os artigos desses códigos para condições e exceções. O número precisa vir acompanhado da mensagem e da operação: a consulta pública pode reutilizar códigos com outro significado.

A Omie documenta ocorrências de 215 em eventos. Isso reforça a necessidade de identificar a mensagem. Não atribua toda falha de evento à 215, pois o conteúdo específico tem a validação 493. Uma tentativa de cancelamento rejeitada não cancela a nota original.

Exemplo hipotético

Uma empresa muda seu integrador. A consulta de situação continua funcionando, mas a autorização começa a falhar. O relatório do XSD aponta que, dentro de prod, encontrou NCM quando esperava xProd. O suporte identifica que a rotina deixou de gerar a descrição obrigatória do produto.

A equipe recupera a descrição verdadeira na origem, corrige o gerador e valida a mensagem completa. Depois, o emissor produz uma nova assinatura e envia a tentativa corrigida. Mudar a numeração, substituir o certificado ou remover NCM não resolveria a omissão identificada.

Valide novamente e confirme o resultado fiscal

Após corrigir a primeira causa, valide novamente: outros erros podem estar encobertos. Compare o arquivo testado com o efetivamente enviado. Essa rastreabilidade importa quando há integrações intermediárias.

A InvoiSys mostra a utilidade de localizar o campo pelo relatório de validação. Prefira uma ferramenta local ou um canal autorizado. Na validação local, bloqueie entidades externas. XMLs contêm dados pessoais e comerciais; não os envie a validadores desconhecidos. Uma cópia anonimizada ajuda na conversa, mas sua alteração impede usá-la para comprovar a assinatura do original.

Não repare manualmente o XML assinado. Ajuste sua origem, gere novamente a mensagem rejeitada e confira estrutura e assinatura antes da transmissão. Preserve documentos autorizados. Se uma tentativa ficou sem resposta, consulte a situação antes de repetir.

Ao final, confira o resultado individual da nota ou do evento e guarde o protocolo aplicável. Passar no XSD é uma etapa técnica; a confirmação depende do serviço fiscal.

Revisão documental: 09/10/2026. O exemplo é didático, baseado no leiaute de produtos; não foi transmitido. Datas, pacote e regras devem ser reconferidos quando o guia for utilizado após novas publicações.