xCpl da retirada na NF-e: complemento, galpão e referência do endereço

retirada/xCpl registra o complemento do endereço do local de retirada. É opcional e, quando informado, aceita texto de 1 a 60 caracteres. Pode acrescentar uma identificação documentada, como bloco, galpão ou portão, sem substituir logradouro, número, bairro ou município. MOC 7.0, F05, p. 15.

Quando o complemento ajuda a identificar o local

O dado vem da informação complementar do endereço de origem física selecionado para a operação. Se dois acessos ou galpões compartilham o mesmo logradouro e número, o complemento pode distinguir o ponto de retirada. Essa utilidade precisa corresponder ao local real; não é um motivo para preencher texto fictício quando o cadastro não possui complemento.

Por ser opcional na estrutura, um endereço confirmado sem informação complementar pode omitir a tag. Isso é diferente de apagar um valor existente durante uma mudança de tela, normalização de cadastro ou importação. Um complemento já informado pode ser relevante para distinguir o ponto de saída e deve ser preservado até sua revisão.

O grupo retirada se destina ao endereço diferente do remetente. Um complemento cadastrado não exige criar o grupo em toda nota. A NT 2026.002 v1.10a, F01-10/669 restringe sua presença em NFC-e e NF-e com DANFE Simplificado Tipo 2 (tpImp=6). A linha de cronograma correspondente indica teste 01/07/2026 e produção 03/08/2026; confira modelo, ambiente e autorizador no diagnóstico real.

Como separar complemento e outras informações

O complemento pode descrever uma parte adicional do endereço, mas não deve receber o município inteiro, uma lista de produtos, instruções tributárias ou observações gerais sobre a nota. Cada um desses dados possui outro contexto. Também não resolve a ausência do campo obrigatório nro: colocar “Galpão 120” em xCpl não elimina a necessidade de representar o número do endereço no campo próprio.

Uma referência operacional deve ser avaliada pela sua relação com a localização documentada. O grupo não é um campo livre para guardar qualquer instrução do pedido. Confirmar galpão ou portão é uma conferência de endereço; decidir a documentação fiscal de um depósito de terceiros depende da operação e de seus participantes.

O limite 60 não autoriza truncar silenciosamente um complemento. Se o final do texto identifica outro bloco ou acesso, o corte muda a informação. Confirme uma representação compatível que preserve a identidade do mesmo local.

Texto vazio, espaços e caracteres XML

O TLocal/xCpl do pacote anterior 010c v1.30 usa TString, mínimo 1 e máximo 60. Se não há conteúdo, a tag opcional não é gerada; <xCpl/> não atende ao mínimo. Espaços nas extremidades também precisam ser conferidos conforme o padrão lexical de texto.

Caracteres de endereço não devem ser removidos porque fazem parte da sintaxe XML. O gerador deve escapar os caracteres reservados corretamente. Um & textual é serializado como &; isso não significa que a palavra “amp” pertença ao complemento. Não confunda conteúdo depois da leitura XML com o tamanho bruto da entidade no arquivo.

Exemplo de complemento em um endereço parcial

O fragmento é sintético e parcial: nome de rua, número e complemento são fictícios, e os demais campos do grupo foram omitidos. Não é XML completo para transmissão:

<retirada xmlns="http://www.portalfiscal.inf.br/nfe">
  <!-- Identificação e demais campos de endereço foram omitidos. -->
  <xLgr>Rua de Exemplo</xLgr>
  <nro>120</nro>
  <xCpl>Galpão A &amp; B</xCpl>
</retirada>

O conteúdo lido de xCpl é “Galpão A & B”. A entidade preserva o caractere, e o texto explica a parte adicional do endereço. Não se afirma que o local exista ou que esse complemento seja apropriado para a operação do leitor.

O XPath é /nfeProc/NFe/infNFe/retirada/xCpl. A posição é depois de nro e antes de xBairro, quando o complemento existir. Use o namespace da NF-e; o complemento em dest/enderDest/xCpl pertence ao destinatário, enquanto entrega/xCpl descreve o ponto de destino físico.

Como investigar complemento perdido ou falha de schema

Compare o valor da operação/cadastro com o XML gerado. Se havia complemento confirmado e a prévia o omitiu, confira a associação do local, o mapeamento do campo e qualquer rotina que transforma um valor manual em vazio. Se o XML apresenta complemento de entrega, investigue a troca de origem entre endereços.

Para falha estrutural, confira conteúdo vazio, comprimento, espaços nas extremidades, caracteres reservados não escapados e sequência dos filhos. Uma falha ao ler um & literal pode ser de sintaxe XML, antes mesmo de conferir o schema. Não invente um código exclusivo de rejeição de complemento sem comprovação no retorno.

Corrija a origem ou serialização comprovadamente incorreta, preservando o conteúdo verdadeiro, e confira nova prévia. Não troque complemento por texto genérico, não edite XML assinado nem retransmita por tentativa. Número da retirada e logradouro da retirada aprofundam a divisão do endereço.