Masowe generowanie kodów QR: od CSV do plików gotowych do druku

Masowe generowanie kodów QR to dwa wywołania API na wiersz i jeden folder na końcu. Utwórz krótki link dla każdego miejsca docelowego, wyrenderuj kod QR dla tego krótkiego linku, zapisz SVG i PNG na dysku. Arkusz z 5000 produktów zamienia się w 5000 plików gotowych do druku w kilka minut.

Narzędzie nie jest tu najważniejszą decyzją. Liczy się to, co koduje kod. Zakoduj miejsce docelowe bezpośrednio, a kod zostanie zamrożony w chwili wysłania do druku, więc jeden błędny URL w serii 5000 naklejek oznacza, że cała seria trafia na złom; zakoduj kontrolowany przez siebie krótki link, a miejsce docelowe pozostanie edytowalne na zawsze, a każdy kod będzie po cichu raportował własne skany.

Tworzysz jeden kod, a nie tysiące? Jak utworzyć kod QR to prostszy przewodnik, a Kampania z kodem QR od podstaw omawia umieszczanie i pomiary.

Pipeline w czterech etapach

Zachowaj kolumnę id w CSV, nawet jeśli wydaje się zbędna. Staje się nazwą pliku, kluczem idempotencji i elementem, po którym dopasujesz dane, gdy zespół projektowy odeśle wiadomość "kod 412 jest nieprawidłowy". Bez niej dopasowujesz dane po URL-ach, a URL-e są długie i łatwo je wpisać z błędem.

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)

Klucz idempotencji jest wyprowadzany z miejsca docelowego, więc ponowne uruchomienie pliku po poprawieniu trzech wierszy nie utworzy niczego podwójnie i nic nie kosztuje. Ta właściwość sprawia, że zadanie masowe można bezpiecznie powtarzać. Warto ją dobrze zrozumieć, zanim skierujesz skrypt na 5000 wierszy: limity szybkości i idempotencja omawiają szczegóły.

Pętla powyżej działa sekwencyjnie, co jest w porządku dla kilku setek wierszy. Powyżej tej liczby uruchom około ośmiu zadań równolegle; przewodniki dotyczące Pythona i JavaScriptu zawierają wzorzec ograniczonej współbieżności, który możesz bezpośrednio wykorzystać.

Chcesz uruchomić skrypt? Utwórz klucz w darmowym planie, wyeksportuj ELIDO_API_KEY i skieruj skrypt najpierw na pięciowierszowy plik CSV, zanim użyjesz prawdziwego pliku.

Statyczne czy dynamiczne, na dużą skalę

Kod statyczny ma dokładnie jedną zaletę: nie zależy od niczego. Nie potrzebuje działającej domeny ani usługi, za którą trzeba stale płacić. Ma to znaczenie w przypadku kodu wyrytego w maszynie, która będzie działać dłużej niż twoja umowa z dostawcą, i niemal nigdzie indziej.

Wszystko inne przemawia za rozwiązaniem dynamicznym. Liczniki skanów dla każdego kodu, bo tylko one pozwalają porównać miejsca na półkach lub lokalizacje placówek. Miejsce docelowe, które możesz poprawić, gdy strona kampanii się przeniesie. Oraz mniejsze, rzadsze kody, ponieważ krótki link ma ułamek liczby znaków otagowanego URL produktu. Dynamiczne i statyczne kody QR zawierają pełne porównanie.

Ustawienia druku, które naprawdę mają znaczenie

O tym, czy partię da się zeskanować w prawdziwym świecie, decydują trzy parametry.

Korekcja błędów. Poziom M odzyskuje dane po około 15 procentach uszkodzeń i utrzymuje kod na tyle rzadkim, by można go było skanować. Przejdź na Q, gdy logo znajduje się pośrodku albo kod będzie dotykany, wycierany lub drukowany na czymś zakrzywionym. H brzmi bezpieczniej, ale zwykle taki nie jest: dodatkowa nadmiarowość oznacza więcej modułów, a gęstsze kody trudniej skanować w małych rozmiarach. Standard QR opisuje wszystkie cztery poziomy.

Format. SVG do druku, ponieważ skaluje się do rozmiaru plakatu bez zmiękczania krawędzi modułów. PNG do slajdów, marketplace'ów i wszędzie tam, gdzie wektory są odrzucane. Poproś o oba formaty w jednym żądaniu, a unikniesz dodatkowej rundy, gdy ktoś będzie potrzebować drugiego.

Strefa ciszy. Pusty margines wokół kodu jest częścią kodu. Określone minimum to cztery moduły, a projektanci regularnie go przycinają, bo wygląda jak zmarnowane miejsce. Kod z ciasną ramką źle skanuje się tanimi aparatami w telefonach i nikt nigdy nie łączy tych dwóch faktów.

Jeszcze jedna rzecz, którą warto wiedzieć, zanim ustalisz jeden rozmiar dla całej partii: ilość danych decyduje o wersji, a wersja decyduje o liczbie modułów kodu. Denso Wave, firma, która wynalazła ten format, publikuje tabelę wersji i pojemności. Krótki link o długości 30 znaków znajduje się blisko jej dolnego zakresu, a otagowany URL produktu o długości 180 znaków już nie, a różnica jest widoczna jako znacznie gęstszy kod przy tym samym rozmiarze wydruku.

Rozmiar pliku ma mniejsze znaczenie niż rozmiar na obiekcie. Jak duży powinien być kod QR zawiera regułę odległości skanowania, która decyduje o wymiarach fizycznych.

Zweryfikuj wszystko przed wysłaniem do druku

Wygeneruj partię, a następnie losowo sprawdź pięć kodów. Nie na biurku przy pełnej jasności ekranu: wydrukuj je w rzeczywistym rozmiarze, przyklej jeden do półki lub opakowania i zeskanuj z miejsca, w którym stałby klient.

Następnie sprawdź samo przekierowanie. curl -sI dla trzech krótkich linków potwierdza, że zwracają przekierowanie do właściwego miejsca docelowego. Wychwytuje to klasyczny błąd o jeden element, w którym druga kolumna CSV została odczytana jako trzecia i każdy kod wskazuje sąsiedni produkt. Ten błąd jest cichy, przechodzi każdą kontrolę wizualną i można go zobaczyć tylko w miejscu docelowym.

Zachowaj CSV, z którego powstała partia, wraz z identyfikatorem, miejscem docelowym, krótkim linkiem i nazwą pliku. Gdy ktoś za sześć miesięcy zapyta, który kod znajduje się na której palecie, odpowiedzią będzie ten plik, a odtworzenie go z dashboardu wymaga znacznie więcej pracy niż jego zachowanie.

Gdzie pojawiają się skany

Gdy kody są już aktywne, każdy z nich raportuje osobno. To cały powód tworzenia jednego kodu na element zamiast jednego wspólnego kodu: pojedynczy kod mówi, że kampania zadziałała, a kody per element pokazują, która placówka, półka lub SKU zadziałało.

Jak śledzić skany kodów QR omawia odczytywanie tych danych, a webhooki dla zdarzeń linków opisują przesyłanie skanów do własnych systemów zamiast sprawdzania dashboardu. W kontekście produktów fizycznych kody QR cyfrowego paszportu produktu omawiają regulacyjną wersję tego samego pipeline'u.

Przeczytaj serię artykułów filarowych

Ten artykuł należy do klastra funkcji. Zacznij od jak utworzyć kod QR, czyli wersji dotyczącej pojedynczego kodu, a następnie przeczytaj Kampanię z kodem QR od podstaw, która omawia projektowanie kampanii. Strona funkcji kodów QR opisuje opcje stylizacji pominięte w tym skrypcie.

Powiązane na blogu

• Dynamiczne i statyczne kody QR: którego potrzebujesz
• Jak duży powinien być kod QR do druku?
• Jak śledzić skany kodów QR
• Masowy import krótkich linków z Google Sheet