Gerar um código de barras GS1QR é simples até que a carga útil contenha um Separador de Grupo. Esse único caractere não imprimível, ASCII 29, é o que indica ao scanner onde termina um campo de Identificador de Aplicação de comprimento variável. Os desenvolvedores contornaram isso com montagem manual de bytes, codificadores personalizados ou divisão da carga útil, e cada solução alternativa trazia o risco de produzir símbolos que são escaneados, mas não são analisados.

Aspose.BarCode for Python via .NET 26.6 resolve esse problema com uma única flag. A propriedade encode_gs1_separator_in_byte_mode força o codificador QR a escrever os separadores de grupo GS1 e o caractere % como bytes brutos, preservando a estrutura exata do GS1. Este tutorial cobre todo o fluxo de trabalho de geração e reconhecimento de códigos de barras em python‑net: instalação do SDK, geração de um símbolo GS1QR compatível e verificação, ao nível do ponto de código, de que o separador sobreviveu ao ciclo completo.

Por que os Separadores GS1 em Modo Byte são Importantes para Códigos de Barras GS1QR

GS1QR é o transportador bidimensional preferido na cadeia de suprimentos, saúde e varejo, onde um único símbolo deve conter um identificador de produto, número de lote, data de validade e número de série em um payload estruturado. A sintaxe do Identificador de Aplicação GS1 torna isso possível, mas depende do Separador de Grupo para delimitar campos cujo comprimento não é fixo.

Considere uma carga útil que combina o AI (10) para número de lote e o AI (21) para número de série. Ambos são de comprimento variável, portanto o scanner precisa de um delimitador explícito entre eles. Sem um separador codificado corretamente, um sistema downstream lê uma única string concatenada em vez de dois campos. O código de barras é escaneado com sucesso e ainda assim entrega dados incorretos, o pior tipo de falha, porque nada no evento de leitura sinaliza o problema.

A codificação em modo byte resolve isso na origem. O codificador deixa de interpretar o separador como um marcador estrutural e o grava literalmente no segmento de dados. Os benefícios práticos para desenvolvedores Python são diretos:

  • Conformidade. O símbolo emitido corresponde às Especificações Gerais da GS1 em vez de aproximá‑las.
  • Código mais simples. Sem montagem manual de bytes, sem subclasse de codificador personalizada, sem passagem de pós‑processamento.
  • Testabilidade. A ida e volta pode ser verificada em um teste unitário ao afirmar os pontos de código decodificados.

Gerando códigos de barras GS1QR usando Aspose.BarCode for Python

Aspose.BarCode for Python via .NET fornece uma API de alto nível para geração e reconhecimento de códigos de barras. Instale-a a partir do PyPI:

pip install aspose-barcode-for-python-via-net

Duas classes realizam a maior parte do trabalho. BarcodeGenerator, de aspose.barcode.generation, cria e renderiza símbolos. BarCodeReader, de aspose.barcode.barcoderecognition, decodifica-os. As configurações de geração são acessadas por meio de uma árvore de parâmetros na instância do gerador, onde opções específicas de simbologia, como as configurações de QR, estão sob parameters.barcode.qr.

Material de referência está disponível na página do produto, no site de documentação, e na referência da API.

Se você possui um arquivo de licença, aplique‑o uma vez na inicialização da aplicação, antes de qualquer chamada de geração ou reconhecimento:

from aspose.barcode import License

license = License()
license.set_license("Aspose.BarCode.Python.NET.lic")

Gerar código de barras GS1QR com separador em modo byte

  1. Importe os tipos necessários - BarcodeGenerator e EncodeTypes para geração, BarCodeReader e DecodeType para verificação.
  2. Instancie BarcodeGenerator com EncodeTypes.GS1QR e uma string de carga útil GS1. Parênteses denotam seções AI, como em (10)ASPOSE2001(21)ASPOSE2026.
  3. Habilite a codificação do separador em modo byte definindo gen.parameters.barcode.qr.encode_gs1_separator_in_byte_mode = True.
  4. Defina a resolução de saída para que o símbolo renderizado seja utilizável tanto em impressão quanto na tela.
  5. Salve a imagem em um formato sem perdas, depois leia‑a novamente para confirmar a codificação.

O exemplo a seguir demonstra o fluxo de trabalho completo:

from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType
from aspose.barcode.generation import BarcodeGenerator, EncodeTypes

# 1. Create a GS1QR Barcode with Sample AI Data
# (10) = Batch or Lot Number, (21) = Serial Number
gen = BarcodeGenerator(EncodeTypes.GS1QR, "(10)ASPOSE2001(21)ASPOSE2026")

# 2. Turn on Byte-Mode Encoding for GS1 Group Separators
gen.parameters.barcode.qr.encode_gs1_separator_in_byte_mode = True

# 3. Set a Print-Ready Resolution
gen.parameters.resolution = 300

# 4. Save the Barcode to a PNG File
gen.save("gs1qr_test.png")

# 5. Verify by Reading the Barcode Back
reader = BarCodeReader("gs1qr_test.png", DecodeType.GS1QR)
for result in reader.read_bar_codes():
    print("BarCode CodeText: " + result.code_text)

Como funciona

  • BarcodeGenerator(EncodeTypes.GS1QR, "(10)ASPOSE2001(21)ASPOSE2026") cria um gerador configurado para a simbologia GS1QR. A carga útil usa a sintaxe GS1, onde (10) é o AI de Número de Lote ou Lote e (21) é o AI de Número de Série. A biblioteca analisa a forma entre parênteses e insere os separadores que a especificação requer.
  • gen.parameters.barcode.qr.encode_gs1_separator_in_byte_mode = True ativa a opção introduzida na versão 26.6. Com ela habilitada, o codificador grava o separador de grupo e % como bytes brutos no segmento de dados em vez de interpretá‑los.
  • gen.parameters.resolution = 300 renderiza a 300 DPI. Símbolos apenas para tela ficam bem no padrão, mas qualquer coisa destinada a uma impressora de etiquetas ou arte de embalagem deve ser gerada na resolução de impressão em vez de ser ampliada posteriormente.
  • gen.save("gs1qr_test.png") grava um PNG sem perdas, preservando o padrão exato dos módulos. Isso é mais importante para símbolos 2D do que para 1D, pois um decodificador QR amostra uma grade e não tolera limites de módulo borrados.
  • read_bar_codes() devolve um iterável de objetos BarCodeResult, e result.code_text contém a carga útil decodificada incluindo quaisquer caracteres de controle. Em um console, o separador não é exibido, o que explica exatamente por que a próxima seção inspeciona pontos de código em vez de confiar na saída impressa.

Ler e Verificar o Código de Barras Gerado

Imprimir a string decodificada prova que o símbolo é legível, não que esteja correto. Como o separador de grupo não é imprimível, uma carga útil com um separador ausente e outra com um separador correto parecem idênticas em um terminal. A verificação deve ocorrer no nível do ponto de código, o que também facilita a asserção em uma suíte de testes.

Etapas

  1. Carregue o PNG salvo com BarCodeReader e DecodeType.GS1QR.
  2. Itere sobre os resultados decodificados.
  3. Inspecione o ponto de código Unicode de cada caractere, procurando por U+001D.
  4. Divida a carga útil no separador e compare os campos com a entrada original.
from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType

GROUP_SEPARATOR = "\x1d"

# Load the Barcode Image Generated Earlier
reader = BarCodeReader("gs1qr_test.png", DecodeType.GS1QR)
results = list(reader.read_bar_codes())

if not results:
    raise ValueError("No GS1QR barcode was detected in the image.")

for result in results:
    decoded = result.code_text
    print("Decoded GS1QR payload:", decoded)

# Inspect the Code Point of Every Character
    for index, char in enumerate(decoded):
        label = repr(char) if char.isprintable() else "<non-printable>"
        print(f"Char {index}: {label} (U+{ord(char):04X})")

# Confirm the Separator Survived the Round Trip
    if GROUP_SEPARATOR in decoded:
        fields = decoded.split(GROUP_SEPARATOR)
        print(f"Separator found. Payload splits into {len(fields)} field(s):")
        for field in fields:
            print("  -", field)
    else:
        print("Warning: no group separator present in the decoded payload.")

Como funciona

  • Configurar o leitor com DecodeType.GS1QR restringe o reconhecimento a essa simbologia, o que é mais rápido e seguro do que escanear todos os tipos, pois impede que um símbolo malformado seja decodificado como QR simples e passe silenciosamente.
  • Materializar os resultados com list(...) antes da verificação torna o caso de vazio explícito. Uma falha de reconhecimento devolve um iterável vazio em vez de lançar exceção, portanto um loop for desprotegido sobre uma leitura falhada termina silenciosamente e relata sucesso.
  • O loop de pontos de código é a asserção real. Ver U+001D na saída confirma que o modo byte funcionou; sua ausência significa que o separador foi descartado ou transformado, independentemente de quão limpo o payload impresso pareça.
  • Dividir em \x1d reconstrói os campos AI individuais, fornecendo valores que podem ser comparados com os dados de origem em um pipeline CI.

Obtenha uma Licença Gratuita

A Aspose oferece uma licença temporária gratuita que remove as marcas d’água de avaliação e desbloqueia toda a funcionalidade para testes. Solicite uma na página de licença temporária da Aspose.

Recursos Adicionais Gratuitos

Conclusão

A opção encode_gs1_separator_in_byte_mode substitui uma categoria de manipulação manual de bytes por um único booleano. Defina‑a nos parâmetros QR e os separadores de grupo GS1, juntamente com o caractere %, são gravados no símbolo exatamente como a especificação exige.

Este tutorial abordou a instalação, a geração de um símbolo GS1QR com separadores em modo byte e a verificação do resultado no nível de ponto de código, em vez de confiar na saída do console. Essa etapa de verificação é a parte que mais vale a pena manter. Nos fluxos de trabalho GS1, um código de barras que é escaneado não é o mesmo que um código de barras que está correto, e uma asserção de ponto de código em sua suíte de testes é o que diferencia os dois antes que os rótulos cheguem à produção.

Perguntas Frequentes

  1. O que a opção encode_gs1_separator_in_byte_mode faz? Ele instrui o codificador QR a emitir o separador de grupo GS1 (ASCII 29) e o caractere % como dados brutos de byte, em vez de tratá‑los como marcadores estruturais, de modo que eles permaneçam intactos na carga útil do código de barras.

  2. Preciso de uma licença especial para usar os recursos GS1QR? GS1QR faz parte da biblioteca padrão Aspose.BarCode. Você pode avaliá‑la sem licença e solicitar uma licença temporária gratuita no site da Aspose para remover as marcas d’água de avaliação.

  3. Posso usar esse recurso com outros tipos de código QR? Não. A bandeira se aplica ao tipo de codificação GS1QR. Codificadores QR padrão e Micro QR a ignoram, pois a análise do Identificador de Aplicação GS1 não se aplica a eles.

  4. A imagem do código de barras gerada é sem perdas? Salvar em PNG, o padrão, produz uma imagem sem perdas que preserva o padrão exato dos módulos. Evite JPEG para códigos de barras, pois seus artefatos de compressão borram as bordas dos módulos e reduzem as taxas de leitura.

  5. Como verifico se o separador foi codificado corretamente? Leia a imagem novamente com BarCodeReader usando DecodeType.GS1QR e inspecione os pontos de código da string decodificada. Um U+001D na carga útil confirma que o separador de grupo foi codificado em modo byte.

  6. A ativação do modo byte afeta o tamanho do código de barras? O modo byte pode exigir mais bits de dados do que o modo alfanumérico, o que pode fazer o símbolo avançar para uma versão QR maior. A biblioteca seleciona automaticamente a menor versão que cabe, portanto o aumento costuma ser de no máximo um passo de versão.

  7. Qual versão do Aspose.BarCode introduziu esta opção?
    A propriedade encode_gs1_separator_in_byte_mode foi adicionada no Aspose.BarCode for Python via .NET 26.6. Versões anteriores exigem manipulação manual de bytes para incorporar separadores de grupo.

Leia Mais