Pular para o conteúdo
Fiscal ProBiblioteca
Acessar Fiscal Pro
NF-e e NFC-e · Suplemento, assinatura e protocolo

qrCode da NFC-e: versões, parâmetros e conferência da URL

<qrCode>nfeProc › NFe › infNFeSupl › qrCode

Revisão editorial em 14 de out. de 2026. As versões e condições das regras estão indicadas ao longo do artigo.

qrCode contém o texto da URL representada pelo QR-Code no DANFE NFC-e. A imagem representa esse texto; o XML guarda a URL, sem pixels ou Base64 de imagem. Para investigar um erro, decodifique a imagem e compare o texto com os dados da nota e a regra da versão utilizada.

Caminho desta página: /nfeProc/NFe/infNFeSupl/qrCode. O prefixo nfeProc identifica a nota processada. infNFeSupl é filho de NFe, irmão de infNFe, e fica fora deste último grupo.

Versão 3: online e contingência têm formatos diferentes

A NT 2025.001 v1.03 corrigida descreve a versão 3 online como endereço oficial de consulta seguido de ?p= e três parâmetros separados por |: chave de acesso, versão 3 e tipo de ambiente. Na forma offline (tpEmis=9), acrescenta dia da emissão, valor total, tipo de identificação do destinatário, identificador do destinatário e assinatura.

O controle criptográfico próprio da versão 3 é documentado para a contingência. A assinatura não deve ser acrescentada ao formato online. ZX02-330/445 e ZX02-334/474 distinguem assinatura indevida online e ausente offline; ZX02-338/583 trata assinatura offline divergente. Ler a chave com sucesso não verifica a assinatura. NT 2025.001 v1.03, p. 13–14.

Versão 2 e CSC não devem ser misturados com v3

Na versão 2, a URL online inclui identificador de CSC e hash; na offline inclui também dia, total e digVal. Na versão 3, esses parâmetros de CSC deixam de compor o formato, e a assinatura offline tem outra função. A NT descreve eliminação futura do CSC sem data definida: não se deve afirmar que toda emissão v2 ou credencial CSC já foi abolida.

A mesma NT trata a versão 3 para emitente pessoa física rural e documenta condição própria para o Paraná. Para CNPJ, descreve a opção de adotar o novo leiaute. O XSD conter padrões v1, v2 e v3 não prova que uma versão legada seja aceita pela regra de negócio atual. Confira emitente, UF, modelo, ambiente e versão efetivamente gerada. NT v1.03, p. 5 e 11.

Vetor público oficial para leitura da forma XML

O exemplo abaixo é transcrito, sem alterar chave ou parâmetros, do vetor legado versão 100 da NT 2025.001 v1.03 corrigida, p. 14. É um exemplo público de homologação (tpAmb=2), usado somente para demonstrar a URL como texto XML; não é uma receita de geração atual, nota de cliente ou prova de autorização. A versão 100 está sujeita às restrições temporais da ZX02-15/903.

<qrCode xmlns="http://www.portalfiscal.inf.br/nfe"><![CDATA[https://www.sefaz.rs.gov.br/NFCE/NFCECOM.aspx?chNFe=43150108287693000157651010000000971000001251&nVersao=100&tpAmb=2&cDest=99999999000191&dhEmi=323031352d30312d32305431373a30303a34392d30323a3030&vNF=1.00&vICMS=0.00&digVal=2f4a703477714e6d6e4e646d31776b64743936655a486b65354f513d&cIdToken=000001&cHashQRCode=ecc4f0e7e612456f2e3521768bd572b6f0eae240]]></qrCode>

O fragmento é parcial, sem XML completo da nota. CDATA preserva os & do literal legado; os formatos 2 e 3, que usam |, não exigem CDATA segundo a NT. Em produção, os parâmetros devem ser gerados a partir do documento real, sem copiar a chave deste exemplo.

Como conferir parâmetros e mensagens

Nas versões 2 e 3, chave é o primeiro parâmetro, versão o segundo e tipo de ambiente o terceiro. ZX02-228/397 compara a chave do QR com a chave da nota; ZX02-244/397 compara o ambiente com ide/tpAmb. ZX02-236/398 trata versão divergente do previsto. Parâmetro ausente está vinculado a 396 nas regras específicas correspondentes; não se confunde com a mesma informação presente, porém divergente.

Na contingência, compare dia e valor total com dhEmi e vNF; ZX02-268 e ZX02-276 tratam essas divergências. Para assinatura offline v3, confronte o conteúdo exato assinado e o certificado pertinente conforme o procedimento oficial, sem substituir por hash CSC da v2. A mensagem completa informa qual parâmetro investigar; um código isolado pode agrupar verificações diferentes.

Como montar e conferir a assinatura offline v3

Na versão 3 offline, o dia da emissão tem exatamente dois dígitos; o valor total usa ponto decimal, sem separador de milhar ou sinais. O tipo de identificação é 1 para CNPJ, 2 para CPF e 3 para identificação de estrangeiro. Se o destinatário não foi identificado, mantenha vazio o parâmetro de tipo. O parâmetro seguinte contém CNPJ ou CPF quando informado; para estrangeiro ou destinatário não identificado, ele permanece vazio. Os separadores | das posições vazias são preservados.

A assinatura é feita sobre a concatenação dos parâmetros de 1 a 7, mantendo os separadores. O Manual v6.0 determina RSA com SHA-1, resultado em Base64 e o mesmo certificado digital que assina a NFC-e. Depois, acrescente o resultado como oitavo parâmetro, separado por |. Isso difere tanto do hash CSC da v2 quanto da assinatura avançada do vínculo PAA: não são credenciais ou mensagens intercambiáveis.

Para investigar a mensagem 583, reconstrua a cadeia original dos sete parâmetros e compare os bytes efetivamente assinados, inclusive posições vazias, dia com zero inicial e valor serializado. Confira o certificado correspondente à nota. Não registre sua chave privada em logs e não substitua a assinatura por um texto Base64 escolhido manualmente. A conferência pode verificar a assinatura com a chave pública apropriada, sem divulgar o material privado. Manual v6.0, tabela 7, p. 30.

Cronograma da v3 e o caso do produtor rural

A NT 2025.001 v1.03 corrigida preserva o cronograma da etapa inicial até 02/06/2025 em teste e até 01/09/2025 em produção. O histórico da revisão v1.01, preservado na v1.03 corrigida, remove a regra ZX02-220/407 de restrição da v3 por UF, considerando a disponibilização do novo leiaute pelas unidades federadas. Por isso, a mensagem 407 rasurada não deve ser apresentada como validação vigente dessa revisão.

Para emitente pessoa física produtor rural, a NT e o Manual v6.0 apresentam a orientação de adoção da v3 com a ressalva do Paraná; ZX02-222/444 trata QR versão 2 com emitente identificado por CPF. Confira a situação da UF e a identificação do emitente antes de transportar uma regra para outro cenário. Para CNPJ, os documentos descrevem a opção de adotar a v3. Esses fatos não permitem afirmar que toda emissão v2 esteja proibida ou que o CSC já tenha sido abolido em qualquer contexto.

As datas publicadas são o cronograma técnico, distinto da situação operacional de uma emissão concreta. O adiamento de outras NTs comunicado em 05/10/2026 não redefine automaticamente essa etapa de 2025. NT 2025.001 v1.03 corrigida, p. 2–3, 5 e 11 e Manual v6.0, p. 29.

Quando o texto está certo e a imagem não é lida

Se a URL do XML e a URL que deveria estar na imagem coincidem, examine também a geração e a impressão. O Manual v6.0 define dimensões mínimas de 25 mm por 25 mm, nível de correção M e codificação UTF-8 para a imagem do QR da NFC-e. Esses parâmetros de imagem são diferentes do limite textual de 60 a 1.000 caracteres de qrCode no XSD.

Compare a imagem digital com a impressão final, verificando cortes e redimensionamentos que afetem a leitura. Uma dificuldade de leitura física não autoriza mudar chave, valor ou assinatura. Primeiro preserve os parâmetros verdadeiros e corrija a geração ou impressão comprovadamente incorreta. A URL base deve vir da relação oficial por UF e ambiente; o Manual permite que uma UF use a mesma base nos dois ambientes, distinguindo-os pelo parâmetro tpAmb. Bases iguais não dispensam a conferência desse parâmetro. Manual v6.0, p. 28 e 31.

Diagnóstico da imagem ao XML original

Primeiro decodifique o QR impresso e compare a URL com infNFeSupl/qrCode. Se os textos diferem, investigue gerador de imagem, cache e documento usado na impressão. Se coincidem, separe endereço oficial e parâmetros, preservando maiúsculas, minúsculas e todos os separadores.

Depois confira UF, ambiente, chave, versão e forma de emissão no XML. Se a consulta não encontra a nota, confirme o endpoint, o ambiente e a situação pelo serviço apropriado antes de concluir que ela foi rejeitada. A existência do QR também não comprova autorização, especialmente em contingência offline. Corrija a causa comprovada na origem, preservando o documento fiscal e seu estado.

Fontes oficiais

Referência técnica para integração

XPath completo
/nfeProc/NFe/infNFeSupl/qrCode
Namespace
http://www.portalfiscal.inf.br/nfe
Leiaute
4.00 · PL_010e_v1.02
Ocorrências no XSD
1–1 no contexto do elemento pai
Tipo
inline:xs:string · string
Preenchimento no catálogo
Condicional

A ocorrência vale dentro da estrutura XML: um campo obrigatório em um grupo opcional não torna esse grupo obrigatório. A aplicação fiscal depende da operação e da versão da regra.

maxLength
1000
minLength
60
pattern
((HTTPS?|https?)://.*\?chNFe=[0-9]{6}[0-9A-Z]{12}[0-9]{26}&nVersao=100&tpAmb=[1-2](&cDest=([A-Za-z0-9.:+-/)(]{0}|[A-Za-z0-9.:+-/)(]{5,20})?)?&dhEmi=[A-Fa-f0-9]{50}&vNF=(0|0\.[0-9]{2}|[1-9]{1}[0-9]{0,12}(\.[0-9]{2})?)&vICMS=(0|0\.[0-9]{2}|[1-9]{1}[0-9]{0,12}(\.[0-9]{2})?)&digVal=[A-Fa-f0-9]{56}&cIdToken=[0-9]{6}&cHashQRCode=[A-Fa-f0-9]{40})
pattern
((HTTPS?|https?)://.*\?p=([0-9]{6}[0-9A-Z]{12}[0-9]{16}(1|3|4)[0-9]{9})\|[2]\|[1-2]\|(0|[1-9]{1}([0-9]{1,5})?)\|[A-Fa-f0-9]{40})
pattern
((HTTPS?|https?)://.*\?p=([0-9]{6}[0-9A-Z]{12}[0-9]{16}(1|3|4)[0-9]{9})\|[3]\|[1-2])
pattern
((HTTPS?|https?)://.*\?p=([0-9]{6}[0-9A-Z]{12}[0-9]{16}(9)[0-9]{9})\|[3]\|[1-2]\|([0]{1}[1-9]{1}|[1-2]{1}[0-9]{1}|[3]{1}[0-1]{1})\|(0|0\.[0-9]{2}|[1-9]{1}[0-9]{0,12}(\.[0-9]{2})?)\|((1|2|3)?)\|((([0-9A-Z]{12}[0-9]{2})|([0-9]{11}))?)\|([a-zA-Z0-9+/]+[=]{0,2}))
pattern
((HTTPS?|https?)://.*\?p=([0-9]{6}[0-9A-Z]{12}[0-9]{16}9[0-9]{9})\|[2]\|[1-2]\|([0]{1}[1-9]{1}|[1-2]{1}[0-9]{1}|[3]{1}[0-1]{1})\|(0|0\.[0-9]{2}|[1-9]{1}[0-9]{0,12}(\.[0-9]{2})?)\|[A-Fa-f0-9]{56}\|(0|[1-9]{1}([0-9]{1,5})?)\|[A-Fa-f0-9]{40})
whiteSpace
preserve
InícioDicionárioRejeições