Массовая генерация QR-кодов: от CSV до файлов, готовых к печати

Массовая генерация QR-кодов - это два вызова API на строку и папка в результате. Создайте короткую ссылку для каждого адреса назначения, получите QR-код для этой короткой ссылки и запишите SVG и PNG на диск. Таблица с 5000 товарами за несколько минут превращается в 5000 файлов, готовых к печати.

Инструмент здесь не главное. Главное - то, что кодирует QR-код. Если закодировать адрес назначения напрямую, код застывает в момент отправки в печать, поэтому одна неверная ссылка в тираже из 5000 наклеек превращает в брак весь тираж; если закодировать короткую ссылку под вашим контролем, адрес назначения навсегда остаётся редактируемым, а каждый код незаметно сообщает о собственных сканированиях.

Генерируете один код, а не тысячи? В статье Как создать QR-код приведено более простое пошаговое руководство, а QR-кампания с нуля охватывает размещение и измерение результатов.

Пайплайн в четыре этапа

Оставьте в CSV столбец id, даже если он кажется избыточным. Он станет именем файла, ключом идемпотентности и идентификатором, по которому вы будете искать нужную запись, когда команда дизайна сообщит: «код 412 неверен». Без него вам придётся сопоставлять записи по URL, а 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)

Ключ идемпотентности строится на основе адреса назначения, поэтому повторный запуск файла после исправления трёх строк ничего не создаст дважды и ничего не будет стоить. Именно это свойство делает массовую задачу безопасной для повторного запуска. Его стоит как следует понять, прежде чем направлять скрипт на 5000 строк: в статье Лимиты частоты запросов и идемпотентность описана механика.

Цикл выше выполняется последовательно, и этого достаточно для нескольких сотен строк. Для большего объёма запускайте примерно восемь операций параллельно; в руководствах по 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 Таблиц