GZip na distribuição de DF-e

O que é GZip e por que ele aparece na distribuição de DF-e?

GZip é um formato de compactação de arquivos muito usado na internet. Ele reduz o tamanho dos dados sem perder nenhuma informação. Depois de descompactado, o conteúdo volta a ser exatamente igual ao original.

Na distribuição de DF-e, os documentos fiscais são XMLs, que costumam ser grandes e repetitivos. Compactá-los diminui o volume de dados trafegado entre o ambiente do fisco e o sistema da empresa. Assim, uma única resposta pode trazer vários documentos de forma mais leve e rápida.

Como o XML chega compactado na resposta?

Na consulta de distribuição da NF-e, por exemplo, cada documento retornado vem dentro de um elemento chamado docZip. O conteúdo desse elemento não é o XML legível, e sim o XML compactado em GZip e depois codificado em Base64.

O Base64 transforma os bytes compactados em texto comum, permitindo que eles sejam transportados dentro de outro XML sem corromper os dados. Junto com o docZip vêm informações como o NSU, que identifica a posição do documento na sequência de distribuição, e o schema, que indica o tipo de conteúdo, como um resumo da nota, a nota completa ou um evento.

Como transformar o docZip de volta em XML?

O processo tem duas etapas, sempre nesta ordem. Primeiro, decodifica-se o texto Base64, obtendo os bytes compactados. Depois, descompacta-se esses bytes com GZip, obtendo o XML original em texto.

Praticamente todas as linguagens de programação já trazem bibliotecas para Base64 e GZip, então a tarefa costuma exigir poucas linhas de código. Após a descompactação, o sistema lê o atributo schema para saber como interpretar o XML e onde armazená-lo.

Quais erros são comuns ao lidar com GZip na distribuição?

Um erro frequente é tentar ler o conteúdo do docZip diretamente como XML, sem decodificar nem descompactar. Outro é inverter a ordem das etapas, tentando descompactar antes de decodificar o Base64, o que gera falha imediata.

Também é comum problemas de codificação de caracteres depois da descompactação, quando o texto não é lido como UTF-8 e acentos aparecem corrompidos. Por fim, alguns sistemas descompactam corretamente, mas ignoram o schema e misturam resumos, notas completas e eventos no mesmo lugar.

O GZip é usado só na NF-e?

Não. O mesmo padrão de XML compactado em GZip e codificado em Base64 aparece em outros serviços de distribuição, como o do CT-e. No Padrão Nacional da NFS-e, a compactação GZip com Base64 também é usada no tráfego de XMLs entre os sistemas e o ambiente nacional.

Por isso, entender esse formato é útil para qualquer integração fiscal que baixe documentos em volume. Em uma API fiscal que já faz esse tratamento, o sistema do cliente pode receber o XML pronto, sem precisar lidar diretamente com a compactação.

Exemplos de GZip na distribuição de DF-e

• Um ERP consulta a distribuição de DF-e para buscar notas emitidas contra o CNPJ da empresa, recebe vários elementos docZip e, para cada um, decodifica o Base64, descompacta com GZip e salva o XML na guarda de documentos fiscais.
• Uma transportadora recebe na distribuição um docZip com schema de evento, descompacta o conteúdo e identifica que se trata de um cancelamento de CT-e relacionado a uma carga.
• Um desenvolvedor investiga um log de integração fiscal em que o XML salvo aparece como texto ilegível e descobre que o sistema gravou o conteúdo Base64 sem descompactar o GZip.
• Uma plataforma integrada a uma API fiscal recebe os XMLs de NF-e já descompactados em formato legível, junto com o status, sem implementar a lógica de GZip internamente.