XPath

Como funciona o XPath?

Um arquivo XML é organizado como uma árvore: há um elemento principal que contém outros elementos, que por sua vez contêm outros, e assim por diante. O XPath permite descrever o caminho até um ponto específico dessa árvore, separando cada nível por uma barra, de forma parecida com o caminho de uma pasta no computador.

Por exemplo, a expressão /nfeProc/NFe/infNFe/ide/nNF significa: comece no elemento nfeProc, entre em NFe, depois em infNFe, depois em ide e pegue o elemento nNF, que guarda o número da nota. Já o símbolo @ indica um atributo, como em infNFe/@Id, que retorna o identificador do grupo, formado pelo prefixo NFe seguido da chave de acesso.

O XPath também aceita atalhos e filtros. Duas barras (//) procuram um elemento em qualquer nível do documento, e colchetes permitem filtrar resultados, como escolher apenas o primeiro item de uma lista ou apenas os itens que atendem a uma condição.

Para que serve o XPath em documentos fiscais?

Os documentos fiscais eletrônicos brasileiros são transmitidos e armazenados em XML, seguindo leiautes definidos pelos órgãos autorizadores. Quando um sistema precisa ler informações desses arquivos, o XPath é uma forma direta de chegar ao dado certo sem percorrer o documento inteiro manualmente.

Usos comuns incluem: extrair o CNPJ do emitente e do destinatário ao importar notas de fornecedores, conferir o valor total e os impostos para conciliação, ler o código de status e o número do protocolo de autorização, e listar os produtos de uma nota para dar entrada no estoque de um ERP.

Também é útil em testes automatizados e auditorias, para verificar se um XML gerado contém os valores esperados nos campos corretos.

Por que o namespace atrapalha consultas XPath na NF-e?

Os XMLs de NF-e, NFC-e, CT-e e MDF-e declaram um namespace padrão, que é uma espécie de sobrenome aplicado a todos os elementos. No caso da NF-e, esse namespace é http://www.portalfiscal.inf.br/nfe. Por causa dele, uma expressão XPath simples como /nfeProc/NFe costuma não encontrar nada, mesmo que o elemento esteja lá.

Há duas saídas usuais. A primeira é registrar o namespace na biblioteca que executa o XPath, associando-o a um prefixo (por exemplo, nfe) e escrevendo /nfe:nfeProc/nfe:NFe. A segunda é usar a função local-name(), como em //*[local-name()='nNF'], que ignora o namespace e compara apenas o nome do elemento. A primeira é mais precisa; a segunda é mais prática para consultas rápidas.

Qual a diferença entre XPath e Esquema XML?

O Esquema XML (XSD) define as regras do documento: quais elementos podem existir, em que ordem, com quais tipos de dado e tamanhos. Ele é usado para validar se um XML está correto antes ou durante o envio ao órgão autorizador.

O XPath não valida nada. Ele apenas aponta e lê partes de um XML que já existe. Em resumo, o esquema responde à pergunta "este documento está no formato certo?", enquanto o XPath responde "onde está e qual é o valor deste campo?".

Preciso usar XPath se a integração fiscal é feita por API em JSON?

Nem sempre. Em uma emissão fiscal por API, o sistema geralmente envia os dados em JSON e recebe de volta o status, a chave de acesso e outros dados já estruturados, sem precisar ler o XML para isso.

O XPath continua útil quando o sistema precisa trabalhar com o próprio arquivo XML: ao importar notas recebidas de terceiros, ao processar documentos obtidos pela distribuição de DF-e, ao reconciliar arquivos guardados ou ao extrair um campo que não foi devolvido no retorno da API.

Exemplos de XPath

• Um ERP importa o XML de compra enviado por um fornecedor e usa a expressão //nfe:emit/nfe:CNPJ para identificar automaticamente quem vendeu a mercadoria.
• Uma rotina de conciliação lê //nfe:total/nfe:ICMSTot/nfe:vNF em cada XML autorizado do mês para somar o faturamento e comparar com o financeiro.
• Um sistema de estoque percorre todos os elementos //nfe:det/nfe:prod de uma nota recebida para obter código, descrição (xProd) e quantidade de cada item.
• Um teste automatizado verifica se o elemento //nfe:protNFe/nfe:infProt/nfe:cStat do XML processado contém o código que indica autorização de uso.