# Glossário de A a Z — letra X > 19 termos. Glossário compacto: https://conota.dev/glossario/llms-full.txt --- # X-API-Key > X-API-Key é o nome de um cabeçalho HTTP usado para enviar uma chave de API em cada requisição, identificando qual sistema está chamando o serviço. Em APIs fiscais, ele permite que um ERP ou plataforma de vendas se autentique para emitir, consultar ou cancelar documentos como NF-e, NFS-e e NFC-e sem precisar de login e senha. **Também conhecido como:** x-api-key, Header X-API-Key, Cabeçalho X-API-Key, Cabeçalho de chave de API, X-API-Key header **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que significa o nome X-API-Key? O nome tem duas partes. API Key é a chave de API, um código longo e secreto que funciona como uma credencial de acesso para sistemas, não para pessoas. O prefixo X- é uma convenção antiga usada para indicar cabeçalhos personalizados, ou seja, que não fazem parte da lista oficial de cabeçalhos do protocolo HTTP. Com o tempo, a comunidade que define padrões da web passou a desaconselhar o uso do prefixo X- em novos cabeçalhos. Mesmo assim, X-API-Key se popularizou tanto que continua sendo um dos nomes mais comuns para transportar chaves de API. Vale lembrar que nomes de cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, então x-api-key e X-API-Key são tratados da mesma forma. ## Como funciona o cabeçalho X-API-Key? Toda requisição HTTP pode levar cabeçalhos, que são informações extras enviadas junto com o pedido. Quando um sistema chama uma API que usa esse padrão, ele inclui uma linha no formato X-API-Key: seguido do valor da chave. O servidor lê esse cabeçalho, verifica se a chave existe, se está ativa e quais permissões ela tem, e só então processa o pedido. Em uma integração fiscal, isso acontece em cada chamada: ao enviar o payload de uma NF-e para emissão, ao consultar o status de uma NFS-e ou ao baixar o XML autorizado. A chave identifica a conta ou o ambiente de quem está fazendo a requisição, o que permite à plataforma saber a quais empresas emissoras aquele sistema tem acesso. ## Para que serve o X-API-Key em uma API fiscal? A principal função é autenticar a comunicação entre máquinas. Um ERP, um marketplace ou um software de gestão não tem uma pessoa digitando senha a cada nota emitida; ele precisa de uma credencial fixa que possa ser usada de forma automática e contínua. O X-API-Key cumpre esse papel de maneira simples. Além de identificar quem chama, a chave costuma estar ligada a permissões e a um ambiente específico. É comum existir uma chave para o ambiente de homologação, usado em testes sem valor fiscal, e outra para o ambiente de produção, onde os documentos têm validade jurídica. Assim, um erro de configuração no teste não gera notas reais. ## Qual a diferença entre X-API-Key e Bearer token? Os dois são formas de enviar credenciais em cabeçalhos, mas seguem lógicas diferentes. O X-API-Key leva diretamente uma chave fixa, geralmente de longa duração, criada em um painel e usada até ser revogada ou trocada. O Bearer token é enviado no cabeçalho Authorization e costuma ser um token temporário, muitas vezes obtido por um fluxo como OAuth 2.0 e com prazo de expiração curto. Na prática, o X-API-Key é mais simples de implementar e muito usado em integrações entre servidores. O Bearer token oferece mais controle em cenários com vários usuários e delegação de acesso. Algumas APIs aceitam apenas um dos modelos; a documentação do serviço define qual deve ser usado. ## Como proteger uma chave enviada no X-API-Key? Quem tem a chave consegue agir em nome da sua empresa, inclusive emitindo ou cancelando documentos fiscais. Por isso, ela deve ser tratada como uma senha. As requisições precisam usar sempre HTTPS, para que o cabeçalho trafegue criptografado, e a chave nunca deve ficar exposta em código de frontend, aplicativos instalados no celular do cliente ou repositórios públicos. Boas práticas incluem guardar a chave em um cofre de segredos ou em variáveis de ambiente do servidor, usar chaves diferentes para cada ambiente e sistema, conceder apenas as permissões necessárias e fazer a rotação periódica, criando uma nova chave e desativando a antiga. Se houver suspeita de vazamento, a chave deve ser revogada imediatamente. ## Exemplos de X-API-Key - Um ERP envia uma requisição POST para o endpoint de emissão de NF-e com o cabeçalho X-API-Key contendo a chave de produção, e recebe de volta o identificador do documento para acompanhar a autorização. - Uma plataforma de vendas on-line consulta periodicamente o status de várias NFC-e, incluindo em cada chamada o cabeçalho X-API-Key para provar que tem acesso àquelas empresas. - Durante os testes de integração, a equipe de desenvolvimento usa uma chave de homologação no X-API-Key para emitir NFS-e sem valor fiscal e validar o fluxo antes de ir para produção. - Após um desenvolvedor sair da empresa, o time de tecnologia gera uma nova chave, atualiza o valor do X-API-Key no servidor do ERP e revoga a chave antiga. ## Perguntas frequentes ### X-API-Key e API Key são a mesma coisa? Não exatamente. API Key é a credencial em si, o código secreto. X-API-Key é o nome do cabeçalho HTTP usado para transportar essa credencial em cada requisição. ### O que acontece se eu enviar a chave errada no X-API-Key? A API normalmente recusa a requisição e retorna um erro de autenticação, como o código HTTP 401. Se a chave for válida mas não tiver permissão para a ação, o retorno costuma ser 403. ### Posso colocar a chave de API na URL em vez do cabeçalho? Não é recomendado. URLs costumam ser gravadas em logs, históricos e ferramentas de monitoramento, o que aumenta o risco de vazamento. Enviar a chave no cabeçalho, sempre via HTTPS, é a prática mais segura. ### Preciso de uma chave diferente para homologação e produção? Na maioria das APIs fiscais, sim. Separar as chaves evita que testes gerem documentos com validade jurídica e facilita o controle de acesso em cada ambiente. ## Termos relacionados - [API Key](https://conota.dev/glossario/api-key.md) - [Header de autenticação](https://conota.dev/glossario/header-de-autenticacao.md) - [Bearer token](https://conota.dev/glossario/bearer-token.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) - [Key rotation](https://conota.dev/glossario/key-rotation.md) - [HTTPS](https://conota.dev/glossario/https.md) --- Fonte: [X-API-Key](https://conota.dev/glossario/x-api-key/) · Atualizado em 2026-10-22 --- # X.509 > X.509 é o padrão internacional que define o formato dos certificados digitais, ou seja, os arquivos eletrônicos que ligam uma identidade, como uma empresa ou um site, a uma chave criptográfica. No Brasil, os certificados ICP-Brasil usados para assinar NF-e, NFC-e, CT-e e MDF-e seguem esse padrão. **Também conhecido como:** Certificado X.509, Padrão X.509, Certificado digital X.509, X.509 certificate **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um certificado X.509? Um certificado X.509 funciona como uma carteira de identidade digital. Ele diz quem é o titular, quem emitiu o documento, até quando ele vale e qual é a chave pública associada a esse titular. Qualquer sistema que receba o certificado consegue ler essas informações e conferir se ele é confiável. O nome X.509 vem de uma recomendação da ITU-T, organismo internacional de padronização em telecomunicações. Por ser um padrão aberto e amplamente adotado, o mesmo formato é usado em sites com HTTPS, em assinaturas de e-mails e em documentos fiscais eletrônicos. A versão usada hoje na prática é a versão 3, que permite incluir campos extras chamados extensões. ## Quais informações um certificado X.509 contém? Os campos principais são: número de série, titular (subject), emissor (issuer), período de validade, chave pública do titular e a assinatura da autoridade certificadora que emitiu o certificado. Nas extensões podem aparecer dados como o uso permitido da chave e, no caso dos certificados ICP-Brasil para empresas, o CNPJ do titular. A chave privada não fica dentro do certificado. Ela é guardada separadamente pelo titular e é usada para assinar. O certificado carrega apenas a chave pública, que permite a qualquer pessoa verificar essa assinatura sem conseguir reproduzi-la. ## Como o X.509 é usado na emissão de documentos fiscais? Ele aparece em dois momentos. O primeiro é a assinatura digital do XML: o emitente assina o arquivo da NF-e, NFC-e, CT-e ou MDF-e com a chave privada, e o próprio certificado X.509 é incluído no XML, dentro do bloco da assinatura, para que a SEFAZ confira quem assinou e se o conteúdo não foi alterado. O segundo é a conexão segura com os servidores do fisco. Os webservices da SEFAZ exigem autenticação mútua (mTLS), em que o sistema emissor apresenta seu certificado X.509 durante a conexão TLS. Na NFS-e, as exigências variam conforme a prefeitura ou o Padrão Nacional. Em uma API fiscal, o sistema do cliente normalmente envia o certificado uma vez, e a plataforma passa a usá-lo automaticamente para assinar e transmitir cada documento, além de avisar quando a validade estiver perto do fim. ## Qual a diferença entre X.509, certificado A1 e arquivo PFX? X.509 é o padrão que define a estrutura do certificado. Certificado A1 é um tipo de certificado ICP-Brasil, no formato X.509, que fica armazenado em arquivo no computador ou servidor, ao contrário do A3, que fica em token ou cartão. Já o PFX (também chamado P12 ou PKCS#12) é o formato de arquivo que empacota o certificado X.509 junto com a chave privada, protegido por senha. Existem ainda outros formatos de arquivo para o mesmo certificado, como PEM (texto) e DER (binário). Eles mudam apenas a forma de gravar os dados, não o conteúdo do certificado. ## Por que a validade e a cadeia de certificação importam? Todo certificado X.509 tem data de início e de fim. Depois de vencido, ele não serve mais para assinar, e a SEFAZ rejeita os documentos. Por isso, acompanhar a data de expiração é uma rotina essencial em quem emite notas. Além disso, a confiança no certificado depende da cadeia de certificação: o certificado da empresa é assinado por uma autoridade certificadora, que por sua vez é reconhecida por uma autoridade raiz. Se algum elo dessa cadeia não for reconhecido ou o certificado tiver sido revogado, a validação falha. ## Exemplos de X.509 - Um ERP envia para a API fiscal o arquivo PFX da empresa em Base64, junto com a senha; a plataforma extrai o certificado X.509 e passa a assinar as NF-e daquele CNPJ. - Ao abrir o XML de uma NF-e autorizada, o desenvolvedor encontra a tag X509Certificate dentro da assinatura, contendo o certificado público do emitente codificado em Base64. - Um marketplace com vários vendedores recebe um alerta no Console de que o certificado X.509 de um dos CNPJs vence em 15 dias e solicita a renovação antes que as emissões sejam rejeitadas. - Durante a integração, uma requisição à SEFAZ falha porque o servidor não apresentou o certificado X.509 do cliente na conexão mTLS. ## Perguntas frequentes ### Todo certificado digital ICP-Brasil é X.509? Sim. Os certificados da ICP-Brasil, sejam A1 ou A3, seguem o padrão X.509 versão 3, com extensões específicas definidas pela infraestrutura brasileira, como a identificação do CNPJ ou CPF do titular. ### Posso compartilhar meu certificado X.509 com outras pessoas? A parte pública do certificado pode circular sem risco, pois ela já vai dentro dos XMLs assinados. O que deve ser protegido é a chave privada e o arquivo PFX com sua senha, que permitem assinar em nome da empresa. ### Como saber até quando meu certificado X.509 é válido? A data de validade fica gravada no próprio certificado e pode ser lida abrindo o arquivo no sistema operacional, com ferramentas como OpenSSL ou no painel da plataforma de emissão que o utiliza. ## Termos relacionados - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Key pair na assinatura digital](https://conota.dev/glossario/key-pair-na-assinatura-digital.md) - [mTLS](https://conota.dev/glossario/mtls.md) - [Keystore de certificados digitais](https://conota.dev/glossario/keystore-de-certificados-digitais.md) - [Key fingerprint de certificado](https://conota.dev/glossario/key-fingerprint-de-certificado.md) --- Fonte: [X.509](https://conota.dev/glossario/x-509/) · Atualizado em 2026-10-22 --- # XML autorizado > XML autorizado é o arquivo eletrônico de um documento fiscal, como NF-e, NFC-e, CT-e, MDF-e ou NFS-e, que já foi validado e aprovado pelo órgão autorizador, como a SEFAZ ou a prefeitura. Ele reúne os dados do documento assinados digitalmente e o protocolo de autorização, servindo como prova oficial e com validade jurídica da operação. **Também conhecido como:** XML de distribuição, XML com protocolo, XML processado, XML da nota autorizada, Authorized XML **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um XML autorizado, na prática? Todo documento fiscal eletrônico nasce como um arquivo XML, um formato de texto estruturado em etiquetas (tags) que organiza informações como emitente, destinatário, produtos ou serviços, valores e impostos. Enquanto esse arquivo não é aprovado pelo órgão responsável, ele é apenas uma proposta de documento. Quando a SEFAZ, a prefeitura ou o ambiente nacional analisa o arquivo, confere as regras e aprova a emissão, ele devolve um protocolo de autorização. O XML original, somado a esse protocolo, forma o XML autorizado. É esse arquivo que vale legalmente como a nota fiscal, e não o papel impresso. Na NF-e, por exemplo, o XML autorizado costuma ser chamado de XML de distribuição, porque é a versão que deve ser entregue ao destinatário e guardada pelas duas partes. ## Qual a diferença entre XML assinado e XML autorizado? O XML assinado é o arquivo que o emitente gerou e assinou com seu certificado digital. A assinatura garante quem enviou e que o conteúdo não foi alterado, mas ainda não significa que o documento foi aceito. O XML autorizado é esse mesmo arquivo depois da aprovação, acompanhado do protocolo com número, data e hora da autorização e o status devolvido pelo órgão. Se o envio for rejeitado, não existe XML autorizado: é preciso corrigir o erro e enviar de novo. ## Qual a diferença entre XML autorizado e DANFE? O XML autorizado é o documento fiscal propriamente dito, em formato digital. O DANFE, assim como o DANFCE, o DACTE e o DAMDFE, é apenas uma representação simplificada em PDF ou papel, usada para acompanhar a mercadoria, facilitar a leitura e permitir a consulta pela chave de acesso ou QR Code. Por isso, guardar só o PDF não substitui o arquivo XML. Em uma fiscalização ou auditoria, o que comprova a operação é o XML autorizado. ## Por que é preciso guardar o XML autorizado? A legislação exige que emitentes e destinatários mantenham os XMLs autorizados pelo prazo previsto em lei, já que eles são usados na escrituração fiscal, na apuração de impostos e como prova em fiscalizações. Perder esses arquivos pode gerar dificuldades para comprovar créditos tributários ou a própria operação. Além da guarda, o emitente normalmente deve disponibilizar o XML autorizado ao destinatário. Muitas empresas compradoras só dão entrada na mercadoria ou aprovam o pagamento depois de receber esse arquivo. ## Como obter o XML autorizado em uma emissão por API? Em uma API fiscal, o sistema da empresa envia os dados da venda, a API monta e assina o XML, transmite ao órgão autorizador e acompanha o processamento. Como a autorização pode levar alguns segundos, é comum o fluxo ser assíncrono: o sistema consulta o status por polling ou recebe um aviso por webhook. No Conota, quando o documento é autorizado, o XML autorizado, o PDF e o status são devolvidos automaticamente ao sistema do cliente e ficam disponíveis para download no Console. Assim, ERPs e plataformas de venda não precisam montar o protocolo nem lidar diretamente com cada SEFAZ ou prefeitura. ## O que acontece com o XML autorizado quando a nota é cancelada? O XML autorizado original não é apagado nem alterado. O cancelamento é registrado como um evento fiscal separado, que também gera seu próprio XML com protocolo. Por isso, para ter o histórico completo de uma nota, é importante guardar tanto o XML autorizado quanto os XMLs dos eventos vinculados a ele, como cancelamento ou carta de correção. ## Exemplos de XML autorizado - Um ERP industrial emite uma NF-e de venda por API, recebe o XML autorizado com o protocolo da SEFAZ e o envia automaticamente por e-mail ao cliente junto com o DANFE. - Uma loja virtual recebe do emissor fiscal o XML autorizado de cada NFC-e e o arquiva por CNPJ para entregar à contabilidade no fechamento do mês. - Uma transportadora consulta o XML autorizado do CT-e para confirmar o protocolo antes de incluir o documento no MDF-e da viagem. - O departamento fiscal de um comprador recusa a entrada de uma mercadoria porque recebeu apenas o PDF do DANFE e solicita ao fornecedor o XML autorizado. ## Perguntas frequentes ### O PDF da nota substitui o XML autorizado? Não. O PDF, como o DANFE, é só uma representação para leitura e acompanhamento. O documento com validade jurídica é o XML autorizado, que deve ser guardado e entregue ao destinatário. ### Como saber se um XML é realmente autorizado? Ele deve conter o protocolo de autorização com número, data e status de aprovação. Também é possível conferir a situação do documento consultando a chave de acesso no portal do órgão autorizador. ### Um XML emitido em homologação é um XML autorizado válido? Não para fins fiscais. O ambiente de homologação serve para testes e seus documentos não têm valor jurídico. Só o XML autorizado no ambiente de produção comprova uma operação real. ### Posso editar um XML autorizado? Não. Qualquer alteração invalida a assinatura digital. Correções devem ser feitas por eventos fiscais, como carta de correção, ou pelo cancelamento e emissão de um novo documento. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Protocolo de autorização](https://conota.dev/glossario/protocolo-de-autorizacao.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Autorização de uso da NF-e](https://conota.dev/glossario/autorizacao-de-uso-da-nf-e.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) - [Download de XML fiscal](https://conota.dev/glossario/download-de-xml-fiscal.md) --- Fonte: [XML autorizado](https://conota.dev/glossario/xml-autorizado/) · Atualizado em 2026-10-22 --- # XML canonicalization > XML canonicalization é o processo que converte um documento XML para uma forma padronizada e única, chamada forma canônica, eliminando diferenças de escrita que não mudam o conteúdo. Ela é essencial na assinatura digital de documentos fiscais eletrônicos, porque garante que emissor e Fisco calculem exatamente o mesmo resumo criptográfico do arquivo. **Também conhecido como:** Canonicalização de XML, Canonização de XML, Forma canônica do XML, Canonical XML, C14N, XML canonicalization **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XML canonicalization? XML canonicalization, ou canonicalização de XML, é um conjunto de regras que transforma um arquivo XML em uma versão padronizada. Dois arquivos que dizem a mesma coisa, mas foram escritos de jeitos diferentes, passam a ter exatamente a mesma sequência de caracteres depois de canonicalizados. Isso é necessário porque o XML permite variações que não alteram o significado dos dados. A ordem dos atributos dentro de uma tag, o uso de aspas simples ou duplas, a forma de escrever uma tag vazia e o tipo de quebra de linha podem mudar sem que a informação mude. Para um computador que compara bytes, porém, essas versões são diferentes. ## Por que a canonicalização é importante para documentos fiscais? Documentos como NF-e, NFC-e, CT-e e MDF-e são arquivos XML assinados digitalmente. A assinatura funciona calculando um resumo criptográfico, chamado hash ou digest, do conteúdo do documento. Qualquer caractere a mais ou a menos gera um hash completamente diferente. Sem canonicalização, uma simples diferença de formatação entre o arquivo gerado pelo emissor e o arquivo lido pelo Fisco faria a assinatura parecer inválida, mesmo sem nenhuma alteração real nos dados. A forma canônica cria um ponto de referência comum: ambos os lados aplicam as mesmas regras antes de calcular o hash e, assim, chegam ao mesmo resultado. ## Como funciona a canonicalização de um XML? O algoritmo aplica regras fixas ao documento. Entre as principais estão: usar a codificação UTF-8, padronizar quebras de linha, ordenar atributos e declarações de namespace de forma definida, usar sempre aspas duplas nos valores, escrever tags vazias com abertura e fechamento separados e remover a declaração inicial do XML. Um ponto que costuma confundir é que a canonicalização não remove espaços e quebras de linha existentes entre as tags, pois eles são tratados como conteúdo. Por isso, os manuais dos documentos fiscais pedem que o XML seja enviado sem formatação extra, e reformatar o arquivo depois de assinado costuma invalidar a assinatura. ## Quais são os tipos de canonicalização? Existem algumas variações definidas por padrões do W3C. A mais conhecida é a Canonical XML 1.0, muitas vezes chamada de C14N. Há também a versão 1.1 e a Exclusive Canonicalization, que trata namespaces de forma diferente e é útil quando um trecho do XML será inserido em outro documento. Cada variação pode ser aplicada com ou sem comentários. Na assinatura de documentos fiscais brasileiros como a NF-e, o padrão adotado é a Canonical XML 1.0 sem comentários, indicada no próprio bloco de assinatura do arquivo. O algoritmo usado precisa ser exatamente o exigido pelo layout do documento. ## Qual a relação entre canonicalização e assinatura digital do XML? Na assinatura digital do XML, a canonicalização aparece em duas etapas. Primeiro, o trecho assinado do documento, como o grupo de informações da nota, é canonicalizado e tem seu hash calculado. Depois, o bloco com as informações da assinatura também é canonicalizado antes de ser assinado com a chave privada do certificado digital. Quando o Fisco recebe o arquivo, refaz o mesmo processo. Se a forma canônica calculada por ele gerar um hash diferente do que está no documento, o arquivo é rejeitado por divergência de assinatura. Esse é um dos erros mais comuns em integrações fiscais feitas do zero. ## Quais erros de canonicalização são mais comuns na emissão fiscal? Os problemas mais frequentes são: formatar ou indentar o XML depois de assinar, alterar a codificação de caracteres, usar uma biblioteca que aplica um algoritmo de canonicalização diferente do exigido, incluir espaços ou quebras de linha dentro dos valores e modificar namespaces ao inserir o XML em um envelope de envio. Em uma API fiscal, normalmente o sistema do cliente envia os dados da venda e a própria infraestrutura de emissão monta, canonicaliza e assina o XML. Isso reduz a chance desses erros, já que o desenvolvedor não precisa lidar diretamente com as regras de canonicalização. ## Exemplos de XML canonicalization - Um ERP gera a NF-e com os atributos de uma tag em uma ordem e, após a canonicalização, eles passam a seguir a ordem padronizada, permitindo que o hash calculado pelo emissor e pela SEFAZ seja idêntico. - Um desenvolvedor assina o XML de um CT-e e, em seguida, usa uma ferramenta que indenta o arquivo para facilitar a leitura. Ao enviar, o documento é rejeitado por assinatura divergente, porque as quebras de linha alteraram a forma canônica. - Uma equipe que integra a emissão de NFS-e com um município verifica no bloco de assinatura do XML qual algoritmo de canonicalização é exigido e configura a biblioteca de assinatura para usar exatamente esse padrão. - Um auditor valida a autenticidade de um XML fiscal baixado: o software de verificação canonicaliza o trecho assinado, recalcula o hash e confirma que ele bate com o valor registrado na assinatura. ## Perguntas frequentes ### O que significa C14N? C14N é a abreviação de canonicalization: a letra C, as 14 letras do meio da palavra em inglês e a letra N. É o nome usado para se referir ao padrão Canonical XML e aos algoritmos de canonicalização. ### A canonicalização altera os dados da nota fiscal? Não. Ela muda apenas a forma de escrever o XML, como ordem de atributos, aspas e codificação. Valores, produtos, impostos e demais informações permanecem exatamente os mesmos. ### Posso formatar o XML de uma NF-e para deixá-lo mais legível? Pode fazer isso apenas em uma cópia para leitura. O arquivo oficial, já assinado, não deve ser reformatado, pois espaços e quebras de linha adicionais mudam a forma canônica e invalidam a assinatura. ### Preciso implementar a canonicalização ao usar uma API fiscal? Em geral, não. Quando a API monta e assina o documento, ela aplica a canonicalização exigida pelo layout. O sistema integrado só precisa enviar os dados corretos e preservar o XML autorizado sem alterações. ## Termos relacionados - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Hash de documento fiscal](https://conota.dev/glossario/hash-de-documento-fiscal.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) --- Fonte: [XML canonicalization](https://conota.dev/glossario/xml-canonicalization/) · Atualizado em 2026-10-22 --- # XML de distribuição de DF-e > XML de distribuição de DF-e é o arquivo de resposta do serviço de Distribuição de Documentos Fiscais Eletrônicos do Ambiente Nacional. Ele entrega à empresa os documentos em que ela aparece como interessada, como NF-e e CT-e emitidos contra seu CNPJ, na forma de resumos, XMLs completos e eventos, cada um identificado por um número sequencial chamado NSU. **Também conhecido como:** XML de retorno da distribuição de DF-e, Retorno do NFeDistribuicaoDFe, XML da distribuição DFe, Lote de distribuição de DF-e **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é o XML de distribuição de DF-e? Quando outra empresa emite uma nota fiscal eletrônica para o seu CNPJ, esse documento fica registrado nos sistemas da administração tributária. O serviço de Distribuição de DF-e permite que você baixe esses documentos sem depender do fornecedor para enviar o arquivo por e-mail. O XML de distribuição é a resposta que esse serviço devolve. Ele funciona como um envelope que contém um ou mais documentos fiscais, compactados e codificados, junto com informações de controle, como o código de status da consulta e a numeração sequencial de cada item. ## Como funciona a estrutura desse XML? A resposta traz um cabeçalho com o resultado da consulta, por exemplo, se foram encontrados documentos ou não, além do último NSU entregue e do maior NSU disponível para aquele CNPJ. Esses números indicam se ainda existem documentos a buscar. Dentro do envelope há um ou mais elementos chamados docZip. Cada um carrega um documento compactado em GZip e codificado em Base64, acompanhado do seu NSU e de um atributo que informa o tipo de esquema do conteúdo. Para ler o documento, o sistema precisa decodificar o Base64 e descompactar o GZip, obtendo então o XML original. ## Que tipos de documento podem vir na distribuição? No caso da NF-e, os tipos mais comuns são o resumo da nota (resNFe), o XML completo com o protocolo de autorização (procNFe), o resumo de um evento (resEvento) e o evento completo (procEventoNFe), como um cancelamento ou uma carta de correção. O resumo traz dados básicos, como chave de acesso, emitente, valor e situação. O XML completo, com todos os itens e impostos, normalmente só fica disponível ao destinatário depois que ele registra uma manifestação, como a ciência da operação. ## Para que serve o XML de distribuição de DF-e? Ele serve para que a empresa saiba quais notas foram emitidas contra seu CNPJ e obtenha os arquivos oficiais para lançar compras, conferir mercadorias, fazer a escrituração fiscal e guardar os documentos pelo prazo exigido. Também ajuda a identificar notas desconhecidas ou indevidas, que podem ser contestadas por meio da manifestação do destinatário, e a acompanhar eventos que alteram a situação de uma nota já recebida, como um cancelamento feito pelo fornecedor. ## Como consultar a distribuição sem ser bloqueado? A consulta pode ser feita a partir do último NSU recebido, por um NSU específico ou pela chave de acesso de um documento. O caminho recomendado é guardar o último NSU processado e continuar a partir dele, pedindo novos lotes até que o NSU retornado alcance o maior NSU disponível. Consultas repetidas sem necessidade, ou reiniciadas do zero com frequência, podem gerar rejeição por consumo indevido e bloqueio temporário. Por isso, quando não houver documentos novos, o ideal é aguardar um intervalo antes de consultar novamente. Uma API fiscal pode automatizar esse controle e entregar ao seu sistema os XMLs já descompactados. ## Exemplos de XML de distribuição de DF-e - Um ERP consulta a distribuição de DF-e a cada hora para o CNPJ de uma indústria, recebe o resumo de uma NF-e de compra de matéria-prima, registra a ciência da operação e, na consulta seguinte, baixa o XML completo para lançar a entrada no estoque. - Uma transportadora usa a distribuição de DF-e para obter os CT-e em que aparece como tomadora, sem precisar pedir os arquivos a cada subcontratada. - Um sistema de gestão recebe um docZip do tipo procEventoNFe, decodifica o conteúdo e descobre que uma nota de fornecedor foi cancelada, bloqueando automaticamente o pagamento da fatura vinculada. - Um marketplace com vários CNPJs mantém o último NSU de cada empresa salvo no banco de dados, retomando a consulta exatamente de onde parou após uma janela de manutenção. ## Perguntas frequentes ### Por que recebi só o resumo da NF-e e não o XML completo? Porque o XML completo costuma ser liberado ao destinatário apenas depois que ele registra uma manifestação, como a ciência da operação. Após a manifestação, o documento completo passa a aparecer em consultas seguintes da distribuição. ### Preciso de certificado digital para baixar o XML de distribuição? Sim. A consulta ao serviço de distribuição é autenticada com o certificado digital da empresa interessada ou de quem tenha autorização para consultar em nome dela, geralmente um certificado A1. ### O que é o NSU nesse XML? NSU é o Número Sequencial Único atribuído a cada documento disponibilizado para um CNPJ. Ele permite saber o que já foi baixado e continuar a consulta a partir do último ponto, sem repetir documentos. ### Por que o conteúdo do docZip parece ilegível? Porque ele está compactado em GZip e codificado em Base64. É preciso decodificar o Base64 e depois descompactar o GZip para obter o XML do documento fiscal em formato legível. ## Termos relacionados - [Distribuição de DF-e](https://conota.dev/glossario/distribuicao-de-df-e.md) - [GZip na distribuição de DF-e](https://conota.dev/glossario/gzip-na-distribuicao-de-df-e.md) - [Manifestação do destinatário](https://conota.dev/glossario/manifestacao-do-destinatario.md) - [Download de XML fiscal](https://conota.dev/glossario/download-de-xml-fiscal.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) --- Fonte: [XML de distribuição de DF-e](https://conota.dev/glossario/xml-de-distribuicao-de-df-e/) · Atualizado em 2026-10-22 --- # XML de evento fiscal > XML de evento fiscal é o arquivo eletrônico, no formato XML, que registra uma ocorrência posterior à emissão de um documento fiscal, como cancelamento, carta de correção, manifestação do destinatário ou encerramento de MDF-e. Assinado digitalmente e vinculado à chave de acesso do documento, ele comprova perante o Fisco que o evento foi enviado e registrado. **Também conhecido como:** XML do evento, Arquivo de evento fiscal, XML de evento da NF-e, procEvento, Tax event XML **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um XML de evento fiscal, em termos simples? Depois que uma nota fiscal eletrônica é autorizada, ela não pode mais ser editada. Se algo precisar acontecer com ela, como cancelar, corrigir uma informação permitida ou registrar que a mercadoria foi recebida, isso é feito por meio de um evento fiscal. O XML de evento fiscal é o arquivo que descreve esse evento. Ele funciona como um anexo oficial do documento original: aponta para a chave de acesso da nota, diz qual evento ocorreu, quando ocorreu e quem o solicitou. Assim, o documento original permanece intacto, e cada mudança fica registrada em um arquivo próprio. ## Quais eventos geram esse tipo de XML? Os eventos variam conforme o documento. Na NF-e, os mais conhecidos são o cancelamento, a carta de correção eletrônica (CC-e) e os eventos de manifestação do destinatário, como ciência da operação, confirmação, desconhecimento e operação não realizada. Na NFC-e, o cancelamento é o evento mais comum. No transporte, o MDF-e tem eventos como encerramento, cancelamento e inclusão de condutor, e o CT-e possui eventos como cancelamento e carta de correção. Na NFS-e, especialmente no Padrão Nacional, também existem eventos, como o cancelamento. Cada evento é identificado por um código próprio definido no leiaute oficial. ## Como funciona o envio e o retorno do XML de evento? O emissor monta o XML com os dados do evento, como a chave de acesso do documento, o tipo de evento, a data e hora, um número sequencial e as informações específicas daquele evento, como a justificativa de um cancelamento. Em seguida, o arquivo é assinado digitalmente com o certificado da empresa e enviado ao órgão autorizador, como a SEFAZ. O órgão valida o arquivo e devolve uma resposta indicando se o evento foi registrado ou rejeitado, com um protocolo em caso de sucesso. A junção do XML enviado com a resposta do Fisco forma o XML de evento processado, que é o arquivo que deve ser guardado como comprovante. ## Qual a diferença entre o XML do documento e o XML do evento? O XML do documento contém a operação em si: emitente, destinatário, produtos ou serviços, valores e impostos. Ele é gerado uma única vez, na emissão, e recebe a autorização de uso. O XML do evento é separado e contém apenas a ocorrência posterior. Um mesmo documento pode ter vários XMLs de evento ao longo do tempo, como várias cartas de correção ou uma manifestação seguida de outra. Para conhecer a situação completa de uma nota, é preciso olhar o XML do documento junto com todos os seus eventos. ## Por que é preciso guardar o XML de evento? O XML de evento processado é a prova legal de que o evento aconteceu. Uma nota cancelada, por exemplo, só se comprova como cancelada com o XML do evento de cancelamento autorizado. Sem ele, a empresa pode ter dificuldade em fiscalizações ou na escrituração. Por isso, a legislação exige que esses arquivos sejam guardados junto com os documentos fiscais pelo prazo previsto, e muitas empresas também os enviam à contabilidade para manter os registros consistentes. ## Como uma API fiscal lida com os XMLs de evento? Em uma emissão fiscal por API, o sistema da empresa normalmente envia apenas uma requisição simples, como pedir o cancelamento de uma nota com a justificativa. A API monta o XML no leiaute correto, assina com o certificado, envia ao órgão autorizador e acompanha a resposta. Depois, a API devolve o status do evento e disponibiliza o XML processado para download ou consulta, além de registrá-lo no histórico do documento. Isso evita que o ERP ou a plataforma de vendas precise lidar diretamente com esquemas XML, assinatura digital e comunicação com cada órgão. ## Exemplos de XML de evento fiscal - Uma loja virtual cancela uma NF-e dentro do prazo permitido porque o cliente desistiu da compra; a API retorna o XML do evento de cancelamento autorizado, que o ERP arquiva junto com a nota. - Uma indústria percebe um erro no endereço do destinatário de uma NF-e já autorizada e emite uma carta de correção eletrônica, gerando um XML de evento com o texto da correção. - Uma transportadora conclui a viagem e envia o encerramento do MDF-e; o XML do evento de encerramento comprova que o manifesto foi finalizado. - Um distribuidor recebe uma NF-e de fornecedor e registra a confirmação da operação, gerando um XML de evento de manifestação do destinatário. ## Perguntas frequentes ### O XML de evento substitui o XML da nota? Não. O XML da nota continua sendo o documento principal. O XML de evento é complementar e deve ser guardado junto com ele, pois mostra o que aconteceu com a nota depois da autorização. ### Todo XML de evento precisa de assinatura digital? Sim. Assim como o documento fiscal, o evento precisa ser assinado com o certificado digital do autor do evento, garantindo autoria e integridade antes do envio ao órgão autorizador. ### Um evento pode ser rejeitado? Sim. Se houver erro de dados, prazo vencido ou situação incompatível, como cancelar uma nota já cancelada, o órgão rejeita o evento e informa o motivo. Nesse caso, não há XML de evento autorizado. ### Onde encontro o XML de eventos de notas recebidas? Eventos relacionados a documentos em que a empresa é parte podem ser obtidos pela distribuição de DF-e, conforme regras de cada documento, ou consultados no histórico da API fiscal utilizada. ## Termos relacionados - [Evento fiscal](https://conota.dev/glossario/evento-fiscal.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Histórico de eventos fiscais](https://conota.dev/glossario/historico-de-eventos-fiscais.md) - [Cancelamento de documento fiscal](https://conota.dev/glossario/cancelamento-de-documento-fiscal.md) - [Manifestação do destinatário](https://conota.dev/glossario/manifestacao-do-destinatario.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) --- Fonte: [XML de evento fiscal](https://conota.dev/glossario/xml-de-evento-fiscal/) · Atualizado em 2026-10-22 --- # XML External Entity > XML External Entity é um recurso da linguagem XML que permite a um documento buscar conteúdo fora dele, como arquivos do servidor ou endereços de rede. O termo também nomeia a vulnerabilidade XXE: quando um sistema lê XML sem proteção, um invasor pode usar esse recurso para ler arquivos internos, acessar redes privadas ou travar o serviço. **Também conhecido como:** Entidade externa XML, Ataque XXE, Vulnerabilidade XXE, Injeção de entidade externa XML, XXE, XML External Entity **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é uma entidade externa no XML? No XML, uma entidade funciona como um apelido que é trocado por um conteúdo quando o documento é lido. Ela é declarada em um trecho opcional no início do arquivo, chamado DTD (Document Type Definition). A entidade é chamada de externa quando esse conteúdo não está escrito no próprio documento. Em vez disso, ela aponta para um caminho de arquivo ou para um endereço de rede. Ao ler o XML, o programa responsável, chamado parser, vai até esse local, busca o conteúdo e o insere no documento. O recurso foi criado para reaproveitar trechos de texto entre documentos. Hoje quase não é usado em integrações comuns, mas muitas bibliotecas de leitura de XML ainda o deixam ativo por padrão. ## Como funciona um ataque XXE? O invasor envia ao sistema um XML com uma entidade externa maliciosa. Ela pode apontar, por exemplo, para um arquivo de configuração do servidor que guarda senhas. Se o parser resolver essa entidade, o conteúdo do arquivo passa a fazer parte do documento e pode aparecer em uma resposta, em um log ou em uma mensagem de erro. A entidade também pode apontar para endereços da rede interna da empresa. Assim, o servidor faz requisições em nome do invasor, que consegue acessar serviços que não estão expostos na internet. Outra variação faz o parser ler recursos que nunca terminam, o que consome memória e derruba a aplicação. ## Por que XXE importa para quem processa XML fiscal? Os documentos fiscais eletrônicos brasileiros, como NF-e, NFC-e, CT-e, MDF-e e muitos padrões de NFS-e, são arquivos XML. ERPs, plataformas de venda e marketplaces leem esses arquivos o tempo todo: ao importar notas de fornecedores, ao receber documentos pela distribuição de DF-e ou ao processar retornos de uma API fiscal. Muitos desses arquivos vêm de terceiros. Um XML enviado por upload em uma tela de importação, por exemplo, pode ter sido manipulado. Se o sistema que o lê não estiver protegido, a importação de uma simples nota pode virar uma porta de entrada para vazamento de certificados digitais, chaves de API ou dados de clientes. ## Como proteger um sistema contra XXE? A medida principal é configurar o parser para não processar DTD nem resolver entidades externas. Os layouts oficiais dos documentos fiscais não dependem de DTD, então rejeitar qualquer XML que traga essa declaração costuma ser seguro e não afeta notas legítimas. Validar o arquivo contra o esquema XML oficial (XSD) ajuda a recusar estruturas inesperadas, mas não basta sozinho, porque a entidade pode ser resolvida durante a leitura, antes da validação. Por isso, a validação deve ser combinada com a configuração segura do parser. Também ajudam manter as bibliotecas de XML atualizadas, limitar o tamanho dos arquivos aceitos, rodar o serviço com o mínimo de permissões possível e restringir o acesso dele à rede interna. ## Qual a diferença entre XXE e outros ataques com XML? O XXE explora entidades que buscam conteúdo fora do documento. Já o ataque conhecido como Billion Laughs usa entidades internas que se repetem umas dentro das outras, fazendo o documento crescer de forma explosiva na memória até travar o sistema. As proteções se sobrepõem: desativar o processamento de DTD bloqueia os dois. A injeção de XML é outro problema: o invasor insere trechos de marcação em campos de texto para alterar a estrutura do documento gerado. Ela se previne tratando corretamente os dados antes de montar o XML, e não na configuração do parser. ## Exemplos de XML External Entity - Um ERP permite que o cliente envie XMLs de NF-e de compra para dar entrada no estoque. Um arquivo adulterado traz uma entidade externa apontando para o arquivo de configuração do servidor, e o conteúdo aparece no campo de observações exibido na tela. - Durante uma auditoria de segurança, a equipe descobre que a biblioteca usada para ler os retornos de NFS-e de prefeituras resolvia entidades externas por padrão e altera a configuração para rejeitar qualquer XML com DTD. - Um marketplace que recebe CT-e de transportadoras parceiras passa a limitar o tamanho dos arquivos e a bloquear declarações de DTD depois que um XML malicioso esgotou a memória do serviço de importação. - Uma software house revisa o código que lê a distribuição de DF-e e acrescenta um teste automatizado que envia um XML com entidade externa para garantir que ele seja recusado. ## Perguntas frequentes ### XXE é um defeito da NF-e ou da SEFAZ? Não. XXE é uma falha na forma como um sistema lê XML. O risco está no software que processa o arquivo, como um ERP ou um importador de notas, quando ele usa um parser mal configurado. ### Validar o XML pelo esquema oficial impede XXE? Não totalmente. A entidade externa pode ser resolvida durante a leitura, antes da validação. A proteção eficaz é desativar o processamento de DTD e de entidades externas no parser, usando a validação por esquema como camada adicional. ### Bloquear DTD pode impedir a leitura de notas fiscais legítimas? Em geral, não. Os layouts oficiais dos documentos fiscais eletrônicos não usam DTD, então um XML fiscal legítimo não precisa dessa declaração para ser lido corretamente. ### Quais sistemas devem se preocupar com XXE? Qualquer sistema que leia XML vindo de fora: importadores de notas de fornecedores, integrações com prefeituras e SEFAZ, serviços de distribuição de DF-e e telas de upload de arquivos fiscais. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.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) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Gerenciamento de segredos](https://conota.dev/glossario/gerenciamento-de-segredos.md) --- Fonte: [XML External Entity](https://conota.dev/glossario/xml-external-entity/) · Atualizado em 2026-10-22 --- # XML fiscal > XML fiscal é o arquivo digital, escrito na linguagem XML, que reúne todas as informações de um documento fiscal eletrônico, como NF-e, NFC-e, NFS-e, CT-e e MDF-e. Depois de assinado digitalmente e autorizado pelo órgão competente, ele é a versão com validade jurídica da nota. O PDF serve apenas como representação visual. **Também conhecido como:** XML da nota fiscal, XML do documento fiscal, XML da NF-e, Arquivo XML da nota, Tax invoice XML **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XML fiscal e por que ele é tão importante? XML é uma linguagem de marcação que organiza informações em etiquetas, chamadas tags, de forma que computadores consigam ler e validar os dados sem ambiguidade. No contexto fiscal, o XML é o formato oficial em que os documentos eletrônicos são criados, transmitidos e armazenados. A importância do XML fiscal está no fato de que ele é o próprio documento. Quando uma NF-e é autorizada pela SEFAZ ou uma NFS-e é autorizada pela prefeitura, o que passa a valer juridicamente é o XML assinado e autorizado, e não uma folha impressa ou um arquivo PDF. ## O que tem dentro de um XML fiscal? Um XML fiscal traz os dados do emitente e do destinatário ou tomador, a descrição dos produtos ou serviços, quantidades, valores, impostos calculados, informações de transporte e pagamento, além de identificadores como a chave de acesso, a série e o número do documento. Ele também carrega a assinatura digital, feita com o certificado digital da empresa, que garante a autoria e mostra se o conteúdo foi alterado depois da assinatura. Após a autorização, o arquivo costuma ser complementado com o protocolo de autorização devolvido pelo órgão, formando o XML completo que deve ser guardado e enviado ao cliente. A estrutura de cada tipo de documento segue um leiaute oficial definido por esquemas XML. Se o arquivo não respeitar esse formato ou tiver dados inconsistentes, ele é rejeitado. ## Qual a diferença entre XML fiscal e DANFE ou PDF da nota? O XML é o documento fiscal em si, feito para ser lido por sistemas. Já o DANFE, o DANFCE, o DACTE e o DAMDFE são representações gráficas, geralmente em PDF, criadas para facilitar a leitura por pessoas e acompanhar mercadorias no transporte. Na prática, quem recebe apenas o PDF não tem o documento fiscal completo. Para escriturar a nota, conferir impostos ou comprovar a operação em uma fiscalização, é o XML que importa. O DANFE pode ser gerado novamente a partir do XML a qualquer momento, mas o contrário não é possível. ## Como o XML fiscal é gerado em uma emissão por API? Em uma emissão fiscal por API, o sistema da empresa, como um ERP ou uma plataforma de vendas, normalmente envia os dados da venda em um formato mais simples, como JSON. O emissor monta o XML no leiaute exigido, assina com o certificado digital, transmite ao órgão autorizador e acompanha a resposta. Quando o documento é autorizado, a API devolve ao sistema o XML final, o PDF e o status. Se houver rejeição, ela retorna o motivo para que o problema seja corrigido. Assim, o desenvolvedor não precisa lidar diretamente com a montagem do XML, as variações de leiaute entre documentos e municípios ou a assinatura digital. ## Quem precisa receber e guardar o XML fiscal? O emitente deve guardar o XML de todos os documentos que emite, e o destinatário ou tomador deve guardar os que recebe. A legislação exige que esses arquivos sejam mantidos por um prazo mínimo, em formato original e íntegro, para eventual consulta do fisco. Também é comum que o emitente envie o XML ao comprador por e-mail ou disponibilize para download. Contadores usam esses arquivos para a escrituração fiscal, e empresas compradoras costumam importá-los para dar entrada de mercadorias no estoque. ## Exemplos de XML fiscal - Uma loja virtual integrada a uma API fiscal vende um produto, recebe de volta o XML autorizado da NF-e e o anexa automaticamente ao e-mail de confirmação do pedido. - Um escritório de contabilidade solicita a um cliente os XMLs de todas as notas emitidas no mês para fazer a escrituração fiscal. - Uma indústria importa o XML da nota recebida de um fornecedor no seu ERP, que cadastra os itens e dá entrada no estoque sem digitação manual. - Uma transportadora consulta o XML de um CT-e para confirmar valores de frete e dados da carga durante uma auditoria interna. ## Perguntas frequentes ### O PDF da nota substitui o XML fiscal? Não. O PDF, como o DANFE, é apenas uma representação visual. O documento com validade jurídica é o XML assinado e autorizado, e é ele que deve ser guardado e usado na escrituração. ### É possível editar um XML fiscal depois de autorizado? Não. Qualquer alteração invalida a assinatura digital. Para corrigir informações, é preciso usar os mecanismos previstos, como carta de correção, quando permitida, cancelamento ou emissão de um novo documento. ### O XML da NFS-e é igual ao da NF-e? Não. Cada tipo de documento tem leiaute próprio. No caso da NFS-e, o formato pode variar conforme o município ou seguir o Padrão Nacional da NFS-e, dependendo de onde o serviço é emitido. ### Preciso saber montar XML para emitir notas por API? Geralmente não. Em uma API fiscal, o sistema envia os dados em formato simples, como JSON, e o emissor cuida de montar, assinar e transmitir o XML, devolvendo o arquivo final pronto. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [DANFE](https://conota.dev/glossario/danfe.md) - [Download de XML fiscal](https://conota.dev/glossario/download-de-xml-fiscal.md) - [Guarda de documentos fiscais](https://conota.dev/glossario/guarda-de-documentos-fiscais.md) --- Fonte: [XML fiscal](https://conota.dev/glossario/xml-fiscal/) · Atualizado em 2026-10-22 --- # XML namespace prefix > XML namespace prefix é o apelido curto, escrito antes do nome de uma tag e separado por dois-pontos (como ds:Signature), que indica a qual namespace, ou vocabulário, aquele elemento pertence. Ele evita confusão entre tags de mesmo nome e, em documentos fiscais eletrônicos, precisa seguir exatamente as regras definidas pelo fisco. **Também conhecido como:** Prefixo de namespace, Prefixo de namespace XML, Prefixo XML, Prefixo de espaço de nomes, XML namespace prefix **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um namespace e onde entra o prefixo? Um namespace, ou espaço de nomes, é um identificador único, geralmente escrito como um endereço no formato de URL, que diz a qual vocabulário um conjunto de tags XML pertence. Ele funciona como um sobrenome. Duas tags chamadas infNFe ou Signature podem ter significados diferentes conforme o namespace a que pertencem. O prefixo é uma forma abreviada de apontar para esse namespace. Em vez de repetir o endereço completo em cada tag, o XML declara uma vez algo como xmlns:ds="endereço do namespace" e, a partir daí, escreve ds:Signature, ds:SignedInfo e assim por diante. O prefixo em si (ds, nfe, soap) é só um apelido. O que realmente importa para o leitor do XML é o namespace associado a ele. ## Qual a diferença entre prefixo e namespace padrão? O namespace padrão é declarado sem prefixo, com xmlns="endereço". Todas as tags filhas sem prefixo passam a pertencer a ele automaticamente. Já o prefixo exige que cada tag traga o apelido antes do nome. Do ponto de vista técnico, e representam o mesmo elemento. Mas nem todo sistema que recebe o XML aceita as duas formas. Na NF-e, por exemplo, o padrão do fisco usa o namespace padrão http://www.portalfiscal.inf.br/nfe, sem prefixo, na estrutura principal do documento. ## Por que o prefixo de namespace causa rejeições em documentos fiscais? Os web services da SEFAZ e de muitas prefeituras validam o XML de forma rígida. No caso da NF-e e da NFC-e, existe uma rejeição específica para uso de prefixo de namespace não permitido. Ela costuma aparecer quando a biblioteca do sistema gera tags como ns2:NFe ou ns0:infNFe por conta própria. Isso é comum em ferramentas que serializam objetos para XML automaticamente, como algumas bibliotecas de Java e .NET. Elas criam prefixos genéricos sem que o desenvolvedor perceba. O XML continua válido pelas regras gerais da linguagem, mas não segue o formato exigido pelo leiaute fiscal e acaba recusado. ## Como o prefixo afeta a assinatura digital do XML? A assinatura digital é calculada sobre o conteúdo do XML depois de um processo chamado canonicalização, que padroniza espaços, atributos e declarações. Prefixos fazem parte desse conteúdo. Se o XML for assinado com um prefixo e depois alguém trocar ou remover esse prefixo, o resumo criptográfico muda e a assinatura deixa de ser válida. Por isso, o XML deve estar no formato final, com os namespaces e prefixos corretos, antes de ser assinado. Depois da assinatura, ele não deve ser reformatado por ferramentas que reescrevam as declarações de namespace. ## Como evitar problemas com prefixos na integração fiscal? O caminho mais seguro é gerar o XML seguindo o esquema XML oficial do documento e configurar a biblioteca de serialização para usar o namespace padrão onde o leiaute exige. Também ajuda testar no ambiente de homologação e comparar o XML gerado com exemplos aceitos pelo fisco. Quando a emissão é feita por uma API fiscal, como o Conota, o sistema do cliente envia os dados em JSON e a montagem do XML fica a cargo da API. Isso inclui namespaces, prefixos e assinatura. Assim, o desenvolvedor não precisa lidar diretamente com essas regras. ## Exemplos de XML namespace prefix - Um ERP em Java gera a NF-e com a tag e recebe da SEFAZ a rejeição por uso de prefixo de namespace não permitido. A correção é configurar o serializador para usar o namespace padrão. - No envelope SOAP enviado a um web service de prefeitura para emitir NFS-e, o prefixo soap: identifica as tags do protocolo, como soap:Envelope e soap:Body, enquanto o conteúdo da nota segue o namespace próprio do leiaute municipal. - Uma rotina de importação de XML fiscal reformata o arquivo e troca o namespace padrão da assinatura por um prefixo ds:. Com isso, a verificação da assinatura falha, porque o conteúdo canonicalizado mudou. - Um desenvolvedor usa XPath para ler o XML autorizado de um CT-e e não encontra nenhuma tag. O motivo é que ele não registrou na consulta o namespace do documento, que é obrigatório mesmo quando o XML não usa prefixos. ## Perguntas frequentes ### O nome do prefixo faz diferença? Pelas regras gerais do XML, não: ds, sig ou qualquer outro apelido apontam para o mesmo namespace se a declaração for igual. Na prática fiscal, porém, o leiaute oficial pode proibir prefixos ou exigir uma forma específica, e o XML precisa obedecer a isso. ### A NF-e aceita prefixos de namespace? A estrutura principal da NF-e e da NFC-e deve usar o namespace padrão do Portal Fiscal, sem prefixo. Gerar tags com prefixos como ns2: costuma resultar em rejeição pela SEFAZ. ### Posso remover prefixos de um XML já assinado? Não é recomendado. Alterar prefixos ou declarações de namespace depois da assinatura muda o conteúdo canonicalizado e invalida a assinatura digital. Qualquer ajuste deve ser feito antes de assinar. ### Preciso me preocupar com prefixos usando uma API fiscal? Em geral, não. Na emissão por API, o sistema envia os dados em JSON e a própria API monta o XML no formato exigido, com namespaces e assinatura corretos. O XML autorizado é devolvido pronto. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Importação de XML fiscal](https://conota.dev/glossario/importacao-de-xml-fiscal.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) --- Fonte: [XML namespace prefix](https://conota.dev/glossario/xml-namespace-prefix/) · Atualizado em 2026-10-22 --- # XML Schema enumeration > XML Schema enumeration é uma regra do XML Schema (XSD) que limita o valor de um campo a uma lista fechada de opções aceitas. Nos documentos fiscais eletrônicos, como NF-e, NFC-e e CT-e, ela define quais códigos são válidos para campos como ambiente, modelo ou modalidade de frete. Qualquer valor fora dessa lista invalida o arquivo. **Também conhecido como:** Enumeração em XSD, xs:enumeration, Restrição de enumeração, Lista de valores permitidos do schema, Faceta enumeration, XML Schema enumeration **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é uma enumeration no XML Schema? Um XML Schema, também chamado de XSD, é um arquivo que descreve como um documento XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de dado cada um aceita. A enumeration é uma das regras que esse esquema pode impor a um campo. Na prática, ela funciona como um menu de opções fechado. Em vez de aceitar qualquer texto ou número, o campo só aceita os valores listados no esquema. É parecido com um formulário em que você escolhe uma opção de uma lista suspensa, sem poder digitar algo livremente. ## Como funciona a enumeration dentro de um XSD? No XSD, o campo recebe um tipo simples com uma restrição. Dentro dessa restrição aparecem várias linhas do elemento xs:enumeration, cada uma com um valor permitido. Se um campo tem as enumerations 1 e 2, apenas esses dois valores passam na validação. O tipo de base continua valendo. Se a restrição é feita sobre um texto, o valor precisa ser exatamente igual ao listado, inclusive em letras maiúsculas e minúsculas, sem espaços extras. Um 1 com espaço antes ou depois, por exemplo, pode ser recusado. ## Onde a enumeration aparece nos documentos fiscais eletrônicos? Os esquemas oficiais de NF-e, NFC-e, CT-e, MDF-e e da NFS-e usam enumerations em muitos campos que representam códigos padronizados. Exemplos comuns na NF-e são o tipo de ambiente (1 para produção e 2 para homologação), o tipo de operação (0 para entrada e 1 para saída) e o modelo do documento (55 para NF-e e 65 para NFC-e). Também são definidos por lista a modalidade do frete, a finalidade da nota, o indicador de presença do comprador e os códigos de UF, entre outros. Isso garante que todos os emissores do país usem os mesmos códigos e que o fisco consiga interpretar cada documento sem ambiguidade. ## O que acontece quando um valor não está na lista? Quando o XML é validado contra o esquema e um campo traz um valor que não consta da enumeration, o documento é considerado inválido. No envio à SEFAZ ou à prefeitura, isso resulta em rejeição por falha de schema, e o documento não é autorizado. Esse tipo de erro costuma acontecer quando o sistema usa um código desatualizado, digita a descrição no lugar do código (escrever Saída em vez de 1, por exemplo) ou envia um valor válido em outro layout, mas não na versão vigente do esquema. ## Qual a diferença entre enumeration e outras restrições do XSD? O XSD tem outras regras, chamadas facetas, que também limitam valores. A pattern define um formato por meio de expressão regular, como exigir 44 dígitos numéricos na chave de acesso. As facetas de tamanho limitam a quantidade de caracteres, e as de valor mínimo e máximo limitam faixas numéricas. A diferença é que a enumeration não descreve um formato: ela lista explicitamente cada valor aceito. Use enumeration quando as opções são poucas e conhecidas; pattern e tamanho quando há muitas combinações possíveis seguindo uma regra. ## Como lidar com enumerations em uma integração fiscal por API? Em uma emissão fiscal por API, o sistema do cliente costuma enviar os dados em JSON, e a infraestrutura de emissão monta o XML no layout oficial. Mesmo assim, os códigos enviados precisam corresponder às listas do esquema, por isso é útil manter tabelas internas de conversão entre os cadastros do ERP e os códigos fiscais. Os esquemas mudam com novas versões de layout e notas técnicas, que podem incluir ou retirar valores. Validar os dados antes do envio e testar no ambiente de homologação ajuda a identificar enumerations desatualizadas antes que elas causem rejeições em produção. ## Exemplos de XML Schema enumeration - Um ERP envia uma NF-e com o campo de tipo de ambiente igual a 3. Como o esquema só aceita 1 ou 2, o documento é rejeitado por falha de schema. - Uma plataforma de vendas grava a modalidade de frete como texto (FOB) em vez do código numérico definido na enumeration, e o XML gerado não passa na validação. - Uma equipe de desenvolvimento consulta o XSD oficial para montar uma tabela de conversão entre os status de pedido do sistema e os valores permitidos para a finalidade da NF-e. - Após a publicação de uma nova versão de layout, um software de gestão atualiza suas listas internas para incluir novos códigos aceitos em um campo de enumeration. ## Perguntas frequentes ### Enumeration aceita a descrição em vez do código? Não. O campo só aceita exatamente os valores listados no esquema. Se a enumeration define 0 e 1, enviar Entrada ou Saída por extenso causa erro de validação, mesmo que o significado esteja correto. ### Os valores de uma enumeration podem mudar? Sim. Novas versões do layout ou notas técnicas podem acrescentar, alterar ou remover valores. Por isso, é importante acompanhar as atualizações dos esquemas oficiais e testar as mudanças em homologação antes de usá-las em produção. ### Existe algo parecido em JSON? Sim. O JSON Schema tem a palavra-chave enum, que cumpre a mesma função: restringir um campo a uma lista fechada de valores permitidos. ### Como descobrir quais valores um campo aceita? Consultando o arquivo XSD da versão vigente do documento ou o manual de orientação do contribuinte correspondente, que descreve cada campo e seus códigos válidos. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) - [Emissão fiscal por API](https://conota.dev/glossario/emissao-fiscal-por-api.md) --- Fonte: [XML Schema enumeration](https://conota.dev/glossario/xml-schema-enumeration/) · Atualizado em 2026-10-22 --- # XML Schema import > XML Schema import é o recurso da linguagem XSD, escrito como xs:import, que permite a um esquema XML usar elementos e tipos definidos em outro esquema de namespace diferente. Nos documentos fiscais eletrônicos, como a NF-e, ele traz, por exemplo, a estrutura padrão da assinatura digital para dentro do leiaute oficial do documento. **Também conhecido como:** xs:import, xsd:import, Importação de esquema XML, Import de XSD, XML Schema import **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XML Schema import, em palavras simples? Um esquema XML (arquivo XSD) é um conjunto de regras que diz como um arquivo XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de valor cada um aceita. Muitas vezes, porém, parte dessas regras já foi escrita por outra organização e faz mais sentido reaproveitá-la do que copiá-la. O import é a instrução que faz esse reaproveitamento. Ela diz ao validador: para estes elementos, use as regras que estão em outro esquema, que pertence a outro vocabulário. É como um contrato que cita outra norma técnica em vez de reescrevê-la por inteiro. ## Como funciona o xs:import na prática? O import é declarado no início do arquivo XSD e costuma ter dois atributos. O atributo namespace informa qual vocabulário está sendo importado, identificado por um endereço único. O atributo schemaLocation indica onde está o arquivo XSD com essas regras, geralmente um caminho relativo, como um arquivo na mesma pasta. Depois de declarar o import, o esquema pode referenciar elementos e tipos do outro vocabulário usando um prefixo associado àquele namespace. Vale saber que o schemaLocation é tratado como uma dica: cada ferramenta de validação decide como localizar o arquivo, e algumas permitem mapear caminhos locais para evitar downloads pela internet. ## Qual a diferença entre xs:import e xs:include? As duas instruções juntam esquemas, mas em situações diferentes. O xs:include é usado quando o outro arquivo pertence ao mesmo namespace, ou seja, faz parte do mesmo vocabulário e apenas foi dividido em vários arquivos por organização. O xs:import é usado quando o outro arquivo pertence a um namespace diferente, isto é, a um vocabulário de outra origem. Usar uma no lugar da outra gera erro de compilação do esquema, por isso a distinção importa para quem monta ou ajusta validadores. ## Onde o import aparece nos esquemas da NF-e e de outros documentos fiscais? Os pacotes de esquemas publicados para a NF-e reúnem vários arquivos XSD. Os arquivos do próprio leiaute, como o de tipos básicos, se ligam por include, porque compartilham o namespace da nota fiscal. Já a estrutura da assinatura digital segue o padrão XML Digital Signature, que tem namespace próprio, e por isso entra por import a partir de um arquivo XSD específico de assinatura incluído no pacote. A mesma lógica costuma se repetir em outros documentos fiscais eletrônicos, como CT-e, MDF-e e NFC-e: o leiaute do documento fica em um namespace e a assinatura em outro. Na NFS-e, a organização dos esquemas varia conforme o padrão adotado, mas o princípio do import é o mesmo. ## Por que a validação falha quando o import não é resolvido? Se o validador não encontra o arquivo indicado no import, ele não consegue entender os elementos daquele namespace. O resultado típico é um erro dizendo que o elemento de assinatura não foi declarado ou que um tipo não pode ser resolvido, mesmo que o XML esteja correto. As causas mais comuns são copiar apenas o arquivo principal sem os arquivos dependentes, mudar a estrutura de pastas e quebrar os caminhos relativos, misturar arquivos de versões diferentes do pacote de esquemas ou executar a validação em um ambiente sem acesso aos arquivos referenciados. ## Quem integra por API precisa se preocupar com o import de esquemas? Quem monta e valida o XML fiscal por conta própria precisa manter o pacote de esquemas completo e atualizado, com todos os arquivos ligados por include e import. A cada nova versão de leiaute, o pacote inteiro deve ser substituído. Quando a emissão é feita por uma API fiscal que recebe os dados em JSON e gera o XML, essa responsabilidade fica com o provedor da infraestrutura. Mesmo assim, entender o import ajuda a interpretar mensagens de erro de validação e a dialogar com a equipe técnica. ## Exemplos de XML Schema import - Um desenvolvedor baixa o pacote de esquemas da NF-e, mas coloca só o arquivo principal no projeto. A validação acusa que o elemento Signature não foi declarado, porque o arquivo de assinatura referenciado pelo import ficou de fora. - Uma equipe reorganiza as pastas do projeto e separa os XSD em subdiretórios. O schemaLocation relativo do import deixa de apontar para o arquivo certo e todas as notas passam a falhar na validação local. - Um ERP valida XMLs de CT-e antes do envio usando uma biblioteca que resolve imports a partir de uma pasta local, evitando depender de acesso à internet durante a validação. - Ao atualizar para uma nova versão de leiaute, a empresa substitui apenas alguns arquivos XSD e mantém outros antigos. A mistura de versões gera erros de tipos não encontrados até que o pacote completo seja trocado. ## Perguntas frequentes ### O import altera o conteúdo do XML da nota fiscal? Não. O import fica dentro do arquivo de esquema (XSD), não no XML da nota. Ele apenas informa ao validador onde encontrar as regras de outro vocabulário, como o da assinatura digital. ### Posso trocar xs:import por xs:include para resolver um erro? Não. O include só funciona para arquivos do mesmo namespace. Para vocabulários diferentes, como a assinatura digital, o import é obrigatório. O erro normalmente se resolve garantindo que o arquivo referenciado esteja no caminho correto. ### Preciso editar os esquemas oficiais para o import funcionar? Em geral, não. Basta manter todos os arquivos do pacote juntos, na estrutura de pastas original e na mesma versão. Editar esquemas oficiais pode causar divergências com a validação feita pelo fisco. ### Quem emite por API precisa ter os arquivos XSD? Depende. Se a API recebe dados estruturados e gera o XML, a validação pelo esquema costuma ser feita pelo provedor. Quem gera o XML por conta própria precisa manter o pacote completo. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Biblioteca de emissão fiscal](https://conota.dev/glossario/biblioteca-de-emissao-fiscal.md) --- Fonte: [XML Schema import](https://conota.dev/glossario/xml-schema-import/) · Atualizado em 2026-10-22 --- # XML Schema include > XML Schema include é o recurso da linguagem XML Schema (XSD) que permite a um arquivo de esquema incorporar as definições de outro arquivo do mesmo namespace, como se fossem um só. Nos documentos fiscais eletrônicos, ele divide os leiautes oficiais em partes reutilizáveis, como tipos básicos e estruturas comuns, usadas para validar o XML. **Também conhecido como:** xs:include, xsd:include, Inclusão de esquema XML, Include de XSD, XML Schema include **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é o XML Schema include? Um esquema XML, ou XSD, é um arquivo que descreve as regras de um documento XML: quais campos existem, em que ordem aparecem, que tipo de valor aceitam e quais são obrigatórios. Quando esse conjunto de regras é grande, faz sentido dividi-lo em vários arquivos menores. O include é a instrução que junta esses pedaços. No código, ela aparece como o elemento xs:include, com um atributo schemaLocation que indica o caminho do arquivo a ser incorporado. Na prática, o validador lê o arquivo principal, encontra o include e carrega as definições do outro arquivo como se estivessem escritas ali. ## Para que serve o include nos esquemas fiscais? Os pacotes de esquemas publicados para documentos como NF-e, NFC-e, CT-e e MDF-e costumam ser compostos por vários arquivos XSD. Há um arquivo para o leiaute do documento, outro com tipos básicos reaproveitados (como formatos de CNPJ, datas e valores monetários) e outros para eventos, como cancelamento ou carta de correção. O include evita repetir as mesmas definições em cada arquivo. Se um tipo básico for ajustado, a mudança é feita em um único lugar e vale para todos os esquemas que o incluem. Isso facilita a manutenção dos leiautes e a publicação de novas versões. ## Qual a diferença entre include e import no XML Schema? O include serve para juntar arquivos que pertencem ao mesmo namespace, ou seja, ao mesmo espaço de nomes que identifica o vocabulário do documento. Também é aceito incluir um arquivo sem namespace definido, que passa a adotar o namespace de quem o incluiu. O import, por outro lado, traz definições de um namespace diferente. Um exemplo comum nos esquemas fiscais é a assinatura digital do XML, cujas estruturas seguem o padrão XML Signature, que tem namespace próprio. Por isso, ela costuma entrar por import, e não por include. ## Que erros o include pode causar na validação? O problema mais frequente é o validador não encontrar o arquivo indicado no schemaLocation. Isso acontece quando alguém copia só o XSD principal para o projeto, esquece os arquivos auxiliares ou muda a estrutura de pastas, quebrando os caminhos relativos. Outro erro comum é misturar arquivos de versões diferentes do mesmo leiaute, por exemplo, um arquivo principal novo incluindo um arquivo de tipos de versão anterior. O resultado pode ser uma mensagem de tipo não declarado ou uma validação que aceita ou recusa campos de forma inesperada. A recomendação é manter o pacote de esquemas completo e na mesma versão. ## Quem integra por API precisa lidar com o include? Depende de como a integração é feita. Quem monta e valida o XML fiscal dentro do próprio sistema precisa carregar o pacote completo de XSDs e garantir que todos os includes sejam resolvidos corretamente. Quando a emissão passa por uma API fiscal que recebe os dados em JSON e gera o XML, a validação contra os esquemas oficiais fica a cargo dessa infraestrutura. Mesmo assim, entender o include ajuda a interpretar mensagens de erro de validação e a investigar divergências ao comparar XMLs autorizados. ## Exemplos de XML Schema include - Um arquivo de leiaute da NF-e usa xs:include para trazer um arquivo de tipos básicos, onde estão definidos formatos como o de CNPJ, CPF e valores decimais. - Um desenvolvedor copia apenas o XSD principal do CT-e para o projeto e, ao validar, recebe um erro informando que um tipo não foi declarado, porque o arquivo incluído ficou de fora. - Uma equipe de ERP organiza os esquemas de eventos fiscais em uma pasta separada e precisa ajustar os caminhos do schemaLocation para que os includes continuem funcionando. - Ao migrar para uma nova versão do leiaute, o time substitui todo o pacote de XSDs de uma vez, evitando que arquivos antigos sejam incluídos por engano. ## Perguntas frequentes ### O include altera o conteúdo do XML da nota fiscal? Não. O include atua apenas nos arquivos de esquema, que definem as regras de validação. O XML da nota não muda; o que muda é o conjunto de regras usado para verificar se ele está correto. ### Posso usar include para trazer o esquema da assinatura digital? Normalmente não. A assinatura digital segue o padrão XML Signature, que tem namespace próprio. Para trazer definições de outro namespace, o recurso adequado é o xs:import. ### Por que meu validador diz que não encontrou um arquivo XSD? Geralmente o arquivo citado no schemaLocation do include não está na pasta esperada. Verifique se o pacote de esquemas foi copiado inteiro, na mesma versão, e se a estrutura de pastas original foi mantida. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [API fiscal](https://conota.dev/glossario/api-fiscal.md) --- Fonte: [XML Schema include](https://conota.dev/glossario/xml-schema-include/) · Atualizado em 2026-10-22 --- # XML Schema pattern > XML Schema pattern é uma regra de validação usada em arquivos XSD que define, por meio de uma expressão regular, o formato exato que o texto de um campo XML deve seguir. Em documentos fiscais eletrônicos, como NF-e e CT-e, garante, por exemplo, que um CNPJ tenha 14 dígitos ou que uma chave de acesso tenha 44 números. **Também conhecido como:** xs:pattern, Faceta pattern, Restrição pattern do XSD, Padrão do XML Schema, XML Schema pattern facet **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um pattern no XML Schema? Um XML Schema (arquivo XSD) é um documento que descreve como um XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de valor cada um aceita. Dentro dele, o pattern é uma das chamadas facetas de restrição, escrita como xs:pattern, que limita os valores de um campo a um formato específico. Esse formato é descrito por uma expressão regular, uma espécie de molde de texto. Se o conteúdo do campo não se encaixar no molde, o XML é considerado inválido, mesmo que todo o resto esteja correto. ## Para que serve o pattern nos documentos fiscais? Os leiautes oficiais de NF-e, NFC-e, CT-e, MDF-e e da NFS-e padrão nacional são publicados como conjuntos de arquivos XSD. Os patterns desses arquivos garantem que dados como CNPJ, CPF, CEP, datas, valores monetários e chaves de acesso cheguem ao fisco em um formato único e previsível. Isso permite que a autorizadora rejeite imediatamente documentos malformados, antes mesmo de analisar regras de negócio, como cálculo de impostos ou situação cadastral do emitente. ## Como funciona a validação por pattern? Quando o XML é enviado, o validador compara o texto de cada campo com a expressão regular definida no schema. Um pattern como [0-9]{14}, por exemplo, só aceita exatamente 14 dígitos. Um CNPJ enviado com pontos, barra e hífen não se encaixa e gera erro. Um detalhe importante: no XML Schema, o pattern sempre precisa casar com o valor inteiro do campo, do primeiro ao último caractere. Por isso não se usam os marcadores de início e fim comuns em outras linguagens. Quando um mesmo tipo tem mais de um pattern, basta o valor atender a um deles. ## Por que erros de pattern são tão comuns na emissão fiscal? Muitos erros vêm de detalhes invisíveis: espaços no início ou no fim do texto, quebras de linha, caracteres especiais, máscaras de formatação ou casas decimais a mais. Nos schemas da NF-e, por exemplo, campos de texto costumam ter um pattern que proíbe espaços nas extremidades. Como a falha acontece na etapa de schema, o documento costuma ser rejeitado sem chegar à análise das regras fiscais. Por isso, sistemas que emitem notas normalmente limpam e formatam os dados antes de montar o XML, ou usam uma API fiscal que faz essa preparação. ## Qual a diferença entre pattern e outras restrições do XML Schema? O pattern controla o formato do texto. Outras facetas controlam aspectos diferentes: enumeration define uma lista fechada de valores permitidos (como os códigos de CST), length, minLength e maxLength controlam o tamanho, e totalDigits e fractionDigits limitam a quantidade de dígitos em números. Um mesmo campo pode combinar várias dessas regras. Também há diferença em relação ao pattern do JSON Schema: lá, a expressão não precisa casar com o valor inteiro, a menos que se usem marcadores de início e fim, e a sintaxe de expressão regular segue outro padrão. ## Exemplos de XML Schema pattern - No schema da NF-e, o campo de CNPJ usa um pattern equivalente a [0-9]{14}, então o valor 12.345.678/0001-90 é rejeitado e 12345678000190 é aceito. - A chave de acesso de uma NF-e ou de um CT-e segue um pattern de 44 dígitos numéricos; uma chave com 43 dígitos ou com espaços falha na validação. - Um ERP envia a razão social do destinatário com um espaço no final, e o documento é rejeitado por falha de schema porque o pattern do campo de texto não permite espaços nas extremidades. - Um time de desenvolvimento valida o XML localmente contra os arquivos XSD oficiais no ambiente de homologação para encontrar erros de pattern antes de emitir em produção. ## Perguntas frequentes ### Pattern e expressão regular são a mesma coisa? Quase. O pattern é a regra do XML Schema que usa uma expressão regular para validar um campo. A sintaxe é parecida com a de outras linguagens, mas tem particularidades, como casar sempre com o valor inteiro. ### Onde encontro os patterns usados na NF-e? Nos arquivos XSD que fazem parte do pacote de schemas oficial de cada documento fiscal, publicado junto com o leiaute técnico. Os patterns ficam definidos principalmente nos tipos básicos reutilizados pelos demais campos. ### Como evitar rejeições por pattern? Remova máscaras e espaços extras, padronize datas e casas decimais, evite caracteres não permitidos e valide o XML contra o XSD antes do envio. Testar no ambiente de homologação ajuda a detectar falhas cedo. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Chave de acesso da NF-e](https://conota.dev/glossario/chave-de-acesso-da-nf-e.md) - [Ambiente de homologação](https://conota.dev/glossario/ambiente-de-homologacao.md) --- Fonte: [XML Schema pattern](https://conota.dev/glossario/xml-schema-pattern/) · Atualizado em 2026-10-22 --- # XML Schema restriction > XML Schema restriction é o mecanismo da linguagem XSD (XML Schema Definition) que cria um tipo de dado a partir de outro já existente, limitando os valores aceitos por meio de regras chamadas facetas, como tamanho máximo, lista de opções, padrão de caracteres e casas decimais. Nos documentos fiscais eletrônicos, essas restrições definem o formato válido de cada campo. **Também conhecido como:** Restrição de esquema XML, Restrição XSD, xs:restriction, Derivação por restrição, Faceta de restrição, XML Schema restriction **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é uma restriction em XML Schema? Um XML Schema, ou esquema XSD, é um arquivo que descreve como um documento XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de valor cada um aceita. A restriction (restrição) é uma das ferramentas desse esquema para dizer exatamente o que pode ou não pode ir dentro de um campo. Ela funciona partindo de um tipo básico, como texto, número inteiro ou decimal, e estreitando as possibilidades. Por exemplo: em vez de aceitar qualquer texto, o campo passa a aceitar apenas 14 dígitos numéricos, o formato de um CNPJ. ## Como funciona uma restriction na prática? Dentro do arquivo XSD, a restrição é declarada com o elemento xs:restriction, que indica um tipo de base (por exemplo, xs:string ou xs:decimal) e, em seguida, lista as regras que limitam esse tipo. Essas regras são chamadas de facetas. Quando um sistema gera um XML, um validador compara cada campo com o esquema. Se o valor respeita todas as facetas, o campo é aceito. Se viola qualquer uma delas, o documento inteiro é considerado inválido em relação ao schema, mesmo que o resto esteja correto. ## Quais são as facetas mais usadas em uma restriction? As principais facetas são: length, minLength e maxLength, que controlam a quantidade de caracteres; pattern, que define um padrão por expressão regular; enumeration, que lista os únicos valores permitidos; minInclusive e maxInclusive, que estabelecem faixas numéricas; totalDigits e fractionDigits, que limitam o total de dígitos e as casas decimais; e whiteSpace, que define como espaços em branco são tratados. Várias facetas podem ser combinadas no mesmo tipo. Um campo de valor monetário, por exemplo, pode exigir no máximo 15 dígitos no total, com até 2 casas decimais, e um padrão que proíba zeros desnecessários à esquerda. ## Por que restrictions importam nos documentos fiscais eletrônicos? NF-e, NFC-e, CT-e, MDF-e e NFS-e são arquivos XML validados contra esquemas oficiais. Esses esquemas usam restrictions em grande parte dos campos: chave de acesso com 44 dígitos, código de UF limitado a valores válidos, datas em formato específico, valores com casas decimais definidas e textos com tamanho mínimo e máximo. Se o XML enviado desrespeita alguma restrição, a autoridade fiscal rejeita o documento por falha de schema antes mesmo de analisar regras tributárias. Por isso, entender essas restrições ajuda desenvolvedores a montar documentos corretos e a interpretar mensagens de rejeição. ## Qual a diferença entre restriction e validação de regras de negócio? A restriction verifica apenas o formato: se o campo tem o tamanho certo, os caracteres permitidos ou um valor dentro da lista. Ela não sabe, por exemplo, se o CNPJ informado existe, se o CFOP combina com a operação ou se o imposto foi calculado corretamente. Essas verificações de conteúdo são feitas depois, pelas regras de validação do fisco. Na prática, um documento passa primeiro pela checagem de schema e só então pelas regras de negócio, e cada etapa gera tipos diferentes de rejeição. ## Como evitar erros causados por restrictions? O caminho mais seguro é validar o XML localmente contra a versão correta do esquema antes de enviá-lo, usando bibliotecas de validação disponíveis na maioria das linguagens de programação. Também é importante acompanhar atualizações dos pacotes de schemas, pois novas versões podem alterar facetas. Quando a emissão é feita por uma API fiscal, parte desse trabalho costuma ficar com a própria API, que monta o XML a partir de dados enviados em outro formato, como JSON, e aponta campos fora do padrão antes do envio ao fisco. ## Exemplos de XML Schema restriction - O campo de CNPJ do emitente da NF-e usa uma restriction com pattern que aceita exatamente 14 dígitos numéricos; um valor com pontos, barra e hífen é rejeitado por falha de schema. - A justificativa de cancelamento de uma NF-e tem restriction de tamanho, exigindo no mínimo 15 caracteres; um texto como 'erro' faz o evento ser recusado. - O código da UF é definido por uma restriction do tipo enumeration, que só aceita os códigos numéricos oficiais dos estados. - Um campo de valor do produto restrito a 2 casas decimais é rejeitado quando o sistema envia 150.3456 em vez de 150.35. ## Perguntas frequentes ### Posso alterar uma restriction de um esquema fiscal oficial? Não. Os esquemas dos documentos fiscais são definidos pelos órgãos responsáveis e o XML precisa obedecê-los exatamente. Alterar o XSD localmente só esconde o erro, que continuará aparecendo na validação feita pelo fisco. ### O que acontece se um campo violar uma restriction? O documento é rejeitado por falha de schema e não é autorizado. A mensagem de retorno geralmente indica o campo problemático, permitindo corrigir o valor e reenviar o documento. ### Restriction existe também em JSON? O conceito equivalente existe no JSON Schema, com palavras-chave como maxLength, pattern, enum e minimum. A sintaxe é diferente, mas a ideia de limitar valores aceitos por campo é a mesma. ### Uma restriction garante que o documento está fiscalmente correto? Não. Ela garante apenas que o formato dos campos está correto. Cálculo de tributos, coerência entre campos e situação cadastral são verificados por regras de negócio separadas. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) - [JSON Schema](https://conota.dev/glossario/json-schema.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [API fiscal](https://conota.dev/glossario/api-fiscal.md) --- Fonte: [XML Schema restriction](https://conota.dev/glossario/xml-schema-restriction/) · Atualizado em 2026-10-22 --- # XMLDSig > XMLDSig é o padrão internacional que define como assinar digitalmente arquivos XML. Ele especifica onde a assinatura fica no arquivo, quais partes são protegidas e como verificar sua validade. No Brasil, é a base técnica da assinatura de documentos fiscais eletrônicos como NF-e, NFC-e, CT-e, MDF-e e muitas NFS-e. **Também conhecido como:** XML Signature, XML-DSig, XML DSig, Assinatura digital XML, XML Digital Signature, XMLDSig **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XMLDSig, em palavras simples? XMLDSig é a abreviação de XML Digital Signature, uma recomendação do W3C, o consórcio que define padrões da web. Ela descreve uma forma padronizada de colocar uma assinatura digital dentro de um arquivo XML ou de associá-la a ele. Funciona como um lacre eletrônico. Quem recebe o arquivo consegue confirmar duas coisas: quem assinou e se o conteúdo foi alterado depois da assinatura. Se alguém mudar um único caractere do trecho assinado, a verificação falha. ## Para que serve o XMLDSig nos documentos fiscais? Uma nota fiscal eletrônica é um arquivo XML com validade jurídica. Para que a SEFAZ ou a prefeitura aceite esse arquivo, ele precisa estar assinado com o certificado digital da empresa emitente, geralmente um certificado do tipo A1 ou A3 no padrão ICP-Brasil. O XMLDSig é a regra técnica que diz como essa assinatura deve ser montada. Ele garante autoria, já que só o dono do certificado pode assinar, e integridade, já que qualquer alteração posterior invalida o documento. Sem uma assinatura válida, o documento é rejeitado e não recebe autorização de uso. ## Como funciona uma assinatura XMLDSig? Primeiro, o trecho do XML que será protegido passa por uma canonicalização, uma padronização que elimina diferenças irrelevantes, como espaços e ordem de atributos. Depois, calcula-se um resumo criptográfico (hash) desse conteúdo, chamado DigestValue. Em seguida, esse resumo e as informações sobre os algoritmos usados são reunidos em um bloco chamado SignedInfo, que é assinado com a chave privada do certificado. O resultado é o SignatureValue. Por fim, o certificado público é incluído no bloco KeyInfo, para que qualquer pessoa possa verificar a assinatura usando a chave pública correspondente. ## Quais são as partes de uma assinatura XMLDSig? A assinatura fica dentro de um elemento chamado Signature. Nele aparecem: SignedInfo, que descreve o que foi assinado e com quais algoritmos; Reference, que aponta para o trecho protegido, normalmente pelo atributo Id; DigestValue, com o hash do conteúdo; SignatureValue, com a assinatura propriamente dita; e KeyInfo, que traz o certificado X.509 do assinante. Nos documentos fiscais brasileiros, a Reference costuma apontar para o grupo principal de informações, como o infNFe na NF-e, identificado pelo Id que contém a chave de acesso. ## Quais são os tipos de assinatura XMLDSig? O padrão prevê três formatos. Na assinatura envelopada (enveloped), ela fica dentro do próprio XML assinado. Na envolvente (enveloping), o conteúdo assinado fica dentro da assinatura. Na destacada (detached), a assinatura fica separada do conteúdo. Os documentos fiscais eletrônicos brasileiros usam a assinatura envelopada: o elemento Signature fica dentro do arquivo da nota, logo após o bloco de informações assinado. Os detalhes exatos, como algoritmos e transformações aceitas, são definidos no leiaute e nas notas técnicas de cada documento. ## Por que a assinatura XMLDSig costuma gerar rejeições? Por ser muito sensível, pequenos detalhes quebram a assinatura: alterar o XML depois de assinado, formatar o arquivo com quebras de linha, usar namespace incorreto, canonicalização diferente da esperada ou um certificado vencido ou revogado. O resultado é uma rejeição fiscal por assinatura inválida ou digest divergente. Por isso, muitos sistemas preferem delegar essa etapa a uma API fiscal. O sistema envia os dados da venda, e a infraestrutura de emissão monta o XML, assina com o certificado cadastrado e transmite ao órgão autorizador, evitando que cada equipe precise dominar os detalhes do padrão. ## Exemplos de XMLDSig - Um ERP envia os dados de uma venda para uma API fiscal, que gera o XML da NF-e, aplica a assinatura XMLDSig envelopada com o certificado A1 da empresa e transmite o arquivo à SEFAZ. - Uma equipe de desenvolvimento recebe uma rejeição por assinatura inválida porque o sistema reformatava o XML com indentação depois de assiná-lo, alterando o conteúdo protegido. - Um evento de cancelamento de NF-e também é um XML assinado com XMLDSig, com a Reference apontando para o Id do grupo de informações do evento. - Um escritório contábil importa XMLs de notas recebidas e usa a validação da assinatura XMLDSig para confirmar que os arquivos não foram adulterados. ## Perguntas frequentes ### XMLDSig é a mesma coisa que certificado digital? Não. O certificado digital é a identidade eletrônica da empresa, com o par de chaves. O XMLDSig é o padrão que define como usar esse certificado para assinar um arquivo XML. ### Posso editar o XML de uma nota depois de assinado? Não. Qualquer alteração no trecho assinado invalida a assinatura. Se for preciso corrigir algo, o XML deve ser gerado e assinado novamente antes do envio, ou, após a autorização, deve-se usar os eventos fiscais previstos, como carta de correção ou cancelamento. ### Toda NFS-e usa XMLDSig? Muitas usam, incluindo o Padrão Nacional da NFS-e, mas alguns municípios têm regras próprias de envio e assinatura. Por isso, os requisitos variam conforme a prefeitura e o leiaute adotado. ### Preciso implementar XMLDSig se uso uma API fiscal? Em geral, não. A API fiscal recebe os dados, monta o XML e faz a assinatura com o certificado cadastrado. Seu sistema só precisa enviar as informações corretas e tratar o retorno. ## Termos relacionados - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Certificado digital A1](https://conota.dev/glossario/certificado-digital-a1.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Hash de documento fiscal](https://conota.dev/glossario/hash-de-documento-fiscal.md) - [Key pair na assinatura digital](https://conota.dev/glossario/key-pair-na-assinatura-digital.md) - [Namespace XML](https://conota.dev/glossario/namespace-xml.md) --- Fonte: [XMLDSig](https://conota.dev/glossario/xmldsig/) · Atualizado em 2026-10-22 --- # 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 --- # XQuery na consulta de XML > XQuery é uma linguagem padronizada para consultar, filtrar e transformar dados armazenados em XML. Com ela, é possível buscar informações específicas em um ou vários arquivos, como valores, CNPJs e produtos de notas fiscais eletrônicas, combinar resultados e gerar novos documentos, sem precisar ler o conteúdo manualmente nem converter tudo para outro formato. **Também conhecido como:** XML Query Language, Linguagem XQuery, Consulta XQuery, XQuery (XML Query Language) **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XQuery e para que serve? XQuery é uma linguagem criada especificamente para trabalhar com documentos XML. Ela é para o XML o que o SQL é para um banco de dados relacional. Você descreve o que quer encontrar, e o processador XQuery percorre os arquivos e devolve o resultado. No contexto fiscal, isso é útil porque NF-e, NFC-e, CT-e, MDF-e e muitos modelos de NFS-e são arquivos XML. Uma empresa que guarda milhares desses arquivos pode usar XQuery para responder perguntas como quais notas passaram de determinado valor, quais produtos usaram um certo CFOP ou quais documentos foram emitidos para um cliente específico. ## Como funciona uma consulta XQuery? A base do XQuery são os caminhos que apontam para partes do XML. Por exemplo, o caminho //emit/CNPJ localiza o CNPJ do emitente dentro de uma NF-e. A partir desses caminhos, a linguagem permite filtrar, ordenar e montar a resposta. A estrutura mais conhecida é chamada FLWOR, sigla das palavras for, let, where, order by e return. O for percorre itens, o let guarda valores em variáveis, o where aplica condições, o order by ordena e o return define o que será devolvido. É parecido com um SELECT do SQL, mas pensado para dados em árvore, como o XML. O resultado pode ser um valor simples, uma lista ou até um novo documento XML ou HTML montado pela própria consulta, como um relatório resumido. ## Como usar XQuery para consultar XMLs de notas fiscais? Um ponto essencial é o namespace. Os XMLs da NF-e e da NFC-e usam o namespace http://www.portalfiscal.inf.br/nfe, e a consulta precisa declará-lo. Sem isso, caminhos como //infNFe não encontram nada, mesmo que o elemento exista no arquivo. Uma consulta típica começa com declare default element namespace "http://www.portalfiscal.inf.br/nfe";. Depois, basta percorrer as notas. Uma consulta como for $n in collection("notas")//infNFe where xs:decimal($n/total/ICMSTot/vNF) > 1000 return string($n/@Id) devolve as chaves de acesso das notas com valor total acima de mil reais. Note que o valor é convertido com xs:decimal, pois no XML ele está armazenado como texto. Esse tipo de consulta costuma rodar em bancos de dados XML nativos, em bibliotecas de linguagens de programação ou em ferramentas de linha de comando, aplicadas sobre os arquivos XML fiscais já baixados ou importados. ## Qual a diferença entre XQuery e XPath? XPath é a linguagem de caminhos usada para localizar elementos dentro de um XML, como //dest/CNPJ. XQuery inclui o XPath e vai além: permite criar variáveis, juntar dados de vários arquivos, ordenar resultados, definir funções e montar novas estruturas de saída. Na prática, XPath resolve bem buscas pontuais, como pegar um campo de uma nota. XQuery é mais indicado quando a pergunta envolve vários documentos, cálculos ou relatórios, como somar o ICMS de todas as notas de um mês agrupadas por cliente. ## Quando vale a pena usar XQuery em vez de converter o XML para JSON? Muitos sistemas preferem converter o XML fiscal para JSON, formato mais comum em APIs modernas, e consultar os dados no banco da aplicação. Isso é prático no dia a dia, mas a conversão pode perder detalhes, como atributos, namespaces e a ordem original dos elementos. XQuery faz sentido quando é preciso consultar o XML original, que é o documento com validade jurídica, por exemplo em auditorias, conferências contábeis ou investigações de divergências. Também ajuda quando o volume de arquivos é grande e a estrutura varia entre versões de leiaute ou entre modelos municipais de NFS-e. ## Quais cuidados tomar ao consultar XML fiscal com XQuery? O XML autorizado de uma nota não mostra, sozinho, se ela foi cancelada ou corrigida depois. Essas informações ficam em eventos fiscais, que são arquivos XML separados. Uma consulta confiável precisa cruzar a nota com seus eventos. Também é importante lembrar que os arquivos podem vir em formatos diferentes: só a nota, a nota com o protocolo de autorização (elemento nfeProc) ou compactados. Por fim, as NFS-e podem seguir leiautes distintos conforme o padrão adotado, o que exige consultas adaptadas a cada estrutura. ## Exemplos de XQuery na consulta de XML - Um escritório contábil recebe os XMLs de NF-e de vários clientes e usa XQuery para listar todas as notas de entrada com CFOP de devolução emitidas em um determinado mês. - Uma equipe de auditoria interna roda uma consulta XQuery sobre o arquivo de notas guardadas para encontrar documentos em que o valor total da nota não bate com a soma dos itens. - Um ERP gera, a partir dos XMLs de CT-e, um relatório em XML com o total de frete por transportadora, montado diretamente pela cláusula return de uma consulta FLWOR. - Um desenvolvedor usa XQuery para extrair o CNPJ do destinatário e a chave de acesso de milhares de NFC-e baixadas, a fim de conciliar as vendas com o sistema de caixa. ## Perguntas frequentes ### Preciso de XQuery para emitir notas fiscais por API? Não. A emissão por API normalmente recebe e devolve dados em JSON, e a plataforma cuida do XML. XQuery é útil depois, para consultar e analisar os arquivos XML já autorizados e armazenados. ### Por que minha consulta XQuery não retorna nada em um XML de NF-e? O motivo mais comum é a falta de declaração do namespace da NF-e. Sem declarar http://www.portalfiscal.inf.br/nfe, os caminhos não correspondem aos elementos do arquivo, e o resultado fica vazio. ### XQuery consegue alterar um arquivo XML fiscal? Existem extensões da linguagem para atualizar XML, mas um documento fiscal autorizado não deve ser alterado, pois isso invalida a assinatura digital. Use XQuery apenas para ler e gerar novos documentos derivados. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Download de XML fiscal](https://conota.dev/glossario/download-de-xml-fiscal.md) - [Importação de XML fiscal](https://conota.dev/glossario/importacao-de-xml-fiscal.md) - [Filtro de documentos fiscais](https://conota.dev/glossario/filtro-de-documentos-fiscais.md) - [Chave de acesso da NF-e](https://conota.dev/glossario/chave-de-acesso-da-nf-e.md) --- Fonte: [XQuery na consulta de XML](https://conota.dev/glossario/xquery-na-consulta-de-xml/) · Atualizado em 2026-10-22 --- # XSD > XSD é a sigla de XML Schema Definition, uma linguagem usada para descrever a estrutura que um arquivo XML deve seguir: quais campos existem, em que ordem aparecem, quais são obrigatórios e que tipo de valor aceitam. No meio fiscal, os arquivos XSD definem o formato oficial de documentos como NF-e, NFC-e, CT-e, MDF-e e NFS-e. **Também conhecido como:** XML Schema, Esquema XSD, Arquivo XSD, Schema XML, XSD, XML Schema Definition **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é um XSD, em palavras simples? Pense no XSD como um molde ou um formulário oficial em branco. Ele não contém os dados de uma nota fiscal específica, mas diz exatamente como qualquer nota daquele tipo precisa ser montada: o nome de cada campo, onde ele fica, quantos caracteres pode ter e se aceita números, datas ou textos. O próprio XSD também é escrito em XML, só que com regras em vez de dados. Um arquivo XML de NF-e, por exemplo, é comparado com o XSD da NF-e para saber se está correto do ponto de vista da estrutura. ## Para que serve o XSD nos documentos fiscais eletrônicos? Os documentos fiscais eletrônicos são trocados entre milhares de sistemas diferentes: ERPs, plataformas de venda, emissores e os servidores das autoridades fiscais. Para que todos se entendam, é preciso um padrão único e verificável. O XSD cumpre esse papel, garantindo que todos montem o XML do mesmo jeito. Quando o XML chega à SEFAZ ou à prefeitura, uma das primeiras verificações é a validação contra o XSD. Se faltar um campo obrigatório, se um valor tiver formato errado ou se a ordem das tags estiver trocada, o documento é rejeitado antes mesmo de as regras tributárias serem analisadas. ## Como funciona a validação de um XML pelo XSD? Um programa chamado validador lê o XML e o XSD ao mesmo tempo e confere, item por item, se o documento respeita as regras. Ele verifica, por exemplo, se a data está no formato esperado, se um CNPJ tem a quantidade certa de dígitos e se campos com valores pré-definidos usam apenas as opções permitidas. O resultado é simples: o XML é válido ou inválido. Quando é inválido, o validador costuma indicar qual elemento causou o problema, o que ajuda o desenvolvedor a localizar o erro. Muitos sistemas fazem essa validação localmente, antes do envio, para evitar rejeições e economizar tempo. ## Quem publica os XSDs fiscais e com que frequência eles mudam? Os XSDs oficiais são disponibilizados pelos órgãos responsáveis por cada documento, geralmente em pacotes publicados junto com o leiaute e as notas técnicas. No caso da NFS-e, além do Padrão Nacional, há municípios que historicamente usam leiautes próprios, cada um com seus esquemas. Os XSDs mudam sempre que o leiaute é alterado, por exemplo para incluir novos campos ou grupos de tributação. Quem emite documentos precisa acompanhar essas atualizações, pois um XML montado com uma versão antiga do esquema pode passar a ser rejeitado. ## Qual a diferença entre XSD e leiaute fiscal? O leiaute fiscal é a especificação completa do documento, normalmente em formato de manual, com a descrição de cada campo, seu significado e as regras de negócio. O XSD é a tradução técnica e automatizável da parte estrutural desse leiaute. Por isso, um XML pode passar no XSD e ainda assim ser rejeitado: o esquema verifica formato e estrutura, mas não confere, por exemplo, se a alíquota informada é a correta para aquela operação. Essas regras de negócio são validadas depois, pela autoridade fiscal. ## Quem usa uma API fiscal precisa lidar com XSD? Em geral, não diretamente. Em uma API fiscal como a do Conota, o sistema do cliente envia os dados em JSON e a infraestrutura de emissão se encarrega de montar o XML no formato exigido, validar a estrutura e acompanhar o documento até a autorização. Ainda assim, entender o que é XSD ajuda a interpretar mensagens de erro de validação e a compreender por que certos campos têm limites de tamanho ou formatos obrigatórios no payload de emissão. ## Exemplos de XSD - Um ERP que monta o XML da NF-e por conta própria valida o arquivo contra o XSD antes do envio e descobre que o campo de CEP do destinatário estava com um hífen, formato não aceito pelo esquema. - Uma SEFAZ rejeita uma nota com a mensagem de falha de schema porque o grupo de informações de pagamento foi colocado fora da ordem definida no XSD. - Após a publicação de uma nota técnica com novos campos, a equipe de desenvolvimento de um marketplace atualiza os arquivos XSD usados nos testes do ambiente de homologação. - Um desenvolvedor que integra NFS-e de vários municípios percebe que cada prefeitura com leiaute próprio exige um XSD diferente, enquanto o Padrão Nacional unifica a estrutura. ## Perguntas frequentes ### XSD e XML são a mesma coisa? Não. O XML é o documento com os dados, como uma nota fiscal preenchida. O XSD é o conjunto de regras que define como esse XML deve ser estruturado. O XSD também é escrito em XML, mas sua função é validar, não transportar dados. ### Um XML válido no XSD sempre será autorizado? Não. O XSD valida apenas estrutura e formato. Depois disso, a autoridade fiscal confere regras de negócio, como cálculos de impostos, situação cadastral do emitente e numeração. O documento pode ser rejeitado nessas etapas. ### Onde encontro os XSDs da NF-e e de outros documentos? Eles são publicados pelos órgãos responsáveis por cada documento, normalmente em seus portais oficiais, junto com manuais de leiaute e notas técnicas. É importante usar sempre a versão vigente. ### Qual a relação entre XSD e JSON Schema? Ambos descrevem e validam a estrutura de dados. O XSD é usado para arquivos XML; o JSON Schema, para dados em JSON. Em APIs fiscais, é comum o cliente enviar JSON validado por JSON Schema, que depois vira XML validado por XSD. ## Termos relacionados - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Schema de validação](https://conota.dev/glossario/schema-de-validacao.md) - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Leiaute fiscal](https://conota.dev/glossario/leiaute-fiscal.md) - [Namespace XML](https://conota.dev/glossario/namespace-xml.md) - [Erro de validação fiscal](https://conota.dev/glossario/erro-de-validacao-fiscal.md) --- Fonte: [XSD](https://conota.dev/glossario/xsd/) · Atualizado em 2026-10-22 --- # XSLT na transformação de documentos > XSLT na transformação de documentos é o uso da linguagem XSLT, padronizada pelo W3C, para converter um arquivo XML em outro formato, como HTML, texto ou um novo XML com estrutura diferente. No contexto fiscal, serve para gerar visualizações de notas, adaptar layouts entre sistemas e extrair dados de XMLs de NF-e, NFS-e ou CT-e. **Também conhecido como:** Transformação XSL, Transformação XSLT, Folha de estilo XSLT, XSL Transformations, XSLT, Extensible Stylesheet Language Transformations **Glossário:** [Glossário de A a Z](https://conota.dev/glossario/) · **Letra:** X ## O que é XSLT e como funciona? XSLT é uma linguagem feita especificamente para transformar documentos XML. Em vez de escrever um programa que lê o arquivo linha por linha, você cria uma folha de estilo com regras do tipo: quando encontrar tal elemento, produza tal resultado. O processo envolve três peças: o XML de entrada (por exemplo, o XML de uma NF-e), a folha de estilo XSLT com as regras e um processador XSLT, que é o software que aplica essas regras. Para localizar as informações dentro do XML, o XSLT usa outra linguagem chamada XPath, que funciona como um endereço, apontando, por exemplo, para o valor total da nota ou o CNPJ do emitente. O resultado pode ser uma página HTML, um texto simples, um CSV ou um novo XML. O arquivo original não é modificado: a transformação sempre gera um documento novo. ## Para que serve XSLT na área fiscal? O uso mais conhecido é gerar uma visualização legível a partir do XML fiscal. Um XML de NF-e é feito para máquinas, não para pessoas, e uma folha XSLT pode montá-lo em HTML com cabeçalho, itens e totais, servindo de base para relatórios ou documentos auxiliares. Outro uso comum é a conversão de layouts. Na NFS-e, por exemplo, diferentes municípios e padrões historicamente usaram estruturas de XML distintas, e uma camada de XSLT pode traduzir um formato interno do sistema para o layout exigido em cada caso, ou o contrário. Também serve para extrair dados: um sistema pode aplicar XSLT em XMLs recebidos de fornecedores para gerar arquivos de importação para o ERP, planilhas de conferência ou relatórios fiscais. ## Aplicar XSLT altera a validade do XML fiscal? Não, desde que o XML autorizado seja preservado. O documento com validade jurídica é o XML original, assinado digitalmente e autorizado pelo fisco. Qualquer arquivo gerado por XSLT é apenas uma representação ou um derivado dele. Se alguém transformar o XML e tentar usar o resultado como se fosse o documento original, a assinatura digital deixará de conferir, porque qualquer alteração no conteúdo assinado invalida a assinatura. Por isso, a regra prática é guardar sempre o XML autorizado intacto e tratar as saídas do XSLT como cópias para visualização ou integração. ## Qual a diferença entre usar XSLT e converter o XML com código comum? Com código comum, em linguagens como Java ou JavaScript, o desenvolvedor lê o XML, monta objetos e gera a saída manualmente. Isso dá flexibilidade total, mas mistura regras de layout com a lógica do sistema. Com XSLT, as regras de transformação ficam separadas em um arquivo próprio, que pode ser alterado sem recompilar a aplicação. É uma vantagem quando há muitos layouts parecidos para manter. Por outro lado, a sintaxe do XSLT é pouco familiar para muitos desenvolvedores e lógicas complexas, como cálculos tributários, costumam ficar mais claras em código convencional. Muitas equipes hoje preferem converter o XML para JSON e trabalhar com ele na linguagem do próprio sistema. ## Quais cuidados tomar ao usar XSLT com documentos fiscais? O erro mais frequente envolve namespaces. Os XMLs fiscais declaram um namespace, e uma expressão XPath que ignora isso simplesmente não encontra nada, gerando saídas vazias sem mensagem de erro clara. Também é importante saber qual versão do XSLT o processador suporta. A versão 1.0 é a mais amplamente disponível, enquanto as versões 2.0 e 3.0 trazem recursos úteis, como melhor tratamento de datas e números, mas nem todo ambiente as oferece. Quando a saída for um novo XML que será enviado a outro sistema, vale validá-la contra o esquema XML esperado. E, por segurança, convém restringir funções que acessam arquivos ou endereços externos ao processar XMLs recebidos de terceiros. ## É preciso usar XSLT ao emitir notas por API? Em geral, não. Quando a emissão é feita por uma API fiscal, o sistema costuma enviar os dados em JSON e receber de volta o XML autorizado, o PDF do documento auxiliar e o status, sem precisar montar layouts manualmente. O XSLT continua útil em necessidades específicas, como criar relatórios personalizados a partir dos XMLs baixados, integrar com sistemas legados que só trabalham com XML ou adaptar dados de notas recebidas para importação no ERP. ## Exemplos de XSLT na transformação de documentos - Um ERP aplica uma folha XSLT sobre os XMLs de NF-e de entrada para gerar um CSV com fornecedor, CFOP, valor dos itens e ICMS, usado na conferência antes do lançamento contábil. - Um software de gestão de serviços mantém um formato interno único de NFS-e e usa uma folha XSLT para cada padrão municipal, convertendo os dados para a estrutura exigida em cada cidade. - Uma transportadora transforma o XML do CT-e em uma página HTML resumida para que o atendimento consulte remetente, destinatário e valor do frete sem abrir o arquivo bruto. - Um marketplace gera, a partir dos XMLs autorizados de NFC-e, um relatório HTML diário com totais por forma de pagamento, mantendo os XMLs originais armazenados sem alteração. ## Perguntas frequentes ### O que significa a sigla XSLT? Significa Extensible Stylesheet Language Transformations. É a parte da família de padrões XSL dedicada a transformar documentos XML em outros formatos. ### Posso gerar o DANFE com XSLT? É possível gerar uma versão em HTML com XSLT e depois convertê-la em PDF, mas o layout precisa seguir as regras oficiais do documento auxiliar. Muitas soluções de emissão já entregam o PDF pronto, dispensando esse trabalho. ### XSLT funciona com JSON? O XSLT foi criado para XML. A versão 3.0 trouxe recursos para ler e produzir JSON, mas o suporte depende do processador usado. Para dados nativamente em JSON, normalmente se usam outras ferramentas. ### O arquivo gerado por XSLT tem valor fiscal? Não. O valor jurídico está no XML original assinado e autorizado. O resultado da transformação é apenas uma representação ou um dado derivado, útil para consulta e integração. ## Termos relacionados - [Arquivo XML fiscal](https://conota.dev/glossario/arquivo-xml-fiscal.md) - [Esquema XML](https://conota.dev/glossario/esquema-xml.md) - [Geração de DANFE](https://conota.dev/glossario/geracao-de-danfe.md) - [Assinatura digital do XML](https://conota.dev/glossario/assinatura-digital-do-xml.md) - [Documento auxiliar da NFS-e](https://conota.dev/glossario/documento-auxiliar-da-nfs-e.md) - [Formato JSON](https://conota.dev/glossario/formato-json.md) --- Fonte: [XSLT na transformação de documentos](https://conota.dev/glossario/xslt-na-transformacao-de-documentos/) · Atualizado em 2026-10-22