xCpl do destinatário na NF-e: complemento, omissão e formato XML

dest/enderDest/xCpl acrescenta o complemento do endereço do destinatário, como a identificação de uma sala, apartamento ou bloco. A tag é opcional dentro de enderDest; quando existe, precisa conter de 1 a 60 caracteres compatíveis com o tipo textual do leiaute.

Seu caminho é /nfeProc/NFe/infNFe/dest/enderDest/xCpl, no namespace http://www.portalfiscal.inf.br/nfe. O campo complementa o endereço cadastral do destinatário, que pode ser diferente do local de entrega. MOC 7.0, E08, p. 14.

Complemento identifica a unidade ou detalhe do endereço

O valor vem do endereço confirmado na documentação e no cadastro do destinatário. xLgr identifica o logradouro, nro seu número ou identificação cadastral correspondente, e xCpl acrescenta um detalhe necessário para localizar a unidade ou completar a identificação.

Sala, apartamento e bloco não devem substituir automaticamente o número do imóvel. Se uma importação trouxe “Rua de Exemplo, 120A, Sala 3” numa única coluna, separar os componentes exige confirmar qual parte corresponde a cada campo. Não deduza a separação apenas pela primeira sequência de algarismos.

Instruções como horário de recebimento, telefone do motorista ou “ligar antes de chegar” não passam a ser complemento cadastral por caberem no limite. O campo não é uma observação geral da venda. Use-o para a identificação efetiva do endereço, sem copiar dados pessoais ou instruções operacionais desnecessárias.

Os homônimos emit/enderEmit/xCpl, entrega/xCpl e retirada/xCpl descrevem outros endereços. Um apartamento usado para entrega pode não ser a unidade cadastral do destinatário. Confira o XPath e a origem selecionada pela integração antes de comparar os valores.

Omissão, vazio e preservação do dado

A ocorrência 0–1 significa que a tag pode não aparecer no grupo e, se aparecer, ocorre uma vez. Isso é diferente de enviar <xCpl/>: a tag vazia tem zero caracteres, enquanto o conteúdo informado precisa ter pelo menos um. Texto formado somente por espaços também não resolve a restrição do tipo textual.

Quando o endereço não tem complemento, a ausência da tag representa essa condição sem criar conteúdo artificial. Quando o cadastro contém uma unidade verdadeira, a opcionalidade estrutural não é uma instrução para apagar o dado. Preservar a identificação ajuda a evitar que um endereço de prédio com várias unidades seja reduzido apenas à porta principal.

Um formulário que recolhe a seção de complemento não deve, por esse motivo, limpar o valor já cadastrado. Da mesma forma, um campo sem edição na tela não demonstra que a tag não existe no XML. Compare cadastro, regra de seleção do endereço e resultado da geração.

O limite é de caracteres do conteúdo, não de bytes UTF-8. Uma integração que trunca por bytes pode cortar uma letra acentuada ou alterar o texto. Se o complemento ultrapassa o limite, revise sua representação cadastral com a fonte responsável; não remova aleatoriamente o dado que distingue a unidade.

Exemplo parcial com caractere especial

O fragmento é parcial e sintético. Assume que o complemento demonstrativo contém um & no texto confirmado:

<enderDest xmlns="http://www.portalfiscal.inf.br/nfe">
  <xLgr>Rua de Exemplo</xLgr>
  <nro>120A</nro>
  <xCpl>Bloco A &amp; Sala 3</xCpl>
  <xBairro>Bairro de Exemplo</xBairro>
</enderDest>

No XML serializado, & representa o caractere & do conteúdo. O parser entrega o texto Bloco A & Sala 3; a sequência de escape não é um novo detalhe do endereço. Um & sem escape quebra a sintaxe XML, enquanto escapar duas vezes pode gerar literalmente & no valor lido. Deixe a biblioteca de serialização tratar esse escape. MOC 7.0 — Visão Geral, p.51.

O trecho mostra a ordem de xCpl, depois de nro e antes de xBairro, mas omite município e UF obrigatórios e o restante da nota. Não é um XML pronto para transmitir nem prova da existência desse endereço.

Conferência do cadastro à geração

Para falha de estrutura, confira a grafia xCpl, uma única ocorrência, posição na sequência, conteúdo não vazio, comprimento e espaços nas extremidades. Para falha de sintaxe, confira escape e codificação antes de atribuir o problema ao cadastro.

Para complemento errado ou ausente, compare o documento do endereço, o cadastro atual e o XML gerado. Investigue se a integração trouxe o complemento da entrega, juntou o complemento ao número, perdeu o valor num campo oculto ou truncou uma importação. São causas diferentes e exigem conferir a origem, não apenas substituir a tag.

Corrija o cadastro ou mapeamento comprovadamente errado no fluxo autorizado e confira a nova geração. Não edite XML assinado, invente uma sala ou retransmita para testar um texto. xCpl não define tributação, CFOP ou condição de contribuinte do destinatário.

Campos relacionados

enderDest no contexto do destinatário, nro no contexto do destinatário, xLgr no contexto do destinatário.