Namespace XML

O que é um namespace XML, em termos simples?

Um arquivo XML é formado por tags, como <emit>, <dest> ou <valor>. Como qualquer pessoa pode criar tags com qualquer nome, é comum que dois padrões diferentes usem o mesmo nome com significados distintos. O namespace funciona como um sobrenome: ele diz de qual família aquela tag vem.

Na prática, o namespace é declarado com o atributo xmlns dentro de uma tag. Por exemplo, na NF-e aparece xmlns="http://www.portalfiscal.inf.br/nfe". Isso significa que todas as tags dentro daquele elemento pertencem ao vocabulário oficial da NF-e.

O endereço do namespace precisa estar acessível na internet?

Não. Embora tenha cara de link, o namespace é apenas um nome único. O sistema que lê o XML não visita esse endereço; ele só compara o texto, caractere por caractere, com o valor esperado.

Por isso, qualquer diferença mínima, como trocar http por https, acrescentar uma barra no final ou mudar maiúsculas e minúsculas, faz o namespace ser considerado outro. Para o validador, é como se o arquivo pertencesse a um padrão completamente diferente.

Por que o namespace é tão importante nos documentos fiscais?

Os sistemas autorizadores, como a SEFAZ, validam cada XML contra um esquema XML (arquivo XSD) publicado no leiaute oficial. Esse esquema está vinculado a um namespace específico. Se o XML não declarar o namespace correto, o validador não reconhece as tags e o documento é rejeitado, mesmo que todos os dados estejam certos.

Cada documento tem o seu: a NF-e e a NFC-e usam o namespace da NF-e, enquanto o CT-e e o MDF-e têm namespaces próprios, também no domínio portalfiscal.inf.br. Já a assinatura digital usa o namespace do padrão XML Signature, "http://www.w3.org/2000/09/xmldsig#", que convive no mesmo arquivo com o namespace fiscal.

Qual a diferença entre namespace padrão e namespace com prefixo?

No namespace padrão, a declaração é feita apenas com xmlns="…" e vale automaticamente para a tag onde aparece e para todas as tags internas, sem precisar repetir nada. É a forma usada nos documentos fiscais brasileiros.

No namespace com prefixo, a declaração fica como xmlns:nfe="…" e as tags passam a ser escritas como <nfe:emit>. Tecnicamente, os dois formatos podem representar o mesmo conteúdo, mas alguns autorizadores e validadores esperam o formato exato do leiaute, e prefixos inesperados podem gerar rejeição ou quebrar a assinatura.

Que problemas o namespace costuma causar na integração?

Os erros mais comuns são: esquecer de declarar o namespace ao montar o XML manualmente, declarar no elemento errado, deixar bibliotecas inserirem prefixos automáticos (como ns0 ou ns2) e alterar o namespace depois de assinar o arquivo.

Esse último caso merece atenção: a assinatura digital considera o namespace no cálculo. Se ele for adicionado, removido ou modificado após a assinatura, o documento passa a ter assinatura inválida. Em integrações por API, como no Conota, o sistema do cliente envia os dados em JSON e a montagem do XML, com namespaces corretos e assinatura, fica a cargo da infraestrutura de emissão.

Exemplos de Namespace XML

• Um desenvolvedor monta o XML de uma NF-e sem o atributo xmlns na tag <NFe> e recebe uma rejeição de falha no schema, embora todos os campos estejam preenchidos corretamente.
• Uma biblioteca de serialização gera tags como <ns2:infNFe>, com prefixo automático, e o autorizador recusa o arquivo por não corresponder ao formato esperado pelo leiaute.
• Ao abrir o XML de um CT-e autorizado, o analista identifica dois namespaces: o do CT-e na tag principal e o do XML Signature dentro da tag <Signature>.
• Um ERP integrado a uma API fiscal envia apenas um payload JSON e recebe de volta o XML autorizado, já com os namespaces e a assinatura digital aplicados corretamente.