# XPath > XPath é uma linguagem de consulta usada para localizar e extrair informações dentro de documentos XML. Ela descreve caminhos entre elementos e atributos, como um endereço de pastas no computador. Em documentos fiscais eletrônicos, como NF-e, CT-e e MDF-e, serve para ler dados específicos, como a chave de acesso, o CNPJ do emitente ou o valor total. **Também conhecido como:** XML Path Language, Linguagem de caminhos XML, Expressão XPath **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## 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. ## Perguntas frequentes ### XPath é uma linguagem de programação? Não. XPath é uma linguagem de consulta para navegar em documentos XML. Ela é usada dentro de linguagens de programação, como Java, JavaScript, Python ou C#, por meio de bibliotecas que interpretam as expressões e devolvem os valores encontrados. ### Por que minha expressão XPath não retorna nada no XML da NF-e? Na maioria dos casos, o motivo é o namespace padrão do documento. É preciso registrá-lo na biblioteca com um prefixo ou usar a função local-name() na expressão para que os elementos sejam encontrados. ### XPath funciona com JSON? Não diretamente. XPath foi criado para XML. Para consultar JSON existem outras linguagens com propósito semelhante, como JSONPath, que seguem a mesma ideia de descrever caminhos até um dado. ### Posso usar XPath para alterar um XML assinado? O XPath pode localizar o campo, mas qualquer alteração no conteúdo assinado de um documento fiscal invalida a assinatura digital. Documentos autorizados não devem ser modificados; correções seguem os eventos fiscais previstos. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Namespace XML](https://conota.dev/glossario/namespace-xml.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Leiaute fiscal](https://conota.dev/glossario/leiaute-fiscal.md) - [Importação de XML fiscal](https://conota.dev/glossario/importacao-de-xml-fiscal.md) - [Distribuição de DF-e](https://conota.dev/glossario/distribuicao-de-df-e.md) --- Fonte: [XPath](https://conota.dev/glossario/xpath/) · Atualizado em 2026-10-22