Geração de códigos QR em massa: de um CSV a arquivos prontos para impressão

A geração de códigos QR em massa envolve duas chamadas de API por linha e uma pasta no final. Crie um link curto para cada destino, gere um código QR para esse link curto e grave o SVG e o PNG no disco. Uma planilha com 5.000 produtos vira 5.000 arquivos prontos para impressão em poucos minutos.

A ferramenta não é a decisão. O que o código codifica é. Codifique o destino diretamente e o código fica congelado no momento em que vai para a impressão, então uma única URL errada em uma tiragem de 5.000 adesivos significa que toda a tiragem será descartada; codifique um link curto que você controla e o destino continuará editável para sempre, enquanto cada código informa discretamente suas próprias leituras.

Vai criar um código, não milhares? Como criar um código QR é o guia mais simples, e Campanha de códigos QR do zero aborda posicionamento e mensuração.

O pipeline em quatro etapas

Mantenha uma coluna id no CSV, mesmo que isso pareça redundante. Ela se torna o nome do arquivo, a chave de idempotência e o elemento usado na correspondência quando a equipe de design enviar a mensagem "o código 412 está errado". Sem ela, você fará a correspondência pelas URLs, que são longas e fáceis de digitar errado.

import csv, base64, hashlib, pathlib, os, requests

API = "https://api.elido.app"
HEAD = {"Authorization": f"Bearer {os.environ['ELIDO_API_KEY']}"}
out = pathlib.Path("qr-out")
out.mkdir(exist_ok=True)

with open("products.csv") as f:
    for row in csv.DictReader(f):        # columns: id, destination
        key = hashlib.sha256(row["destination"].encode()).hexdigest()

        link = requests.post(
            f"{API}/v1/links",
            headers={**HEAD, "Idempotency-Key": key},
            json={"destination_url": row["destination"]},
            timeout=10,
        )
        link.raise_for_status()
        short_url = link.json()["short_url"]

        qr = requests.post(
            f"{API}/v1/qr/generate",
            headers=HEAD,
            json={
                "content": short_url,          # the short link, never the destination
                "formats": ["svg", "png"],
                "size": 1024,
                "error_correction": "M",
            },
            timeout=20,
        )
        qr.raise_for_status()
        payload = qr.json()

        (out / f"{row['id']}.svg").write_text(payload["svg"])
        (out / f"{row['id']}.png").write_bytes(base64.b64decode(payload["png"]))
        print(row["id"], short_url)

A chave de idempotência é derivada do destino, então executar o arquivo novamente depois de corrigir três linhas não cria nada duas vezes nem custa nada. Essa propriedade é o que torna seguro repetir um trabalho em massa, e vale a pena entendê-la corretamente antes de apontar isto para 5.000 linhas: limites de requisições e idempotência aborda os detalhes.

O loop acima é sequencial, o que funciona bem até algumas centenas de linhas. Depois disso, execute cerca de oito em paralelo; os guias de Python e JavaScript têm um padrão de concorrência limitada que você pode reutilizar diretamente.

Quer executar? Crie uma chave no plano gratuito, exporte ELIDO_API_KEY e aponte o script para um CSV com cinco linhas antes de apontá-lo para o arquivo real.

Estático ou dinâmico, em escala

Um código estático tem exatamente uma vantagem: ele não depende de nada. Nenhum domínio para manter ativo, nenhum serviço para continuar pagando. Isso importa para um código gravado em uma máquina que sobreviverá ao seu contrato com o fornecedor, e quase nunca importa em outros casos.

Todo o resto favorece o dinâmico. Contagens de leituras por código, que são a única forma de comparar posições em prateleiras ou locais de lojas. Um destino que você pode corrigir quando a página da campanha mudar. E códigos menores e mais esparsos, porque um link curto é uma fração dos caracteres de uma URL de produto com parâmetros de rastreamento. Códigos QR dinâmicos versus estáticos traz a comparação completa.

Configurações de impressão que realmente importam

Três parâmetros determinam se o lote será lido no mundo real.

Correção de erros. O nível M recupera aproximadamente 15% de danos e mantém o código esparso. Passe para Q quando houver um logotipo no centro ou quando o código for manuseado, sofrer arranhões ou for impresso em algo curvo. H parece mais seguro e geralmente não é: a redundância extra inclui mais módulos, e códigos mais densos são mais difíceis de ler em tamanhos pequenos. O padrão QR documenta os quatro níveis.

Formato. SVG para impressão, porque escala para um pôster sem suavizar as bordas dos módulos. PNG para apresentações, marketplaces e qualquer coisa que rejeite vetores. Peça os dois em uma única requisição e evite uma nova rodada quando alguém precisar do outro.

Zona de silêncio. A margem em branco ao redor do código faz parte do código. Quatro módulos é o mínimo especificado, e os designers a cortam sistematicamente porque ela parece espaço desperdiçado. Um código com uma borda apertada é lido mal por câmeras de celulares baratos, e ninguém jamais relaciona as duas coisas.

Há mais uma coisa que vale a pena saber antes de fixar um tamanho para todo o lote: a quantidade de dados determina a versão, e a versão determina quantos módulos o código tem. A Denso Wave, que inventou o formato, publica a tabela de versões e capacidades. Um link curto de 30 caracteres fica perto da parte inferior da tabela; uma URL de produto com parâmetros de rastreamento e 180 caracteres não, e a diferença aparece como um código visivelmente mais denso no mesmo tamanho impresso.

O tamanho no arquivo importa menos do que o tamanho no objeto. Qual deve ser o tamanho de um código QR apresenta a regra de distância de leitura que determina a dimensão física.

Verifique antes de qualquer coisa ir para a impressão

Gere um lote e depois verifique cinco códigos aleatoriamente. Não na sua mesa com o brilho máximo da tela: imprima-os no tamanho real, prenda um na prateleira ou na embalagem e faça a leitura do local onde um cliente ficaria.

Depois, verifique o próprio redirecionamento. Executar curl -sI em três dos links curtos confirma que eles retornam um redirecionamento para o destino correto, o que detecta o clássico erro de deslocamento em que a coluna dois do CSV foi lida como a coluna três e todos os códigos apontam para o produto vizinho. Esse erro é silencioso, passa por toda verificação visual e só aparece no destino.

Guarde o CSV que produziu o lote, com o id, o destino, o link curto e o nome do arquivo. Quando alguém perguntar daqui a seis meses qual código está em qual palete, esse arquivo será a resposta, e regenerá-lo a partir do dashboard dá muito mais trabalho do que mantê-lo.

Onde as leituras aparecem

Quando os códigos estiverem ativos, cada um informará seus dados separadamente. Essa é a razão de ter um código por item, em vez de um código compartilhado: um único código informa que a campanha funcionou, e os códigos por item informam qual loja, prateleira ou SKU funcionou.

Como acompanhar leituras de códigos QR explica como ler esses dados, e webhooks para eventos de links explica como enviar as leituras para os seus próprios sistemas, em vez de consultar um dashboard. Especificamente para o contexto de produtos físicos, códigos QR para passaporte digital de produto aborda a versão regulatória do mesmo pipeline.

Leia a série principal

Este artigo faz parte do cluster de funcionalidades. Comece por como criar um código QR para a versão de um único código e depois leia campanha de códigos QR do zero para o design da campanha. A página de funcionalidades de códigos QR aborda as opções de estilo que este script não contempla.

Relacionados no blog

• Códigos QR dinâmicos versus estáticos: qual você precisa
• Qual deve ser o tamanho de um código QR para impressão?
• Como acompanhar leituras de códigos QR
• Importe links curtos em massa de uma Planilha Google