Automatizar códigos QR com Python: biblioteca ou API REST?

O que faz uma biblioteca Python

Quem quer gerar códigos QR com Python encontra várias bibliotecas livres. Transformam um texto numa imagem, muitas vezes também num SVG, localmente e sem serviço. Para etiquetas com números de série, documentos internos ou acessos Wi-Fi é exatamente o indicado.

Onde as imagens estáticas chegam ao limite

Um código QR gerado assim é estático, o conteúdo está no próprio padrão. Se o destino muda por causa de uma remodelação do site, se um erro de escrita só é notado depois da impressão ou se queres saber quantas vezes é lido, ele não ajuda. Para isso existem os códigos QR dinâmicos: o Same-QR guarda o destino atrás de um endereço curto e constante, conta as leituras e verifica de noite se cada destino está acessível.

Códigos QR dinâmicos pela API REST

A API está em https://sameqr.com/api/v1. Cria no painel, em Conta, “Acesso para CLI, scripts e agentes”, uma chave, “leitura + escrita” para criar, e define-a como variável de ambiente SAMEQR_API_KEY. Este exemplo usa apenas a biblioteca padrão:

import json, os, urllib.request

API = "https://sameqr.com/api/v1"
KEY = os.environ["SAMEQR_API_KEY"]

def rufe(methode, weg, daten=None):
    req = urllib.request.Request(
        API + weg, method=methode,
        data=json.dumps(daten).encode() if daten else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)

code = rufe("POST", "/qr", {"name": "Anleitung Modell A", "targetUrl": "https://example.com/anleitung-a"})
print(code["id"])

Se a API responder com um erro, o urlopen lança uma exceção. O conteúdo traz sempre um objeto error com status, code e message. Trata-o, em vez de deixares o script continuar às cegas.

Um fluxo da prática

Um fabricante imprime em cada embalagem um código QR para o manual:

• O script lê a lista de produtos de um ficheiro CSV.
• Para cada novo produto cria um código QR e guarda o seu identificador ao lado do número do artigo.
• Quando sai uma nova versão do manual, altera só o destino com PATCH em /qr/<id>. Para isso precisa de uma chave “total” e do cabeçalho X-Confirm com a versão lida.
• Um segundo script com chave de leitura obtém uma vez por mês o número de leituras.

Conta com os limites: no máximo 10 alterações de destino por hora e 30 por dia pela API, 120 pedidos por minuto por chave, e por hora 60 no plano gratuito, 300 no Start, 1.000 no Pro e 5.000 no Agentur. Em caso de 429, esperas os segundos indicados no cabeçalho Retry-After.

Chave segura no script

• Nunca escrevas a chave no ficheiro .py, lê-a do ambiente.
• Para scripts que só leem, usa uma chave “só leitura”.
• Uma chave própria por script, com um nome claro e uma validade adequada.

Conclusão: porquê o Same-QR

Para códigos QR estáticos, uma biblioteca chega. Assim que se imprime, o Same-QR é a melhor base: uma API REST simples em todos os planos, erros compreensíveis, proteção contra substituições em paralelo e destinos que ainda podes alterar depois da impressão.

Começa já: regista-te gratuitamente em sameqr.com, 20 códigos QR dinâmicos são gratuitos para sempre. API, CLI e servidor MCP existem em todos os planos, a documentação está em sameqr.com/entwickler.

Perguntas frequentes