Quantidade de volumes na NF-e: como preencher qVol sem contar os produtos

qVol informa a quantidade de volumes transportados descritos em um grupo vol. Seu caminho é /nfeProc/NFe/infNFe/transp/vol/qVol. O número vem da contagem física correspondente à expedição, não automaticamente da quantidade de unidades comerciais nem do número de itens da NF-e.

O MOC 7.0, campo X27 documenta ocorrência de zero a um e de 1 a 15 algarismos. O PL_010c efetivamente consultado usa texto com padrão [0-9]{1,15}: somente algarismos, sem sinal e sem fração. A definição é de uma contagem, mesmo que o tipo técnico seja string; isso não transforma a tag em uma identificação livre como nVol.

Volume, item e unidade comercial são diferentes

Uma nota com três itens pode ter uma caixa que contém todos eles. Uma linha com 120 unidades de produto pode ser expedida em dez caixas, cada uma contendo 12 unidades. Nessas hipóteses, contar linhas ou copiar qCom não produz a quantidade de volumes. O dado precisa representar o conjunto de embalagens efetivamente documentado.

Confira a relação de expedição e como a carga foi preparada. Caixas internas, pacotes consolidados e paletização podem criar dúvida sobre o nível de agrupamento representado. O schema não decide qual desses objetos é o volume da operação. Esclareça a organização real e o critério aplicável antes de contar; não some caixas e paletes que contêm as mesmas caixas como se fossem conjuntos independentes sem examinar essa relação.

A espécie em esp deve permitir compreender o conjunto contado. A identificação em nVol conserva a numeração dos volumes, mas não calcula qVol. Uma faixa terminada em CX010 não prova dez caixas: pode representar apenas CX007 a CX010 ou ter lacunas que exigem conferência.

Exemplo: 120 unidades em dez caixas

Na hipótese fictícia, a expedição confirmou dez caixas com 12 unidades comerciais cada, totalizando 120 unidades. A parte de volumes pode ser:

<vol xmlns="http://www.portalfiscal.inf.br/nfe">
  <qVol>10</qVol>
  <esp>CAIXAS</esp>
  <nVol>CX001 A CX010</nVol>
</vol>

qVol=10 conta caixas; as 120 unidades pertencem ao contexto dos produtos. O cálculo 10 × 12 = 120 é apenas a conferência da hipótese, não uma fórmula para qualquer nota. Se as caixas contiverem quantidades distintas, o total de produtos precisa ser conferido pelos dados reais. O trecho é sintético, parcial e não está pronto para transmissão.

Não escreva 120 em qVol para fazê-lo coincidir com a venda. Também não escreva 10 CAIXAS: a quantidade vai em qVol, e a descrição da espécie fica em esp.

Como contar quando há vários grupos vol

Cada vol tem sua própria quantidade. Para quatro caixas e dois sacos que constituem conjuntos distintos, a organização parcial pode ser:

<vol xmlns="http://www.portalfiscal.inf.br/nfe">
  <qVol>4</qVol>
  <esp>CAIXAS</esp>
</vol>
<vol xmlns="http://www.portalfiscal.inf.br/nfe">
  <qVol>2</qVol>
  <esp>SACOS</esp>
</vol>

Há dois grupos XML e seis volumes físicos nesta hipótese. O número de grupos vol não é o total de volumes. A soma de quatro e dois só é válida porque os conjuntos são distintos. Não coloque o total seis em ambos os grupos; isso produziria uma contagem duplicada. Se um grupo não informa quantidade, o simples número de registros não permite descobrir a contagem ausente.

O limite de até 5.000 ocorrências de vol é o limite de registros dentro de transp. Ele não limita qVol a 5.000. Esse campo tem seu próprio padrão de até 15 algarismos. Mesmo quando um valor cabe nesse formato, sua correspondência com a expedição deve ser comprovada. Veja a organização dos volumes para vincular também pesos e lacres aos mesmos conjuntos.

Formato: inteiros, zeros e separadores

O padrão do campo não aceita 2.5, 2,5, +2, -2, espaços ou texto de unidade. Uma contagem de volumes não deve ser arredondada para tornar uma quantidade fracionária aceitável. Se a origem traz uma fração, confira se ela é quantidade de produto, peso ou outra informação enviada ao campo errado; não invente uma contagem inteira.

Para mil volumes, a representação numérica é 1000, sem pontuação de milhares. Os zeros iniciais eventualmente aceitos não convertem a contagem em código de embalagem. Se você precisa preservar um código como 0010 ou CX0010 para identificar o volume, sua finalidade é diferente e deve ser representada no campo próprio conforme a documentação.

Ausência, carga sem contagem confirmada e erros

qVol é opcional no leiaute consultado, mas <qVol/> não satisfaz o mínimo de um algarismo. Omitir o campo e enviar zero são situações distintas. Zero admitido pelo padrão não deve ser usado automaticamente para “não informado”; também não se deve escolher um como padrão para toda operação a granel ou sem contagem conhecida. A representação exigível do caso concreto depende da carga e de seus registros.

Quando a quantidade divergir, compare a relação de expedição, os conjuntos contados e a eventual sobreposição de agrupamentos. Quando a integração acusar conteúdo inválido, localize o XPath no XML e confira decimal, sinal, separadores, vazio e limite de 15 algarismos. Não trate qVol como valor monetário com casas decimais. Na sequência de vol, ele vem antes de esp e dos demais filhos presentes.

Nenhum desses exames comprova sozinho a validade da carga ou autoriza o XML completo. Examine o retorno real antes de atribuir uma rejeição específica. O MOC e o PL_010c citados, confrontados com documentos posteriores consultados até 26/09/2026, sustentam a distinção entre contagem, formato e contexto; não constituem prova de implantação das regras na UF.