Масове створення QR-кодів: від CSV до готових до друку файлів

Масове створення QR-кодів - це два виклики API на рядок і папка в результаті. Створіть коротке посилання для кожного призначення, згенеруйте QR-код для цього короткого посилання, запишіть SVG і PNG на диск. Електронна таблиця з 5 000 товарами за кілька хвилин перетворюється на 5 000 готових до друку файлів.

Інструменти не визначають рішення. Важливо, що саме кодує код. Закодуйте призначення безпосередньо - і в момент відправлення коду до друку він зафіксується, тож одна неправильна URL-адреса в партії з 5 000 наклейок означає, що всю партію доведеться викинути; закодуйте коротке посилання під вашим контролем - і призначення назавжди залишиться редагованим, а кожен код непомітно звітуватиме про власні сканування.

Потрібен один код, а не тисячі? Як створити QR-код - це простіший практичний посібник, а QR-кодова кампанія з нуля охоплює розміщення та вимірювання результатів.

Конвеєр у чотири етапи

Залиште в CSV стовпець id, навіть якщо він здається зайвим. Він стане назвою файлу, ключем ідемпотентності та значенням, за яким ви зіставлятимете дані, коли команда дизайну поверне результат зі словами "code 412 is wrong". Без нього ви зіставлятимете дані за URL-адресами, а вони довгі й у них легко помилитися.

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)

Ключ ідемпотентності формується з призначення, тож повторний запуск файлу після виправлення трьох рядків нічого не створить двічі й нічого не коштуватиме. Саме ця властивість робить масове завдання безпечним для повторення, і її варто добре зрозуміти, перш ніж спрямовувати цей скрипт на 5 000 рядків: у матеріалі про ліміти частоти запитів та ідемпотентність описано механіку.

Наведений вище цикл послідовний, і для кількох сотень рядків цього достатньо. Для більших обсягів запускайте приблизно вісім операцій паралельно; у посібниках про Python та JavaScript є шаблон обмеженої паралельності, який можна безпосередньо використати.

Хочете запустити його? Створіть ключ на безкоштовному плані, експортуйте ELIDO_API_KEY і спочатку спрямуйте скрипт на CSV із п'ятьма рядками, а не на справжній файл.

Статичні чи динамічні: масове використання

Статичний код має рівно одну перевагу: він ні від чого не залежить. Не потрібно підтримувати домен і постійно платити за сервіс. Це важливо для коду, вигравіруваного на машині, яка переживе ваш контракт із постачальником, і майже ні для чого іншого.

У всьому іншому переважають динамічні коди. Кількість сканувань для кожного коду - це єдиний спосіб порівняти розміщення на полицях або в магазинах. Призначення можна виправити, коли сторінка кампанії переміститься. А коди виходять меншими й розрідженішими, бо коротке посилання містить лише частину символів маркованої URL-адреси товару. У матеріалі Динамічні та статичні QR-коди наведено повне порівняння.

Параметри друку, які справді важливі

Три параметри визначають, чи скануватиметься партія у реальному світі.

Корекція помилок. Рівень M відновлюється приблизно після 15 відсотків пошкоджень і зберігає код розрідженим. Переходьте на Q, якщо логотип розташований посередині, код братимуть у руки, його можуть потерти або надрукувати на вигнутій поверхні. H звучить безпечніше, але зазвичай таким не є: додаткова надлишковість додає модулі, а щільніші коди важче сканувати на малих розмірах. У стандарті QR-кодів описано всі чотири рівні.

Формат. SVG для друку, оскільки його можна масштабувати до плаката без розмивання країв модулів. PNG - для слайдів, маркетплейсів і всього, що не приймає векторні формати. Запросіть обидва формати одним запитом і не витрачайте час на ще один обмін, коли комусь знадобиться другий.

Тиха зона. Порожнє поле навколо коду є його частиною. Визначений мінімум становить чотири модулі, але дизайнери регулярно обрізають його, бо воно здається марним простором. Код із вузькою рамкою погано сканується дешевими камерами телефонів, і ніхто не пов'язує ці дві причини.

Перед тим як зафіксувати розмір для всієї партії, варто знати ще одне: обсяг даних визначає версію, а версія - кількість модулів у коді. Denso Wave, яка винайшла цей формат, публікує таблицю версій і місткості. Коротке посилання завдовжки 30 символів розташовується ближче до нижньої межі; маркована URL-адреса товару завдовжки 180 символів - ні, і за однакового розміру друку різниця проявляється у помітно щільнішому коді.

Розмір у файлі менш важливий, ніж розмір на об'єкті. У матеріалі Яким має бути розмір QR-коду наведено правило відстані сканування, яке визначає фізичний розмір.

Перевірте все до того, як щось піде до друку

Створіть партію, а потім навмання перевірте п'ять кодів. Не на столі при максимальній яскравості екрана: надрукуйте їх у фактичному розмірі, приклейте один до полиці або упаковки та відскануйте з місця, де стояв би покупець.

Потім перевірте сам редирект. Команда curl -sI для трьох коротких посилань підтвердить, що вони повертають редирект на правильне призначення. Це виявляє класичну помилку зі зміщенням на один стовпець, коли другий стовпець CSV читається як третій і кожен код вказує на сусідній товар. Вона непомітна, переживає всі візуальні перевірки й видна лише в призначенні.

Збережіть CSV, з якого створено партію, разом з ідентифікатором, призначенням, коротким посиланням і назвою файлу. Коли через пів року хтось запитає, який код нанесено на яку палету, відповідь буде в цьому файлі, а відновити її з дашборду набагато складніше, ніж зберегти файл.

Де з'являються сканування

Коли коди запрацюють, кожен звітуватиме окремо. У цьому і є вся причина мати один код для кожного товару, а не один спільний: один код показує, що кампанія спрацювала, а коди для окремих товарів показують, який магазин, полиця або SKU спрацювали.

У матеріалі Як відстежувати сканування QR-кодів описано читання цих даних, а матеріал про вебхуки для подій посилань - надсилання сканувань у власні системи замість перевірки дашборду. Для контексту фізичних товарів у матеріалі про QR-коди цифрового паспорта товару описано нормативну версію того самого конвеєра.

Ознайомтеся з основною серією

Цей матеріал належить до кластера функцій. Почніть із як створити QR-код для версії з одним кодом, а потім перейдіть до QR-кодової кампанії з нуля, присвяченої дизайну кампанії. На сторінці функції QR-кодів описано можливості стилізації, які цей скрипт пропускає.

Пов'язані матеріали в блозі

• Динамічні чи статичні QR-коди: який варіант потрібен вам
• Яким має бути розмір QR-коду для друку?
• Як відстежувати сканування QR-кодів
• Масовий імпорт коротких посилань із Google Sheet