У QRsir появился API. Теперь QR-коды можно создавать не только руками в кабинете, но и запросом из своей системы: интернет-магазина, CRM, 1С, скрипта на сервере. В ответ приходит короткая ссылка и готовая картинка — в векторе для типографии и растром для экрана. Назначение кода при этом остаётся изменяемым: напечатанный QR продолжит работать, даже если завтра он должен вести совсем в другое место.

Ключ выдаётся в личном кабинете, в разделе «Ключи API», и входит в бесплатный аккаунт. Доступны все 14 типов кодов, что есть в кабинете, — от обычной ссылки до мини-сайта и маршрутизатора. Полный справочник методов открыт без регистрации.

Ниже — не пересказ документации, а разбор: когда генерация кодов машиной действительно окупается, а когда это лишняя сложность. С примерами из практики и кодом, который можно скопировать.

Сначала — когда API не нужен

Честный разговор стоит начать с этого. Если вам нужна просто картинка — QR со ссылкой на чеке, в письме, на экране кассы, — возьмите бесплатную библиотеку для своего языка и рисуйте локально. Это быстрее, не зависит от чужого сервиса и ничего не стоит. Никакой API для такой задачи не нужен, и мы не будем убеждать в обратном.

Разница появляется в момент, когда код печатают. Тираж каталога, партия упаковки, наклейки на оборудовании, бейджи участников — это уже вложенные деньги и физические предметы, которые нельзя отозвать. Если внутри картинки зашит конкретный адрес, то переезд сайта, смена акции или обновление документа превращают весь тираж в мусор. У динамического кода картинка фиксированная, а назначение живёт на сервере, и его меняют одним запросом.

Второе, чего не даёт локальная библиотека, — обратная связь. Нарисованная у себя картинка молчит: сколько раз её отсканировали, с каких устройств, в какие дни — узнать неоткуда. Динамический код отвечает на эти вопросы, потому что каждое сканирование проходит через сервис.

Итого простое правило: картинка на один раз — библиотека, код на бумаге и надолго — сервис. А API нужен тогда, когда таких кодов становится не десять, а сотни, и заводить их руками — значит держать человека на операции, которую машина делает за миллисекунду.

Три строчки, с которых всё начинается

Прежде чем перейти к примерам — как это выглядит вживую. Вот полноценное создание кода:

curl -X POST https://qrsir.ru/api/v1/codes \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"type":"url","title":"Каталог","target_url":"https://example.ru/catalog"}'

В ответ приходит JSON: id кода, короткая ссылка short_url, которую кодирует QR, и адреса картинок в SVG и PNG. Всё. Это обычный HTTP с JSON — подойдёт PHP, Python, JavaScript, C#, Java, 1С и даже curl из планировщика задач. Отдельную библиотеку ставить не нужно.

Пример 1. Интернет-магазин: вкладыш в посылке

Как обычно. В коробку кладут листовку «отсканируйте и оставьте отзыв». Код на всех листовках один и тот же — его сделали руками год назад. Работает ли он, сколько людей сканируют, из каких заказов — неизвестно. Через полгода акция закончилась, а листовок напечатано ещё на три месяца вперёд.

Что меняется. Код создаётся в момент оформления заказа и печатается на вкладыше вместе с накладной. Ведёт он на страницу конкретного заказа: отзыв, статус доставки, инструкция к товару.

$ch = curl_init('https://qrsir.ru/api/v1/codes');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Key: qrs_ваш_ключ', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'type'       => 'url',
        'title'      => 'Заказ № ' . $orderId,
        'target_url' => 'https://example.ru/orders/' . $orderId . '/review',
    ], JSON_UNESCAPED_UNICODE),
]);
$qr = json_decode(curl_exec($ch), true);

// $qr['short_url']       — ссылка, которую кодирует QR
// $qr['images']['png']   — адрес картинки для макета накладной
// $qr['id']              — сохраните рядом с заказом, пригодится

Что это даёт на самом деле. Не «красиво», а три конкретные вещи. Первая: видно долю сканирований — сколько покупателей вообще обращают внимание на вкладыш. Обычно эта цифра оказывается сильно ниже ожидаемой, и это повод переделать сам вкладыш, а не печатать его ещё сто тысяч. Вторая: после праздников ту же пачку вкладышей можно перевести с «оставьте отзыв» на «повторите заказ со скидкой» — коды уже уехали к покупателям, но ведут они туда, куда вы скажете сегодня. Третья: код привязан к заказу, поэтому по сканированию видно, кто именно пришёл, — без промокодов и опросов.

Оговорка. Сейчас предел — 200 новых кодов в сутки на аккаунт. Магазину с тремя десятками заказов в день этого хватает с запасом, а вот при пяти сотнях заказов схема «код на заказ» уже не сработает — там разумнее делать код на партию вкладышей: одна тысяча листовок с одним кодом, следующая тысяча со своим. Статистика по партиям всё равно останется.

Пример 2. Производство: паспорт изделия, который можно обновить

Как обычно. На упаковке или шильдике печатают QR со ссылкой на PDF: инструкция, паспорт, сертификат, декларация соответствия. Файл лежит на сайте по адресу вроде /files/instr-2024-v3.pdf. Выходит новая редакция — и начинается: либо старый файл держат вечно, чтобы не сломать напечатанные коды, либо ссылка тихо превращается в 404, и клиент со сканером в руках видит ошибку.

Что меняется. В API есть тип file: сначала файл загружается к нам, потом на него заводится код. Обновилась редакция — загрузили новый файл и переставили назначение. Коды на выпущенных изделиях не трогали вообще.

# 1. Загрузили паспорт изделия
curl -X POST https://qrsir.ru/api/v1/uploads \
  -H "X-Api-Key: qrs_ваш_ключ" \
  -F "file=@passport-2026.pdf"
# → {"url":"https://qrsir.ru/uploads/8f3c1d0b2a94.pdf", "name":"passport-2026.pdf", ...}

# 2. Завели код на партию
curl -X POST https://qrsir.ru/api/v1/codes \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"type":"file","title":"Партия 2026-08",
       "payload":{"url":"https://qrsir.ru/uploads/8f3c1d0b2a94.pdf",
                  "name":"Паспорт изделия.pdf"}}'

# 3. Через полгода — новая редакция. Коды на изделиях не трогаем
curl -X PATCH https://qrsir.ru/api/v1/codes/1042 \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"payload":{"url":"https://qrsir.ru/uploads/c4b1e07a2f65.pdf",
                  "name":"Паспорт изделия, ред. 2.pdf"}}'

Неочевидная польза. Статистика по таким кодам показывает то, чего не видно иначе: документацию читают не в момент покупки, а спустя недели и месяцы — когда что-то сломалось или потребовалось обслуживание. Это меняет отношение к самой документации. Пока считалось, что паспорт изделия никто не открывает, его делали формально. Когда видно, что за год по коду прошли сотни сканирований, появляется смысл вкладываться в понятную инструкцию — и держать её актуальной.

Пример 3. Сеть точек: один код в общем макете

Как обычно. Федеральная реклама, листовки или упаковка одинаковые для всех городов, а вести код должен в разные места: в меню конкретного заведения, на страницу ближайшего магазина, к местному телефону. Обычно это решают так: печатают код на общую страницу «выберите город» — и теряют часть людей прямо на ней.

Что меняется. Тип router — код, который выбирает назначение по правилам: город, устройство, время суток, диапазон дат. Один QR в макете, а решение принимается в момент сканирования.

curl -X POST https://qrsir.ru/api/v1/codes \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{
    "type": "router",
    "title": "Общий код на упаковке",
    "payload": {
      "rules": [
        {"time_from":"23:00", "time_to":"07:59",   "target":"nT5vR8c"},
        {"city":"Москва",                          "target":"aB3xK9m"},
        {"city":"Санкт-Петербург",                 "target":"pQ7wL2z"}
      ],
      "default": "kD4hY6b"
    }
  }'

Важная деталь. Правила проверяются сверху вниз, и срабатывает первое подходящее. Поэтому ночное правило стоит первым: если поставить его после городских, то москвич в два часа ночи попадёт в обычное меню и увидит закрытое заведение. Порядок правил здесь — не оформление, а логика.

Зачем тут API. Правила можно задать и руками, но список точек живёт в вашей учётной системе: открылся город — правило должно появиться само, закрылась точка — исчезнуть. В target можно передавать не только внутренний id, но и короткий код — то, что вы и так храните рядом с точкой.

Оговорка, которую стоит проговорить клиенту. Город определяется по IP-адресу. Это уровень города, а не GPS: корпоративный интернет, мобильный оператор или VPN иногда покажут не тот город. Правило «по городу» — про «как обычно», а не «всегда», поэтому под ним обязательно должен стоять разумный default, а на самой странице — возможность выбрать город вручную.

Пример 4. Мероприятие: бейджи, по которым обмениваются контактами

Как обычно. На бейдже — имя и компания. Дальше по классике: «дайте визитку», «сфотографируйте бейдж», «запишите телефон». Половина контактов теряется в тот же вечер.

Что меняется. На каждого участника заводится vCard-код и печатается на бейдже. Сосед по секции наводит камеру — контакт сохраняется в телефон целиком: имя, компания, должность, телефон, почта.

import requests

API  = "https://qrsir.ru/api/v1"
HEAD = {"X-Api-Key": "qrs_ваш_ключ"}

for g in guests:                                # список из вашей регистрации
    qr = requests.post(f"{API}/codes", headers=HEAD, json={
        "type":  "vcard",
        "title": f"Бейдж — {g['last']} {g['first']}",
        "payload": {
            "first": g["first"], "last":  g["last"],
            "org":   g["company"], "job": g["job"],
            "phone": g["phone"], "email": g["email"],
        },
    }).json()

    png = requests.get(f"{API}/codes/{qr['id']}.png?size=600", headers=HEAD)
    open(f"badges/{g['id']}.png", "wb").write(png.content)

Что это даёт. Во-первых, обмен контактами перестаёт требовать усилий — а значит, происходит. Во-вторых, у организатора появляется цифра, которой раньше не было: сколько бейджей вообще сканировали. Это прямая мера того, насколько мероприятие сработало как площадка для знакомств, — и хороший аргумент в разговоре со спонсорами на следующий год.

Практическая деталь. Генерировать бейджи лучше заранее и партиями: суточный предел — 200 кодов, так что список на 600 человек разбивается на три дня. Картинку берите в SVG, если бейджи печатает типография: вектор не рассыпается на любом размере.

Пример 5. Оборудование и аренда: код на предмете, за которым живая карточка

Как обычно. На кулере, огнетушителе, кондиционере, арендной квартире или самокате висит наклейка с телефоном сервиса и, если повезёт, датой обслуживания, написанной маркером. Дата устаревает через месяц, телефон меняется через год.

Что меняется. На каждую единицу заводится код типа minisite — небольшая страница со своими цветами, заголовком, текстом и кнопками. Наклейка печатается один раз, а содержимое страницы обновляет ваша учётная система после каждого выезда мастера.

curl -X PATCH https://qrsir.ru/api/v1/codes/2051 \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"payload":{"subheading":"Обслужен 12.08.2026 · следующее ТО — 12.02.2027"}}'

Обратите внимание: в запросе только одно поле. У мини-сайта правка частичная — заголовок, текст, цвета и кнопки остаются на месте, меняется ровно то, что вы прислали. Поэтому обновление даты из учётной системы — это одна строчка, а не пересборка всей страницы.

Что это даёт. Пропадает целый класс работы: не нужно заводить сайт под каждую единицу техники и не нужно печатать новые наклейки при смене телефона или подрядчика. А человек, который стоит перед сломавшимся оборудованием, получает не просто номер, а страницу с кнопкой «вызвать мастера» и историей обслуживания — это заметно снижает число звонков «а к кому вообще обращаться».

Где ещё это просят

Сценарии, которые встречаются реже, но устроены так же:

  • Гарантийные талоны. Код на талоне ведёт на страницу гарантии; условия меняются — талоны не перепечатывают.
  • Коды в коммерческих предложениях. CRM создаёт код при формировании КП — и видно, открывал ли клиент приложенные материалы.
  • Пропуска и бейджи сотрудников. Код ведёт на карточку сотрудника; уволился — назначение переставили, пластик не выбрасывали.
  • Экспозиции и таблички. Музеи, выставки, ботанические сады: подпись у экспоната печатается один раз, а текст за кодом можно дополнять годами.
  • Wi-Fi в номерах и залах. Тип wifi: пароль меняется по расписанию из скрипта, таблички на столах остаются те же.

Чего API пока не умеет

Об этом лучше знать до начала работы, чем обнаружить на второй день.

  • Пакетной генерации нет. Коды создаются по одному, предел — 200 в сутки на аккаунт и 60 запросов в минуту на ключ. Для конвейера с миллионами уникальных кодов это не подходит. Мы отложили массовый режим намеренно: сначала посмотрим, как пойдёт поштучная генерация, и по реальным запросам решим, каким он должен быть. Если ваш случай именно такой — напишите, это влияет на очерёдность работ.
  • Картинку нельзя отдать прямо в вёрстку. Изображение доступно только по ключу, а ключ в HTML показывать нельзя. Обычный порядок такой: вы забираете картинку запросом и храните её у себя рядом с заказом или карточкой товара. Публичные ссылки на картинки в планах.
  • Уведомлений о сканированиях нет. Статистику нужно запрашивать самому — вебхуков пока не сделано.

Как начать

  1. Войдите в кабинет и откройте раздел «Ключи API». Ключ показывается один раз — скопируйте его сразу, второй раз мы его не покажем.
  2. Заведите отдельный ключ на каждую интеграцию: сайт, CRM, внутренний скрипт. Тогда ненужный можно отозвать, не ломая остальные.
  3. Сделайте первый запрос из примера выше — код сразу появится в кабинете наравне с созданными вручную.
  4. Загляните в справочник: там по каждому из 14 типов кодов расписаны поля и лежит готовое тело запроса, которое можно скопировать.

Ключ входит в бесплатный аккаунт вместе с кодами, мини-сайтами и виджетами — платить и договариваться не нужно. Если после чтения останется вопрос «а мой случай так решается?» — напишите, разберём: такие письма и определяют, что мы делаем следующим.