Для разработчиков

API динамических
QR-кодов

Создавайте коды прямо из своей системы: интернет-магазина, CRM, 1С или скрипта. Один запрос — и у вас короткая ссылка и готовая картинка в SVG и PNG. Назначение кода можно менять сколько угодно раз, а напечатанный QR продолжит работать.

Получить ключ Справочник методов

Когда QR-коды пора генерировать программно

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

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

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

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

Типовые сценарии

Маркировка партий и продукции. Свой код на партию, за ним — инструкция, сертификат или паспорт изделия. Документ обновился — заменили файл, коды на упаковках не трогали.
Персональные коды клиентов. Код в личном кабинете, на карте лояльности или в приложении, у каждого свой — и по нему видно, кто и когда его использовал.
Документы и накладные. Код на бумажном документе ведёт на его электронную версию. Особенно полезно там, где бумага живёт годами, а система за это время меняется.
Коды из CRM. Сделка создана — код сгенерирован и подставлен в коммерческое предложение или договор. Менеджер не открывает никаких сторонних сервисов.
Мероприятия и пропуска. Бейдж с кодом на визитку участника, на программу или на карту площадки; программа поменялась за день до начала — обновили назначение.

Что стоит знать заранее

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

Ещё одно ограничение, о котором лучше знать до начала работы: картинка кода отдаётся только по ключу, поэтому вставить её прямо в вёрстку чужого сайта через <img src> нельзя — ключ в разметке показывать нельзя. Обычный порядок такой: вы забираете картинку запросом и храните у себя вместе с заказом или карточкой товара.

Что умеет API

🔗

Код одним запросом

POST с названием и назначением — в ответе короткая ссылка, которую кодирует QR, и адреса картинок. Дальше код живёт в вашем кабинете наравне с созданными вручную.

🖼

Картинка в SVG и PNG

Вектор для типографии, растр для экрана и документов. Оформление — цвета, форма точек, рамка с подписью, логотип в центре — задаётся прямо в запросе.

♻️

Назначение меняется

Запрос PATCH переставляет код на другой адрес. Короткая ссылка и картинка остаются прежними, поэтому напечатанные коды продолжают работать.

🧩

Все 14 типов кодов

Ссылка, текст, мини-сайт, визитка, Wi-Fi, звонок, WhatsApp, Telegram, письмо, SMS, файл, геометка, событие и маршрутизатор — всё, что есть в кабинете.

📊

Статистика по коду

Сканирования по дням, устройства и страны — тем же запросом, что и всё остальное. Удобно складывать в свою отчётность.

🔑

Ключ на каждую интеграцию

Ключей можно завести несколько — по одному на сайт, CRM и внутренний скрипт. Ненужный отзывается, остальные продолжают работать.

Как начать

Заведите ключ

В личном кабинете, в разделе «Ключи API». Ключ показывается один раз — скопируйте его сразу.

Создайте код

Один запрос POST. В ответе — короткая ссылка и адреса картинок.

Заберите картинку

SVG для печати или PNG нужной ширины — и в макет.

Меняйте, когда нужно

Назначение переставляется запросом PATCH, тираж перепечатывать не нужно.

Получить ключ бесплатно

Справочник

Полное описание методов, типов кодов и их полей. То же самое видно в кабинете на странице ключей.

Как пользоваться

Ключ передаётся заголовком X-Api-Key (или Authorization: Bearer). Тело запроса и ответы — JSON. Ограничения: 60 запросов в минуту на ключ и 200 новых кодов в сутки на аккаунт.

Создать код

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"}'

В ответе — короткая ссылка short_url, которую кодирует QR, и адреса картинок. Картинка кода не меняется никогда: чтобы переставить назначение, меняют сам код, а не печатают новый.

Забрать картинку

curl -H "X-Api-Key: qrs_ваш_ключ" https://qrsir.ru/api/v1/codes/123.svg -o code.svg
curl -H "X-Api-Key: qrs_ваш_ключ" "https://qrsir.ru/api/v1/codes/123.png?size=1024" -o code.png

Сменить назначение

curl -X PATCH https://qrsir.ru/api/v1/codes/123 \
  -H "X-Api-Key: qrs_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.ru/sale"}'

Тип кода при правке не меняется — меняется назначение. У мини-сайта правка частичная: что не прислали, останется как было, а список links заменяется целиком, но только если вы его передали. У маршрутизатора список rules заменяется целиком.

Все методы

GET	/api/v1/codes	список кодов (limit, offset)
POST	/api/v1/codes	создать код
GET	/api/v1/codes/{id}	карточка кода
PATCH	/api/v1/codes/{id}	название, назначение, оформление, включить/выключить
DELETE	/api/v1/codes/{id}	удалить код
GET	/api/v1/codes/{id}.svg	картинка вектором (mp — размер модуля)
GET	/api/v1/codes/{id}.png	картинка растром (size — ширина в пикселях)
GET	/api/v1/codes/{id}/stats	статистика сканирований (days)
POST	/api/v1/uploads	загрузить файл или картинку (multipart/form-data)

Типы кодов и их поля

В теле запроса всегда есть type и title — они обязательны у всех типов. Дальше зависит от типа: у url это target_url, у text — text, у остальных — объект payload. Раскройте нужный тип: внутри список полей и готовое тело запроса, его можно скопировать и подставить в пример выше. Через API доступны все типы кодов, что есть в кабинете.

url — Ссылка на сайт

Переадресация на страницу. Адрес меняется через PATCH сколько угодно раз — картинка остаётся прежней.

target_url

обязательно

адрес со схемой http:// или https://

{
    "type": "url",
    "title": "Каталог",
    "target_url": "https://example.ru/catalog"
}

text — Текст

Показывает страницу с текстом. Годится для инструкций, состава, условий акции.

text

обязательно

до 2000 символов

{
    "type": "text",
    "title": "Состав",
    "text": "Мука, вода, соль.\nХранить при +4 °C."
}

minisite — Мини-сайт

Страница-визитка со своими цветами, логотипом, картинкой и списком ссылок — когда одной ссылки мало, а сайт заводить не хочется. Картинки сначала загружают через POST /api/v1/uploads с kind=image.

heading	обязательно	заголовок страницы
subheading	по желанию	подзаголовок
body	по желанию	текст под заголовком, до 5000 символов
bg	по желанию	цвет фона, #rrggbb
text	по желанию	цвет текста
accent	по желанию	цвет кнопок
logo	по желанию	ссылка на логотип
image	по желанию	ссылка на картинку-обложку
links	по желанию	список кнопок, до 20 штук

Поля одной кнопки:

label	обязательно	подпись на кнопке
url	обязательно	куда ведёт

{
    "type": "minisite",
    "title": "Кафе «Ромашка»",
    "payload": {
        "heading": "Кафе «Ромашка»",
        "subheading": "Завтраки с 8:00, кофе навынос",
        "body": "Тверская, 15. Работаем без выходных.",
        "bg": "#fffaf3",
        "text": "#1f2937",
        "accent": "#e07a5f",
        "logo": "https://qrsir.ru/uploads/8f3c1d0b2a94.webp",
        "image": "https://qrsir.ru/uploads/2b7e91c4d035.webp",
        "links": [
            {
                "label": "Меню",
                "url": "https://example.ru/menu"
            },
            {
                "label": "Забронировать стол",
                "url": "https://example.ru/booking"
            }
        ]
    }
}

vcard — Визитка

Контакт сохраняется в телефонную книгу одним касанием. Нужно хотя бы одно из полей first, last, org.

first	по желанию	имя
last	по желанию	фамилия
org	по желанию	компания
job	по желанию	должность
phone	по желанию	телефон в любом виде, нормализуется сам
email	по желанию	проверяется на корректность
website	по желанию	адрес сайта
address	по желанию	адрес, одной строкой
note	по желанию	заметка, до 500 символов

{
    "type": "vcard",
    "title": "Визитка менеджера",
    "payload": {
        "first": "Иван",
        "last": "Петров",
        "org": "ООО «Ромашка»",
        "job": "Менеджер",
        "phone": "+7 900 123-45-67",
        "email": "ivan@example.ru",
        "website": "https://example.ru"
    }
}

wifi — Wi-Fi

Телефон подключается к сети без ввода пароля. Удобно для гостевых сетей в кафе и гостиницах.

ssid	обязательно	имя сети, с учётом регистра
password	обязательно	кроме случая auth: "nopass"
auth	по желанию	WPA (по умолчанию), WEP или nopass
hidden	по желанию	true, если сеть скрытая

{
    "type": "wifi",
    "title": "Гостевой Wi-Fi",
    "payload": {
        "ssid": "Cafe-Guest",
        "password": "latte2026",
        "auth": "WPA",
        "hidden": false
    }
}

phone — Звонок

Открывает набор номера.

phone

обязательно

номер в любом виде

{
    "type": "phone",
    "title": "Отдел продаж",
    "payload": {
        "phone": "+7 800 201-62-88"
    }
}

whatsapp — WhatsApp

Открывает переписку, при желании — с заранее вписанным сообщением.

phone	обязательно	международный формат, только цифры
text	по желанию	заготовка сообщения, до 1000 символов

{
    "type": "whatsapp",
    "title": "Написать в WhatsApp",
    "payload": {
        "phone": "79001234567",
        "text": "Здравствуйте! Хочу уточнить наличие."
    }
}

telegram — Telegram

Ведёт на пользователя, канал или бота.

username

обязательно

имя без ссылки, символ @ можно не писать

{
    "type": "telegram",
    "title": "Наш канал",
    "payload": {
        "username": "qrsir"
    }
}

email — Письмо

Открывает почтовую программу с заполненными полями.

to	обязательно	адрес получателя
subject	по желанию	тема
body	по желанию	текст письма, до 2000 символов

{
    "type": "email",
    "title": "Заявка",
    "payload": {
        "to": "sales@example.ru",
        "subject": "Заявка с упаковки",
        "body": "Здравствуйте!"
    }
}

sms — SMS

Открывает окно нового сообщения.

phone	обязательно	номер получателя
body	по желанию	заготовка сообщения, до 1000 символов

{
    "type": "sms",
    "title": "Заказать звонок",
    "payload": {
        "phone": "+7 900 123-45-67",
        "body": "Перезвоните мне"
    }
}

file — Файл или PDF

Ведёт на файл: прайс, меню, инструкцию, сертификат. Сначала загрузите файл через POST /api/v1/uploads и подставьте полученный url — тогда файл лежит у нас и его можно заменить, не перепечатывая код.

url	обязательно	ссылка на файл, обычно из ответа /uploads
name	по желанию	как файл называется для человека; по умолчанию берётся из ссылки

{
    "type": "file",
    "title": "Прайс-лист",
    "payload": {
        "url": "https://qrsir.ru/uploads/8f3c1d0b2a94.pdf",
        "name": "Прайс-лист 2026.pdf"
    }
}

geo — Геометка

Открывает точку на карте. Пригодится на вывеске, в буклете, на упаковке доставки.

lat	обязательно	широта, число от -90 до 90
lng	обязательно	долгота, число от -180 до 180
label	по желанию	подпись точки

{
    "type": "geo",
    "title": "Как нас найти",
    "payload": {
        "lat": "55.751244",
        "lng": "37.618423",
        "label": "Красная площадь"
    }
}

event — Событие

Добавляет встречу в календарь. Верхний title — имя кода в кабинете, title внутри payload — название самого события.

title	обязательно	название события (внутри payload)
start	обязательно	начало в формате 2026-09-01T18:00
end	по желанию	окончание, в том же формате
location	по желанию	место
desc	по желанию	описание, до 2000 символов
allday	по желанию	true, если событие на весь день

{
    "type": "event",
    "title": "Вебинар",
    "payload": {
        "title": "Вебинар по QR-кодам",
        "start": "2026-09-01T18:00",
        "end": "2026-09-01T19:30",
        "location": "Онлайн",
        "desc": "Ссылку пришлём за час до начала."
    }
}

router — Маршрутизатор

Один код, который отправляет в разные места по условиям: устройство, город, время, даты. Правила проверяются сверху вниз, срабатывает первое подходящее; если ни одно не подошло — код из default. Нужно хотя бы одно правило или default.

rules	по желанию	список правил, до 20 штук
default	по желанию	куда вести, если ни одно правило не подошло

Поля одного правила:

target	обязательно	id кода назначения или его короткий код
device	по желанию	ios, android или desktop
city	по желанию	город по IP, совпадение по части названия
time_from	по желанию	с какого часа, ЧЧ:ММ
time_to	по желанию	по какой час
date_from	по желанию	с какой даты, ГГГГ-ММ-ДД
date_to	по желанию	по какую дату

{
    "type": "router",
    "title": "Умный код на упаковке",
    "payload": {
        "rules": [
            {
                "device": "ios",
                "target": 101
            },
            {
                "device": "android",
                "target": 102
            },
            {
                "city": "Москва",
                "time_from": "09:00",
                "time_to": "18:00",
                "target": 103
            }
        ],
        "default": 104
    }
}

Загрузка файлов

Единственный метод, который принимает не JSON. Нужен для кода типа file и для картинок мини-сайта: загружаете файл, в ответ получаете url и подставляете его в код. Файл лежит у нас, поэтому его можно заменить, не перепечатывая QR.

curl -X POST https://qrsir.ru/api/v1/uploads \
  -H "X-Api-Key: qrs_ваш_ключ" \
  -F "file=@price.pdf"

curl -X POST https://qrsir.ru/api/v1/uploads \
  -H "X-Api-Key: qrs_ваш_ключ" \
  -F "file=@logo.png" -F "kind=image"

Без kind файл сохраняется как есть — до 10 МБ: PDF, картинки, документы Office, txt, csv, zip. С kind=image принимаются только изображения до 3 МБ, растр пережимается в WebP — так логотип и обложка мини-сайта не тормозят страницу.

Оформление

Необязательный объект style — и при создании, и при правке. Что не передали, останется прежним.

fg	цвет точек, например #0f172a
bg	цвет фона
accent	цвет угловых меток
dots	форма точек: square, rounded, dots, soft
frame	рамка: none, box, label
caption	подпись под кодом, видна при frame: "label"
logo	адрес логотипа в центре; загружается в кабинете

У картинок есть свои параметры: .svg?mp=10 — размер одного модуля (2–60), .png?size=512 — ширина в пикселях (120–2000).

Ошибки

Приходят в виде {"error":{"code":"…","message":"…"}}; при проверке данных добавляется список details — там написано, какое поле не устроило.

401	no_key, bad_key	ключ не передан, неизвестен или отозван
404	not_found	кода нет или он принадлежит другому аккаунту
422	validation_failed, bad_type	данные не прошли проверку или тип недоступен в API
429	rate_limited, daily_limit	превышена частота запросов или суточный предел кодов

Частые вопросы

Чем это отличается от бесплатной библиотеки генерации QR?

Библиотека рисует картинку — этого достаточно, если код живёт недолго: на чеке, на экране, в письме. Наш API нужен, когда важна не картинка, а адрес за ней: код печатают один раз, а вести он должен туда, куда нужно сегодня. Плюс к каждому коду копится статистика сканирований, чего у картинки быть не может.

Можно ли поменять ссылку после того, как код напечатан?

Для этого всё и сделано. Запрос PATCH меняет назначение кода, а короткая ссылка и сама картинка остаются прежними. Напечатанные коды продолжают работать, перепечатывать ничего не нужно.

На каком языке писать интеграцию?

На любом. Это обычные HTTP-запросы с JSON: подойдут PHP, Python, JavaScript, C#, Java, 1С и даже curl из планировщика задач. Отдельной библиотеки ставить не нужно.

Сколько кодов можно создать?

До 200 новых кодов в сутки на аккаунт и до 60 запросов в минуту на ключ. Этого хватает, чтобы заводить код на заказ, на клиента или на партию товара. Если нужны другие объёмы — напишите, обсудим.

Можно ли поставить картинку кода прямо на свой сайт?

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

Сколько это стоит?

Ключ входит в бесплатный аккаунт QRsir вместе с кодами, мини-сайтами и виджетами. Регистрация через Яндекс ID, без анкет и привязки карты.

Первый код — за пять минут

Ключ выдаётся сразу после входа, платить и договариваться не нужно.

Получить ключ

API динамическихQR-кодов

Когда QR-коды пора генерировать программно

Типовые сценарии

Что стоит знать заранее

Что умеет API

Код одним запросом

Картинка в SVG и PNG

Назначение меняется

Все 14 типов кодов

Статистика по коду

Ключ на каждую интеграцию

Как начать

Заведите ключ

Создайте код

Заберите картинку

Меняйте, когда нужно

Справочник

Как пользоваться

Создать код

Забрать картинку

Сменить назначение

Все методы

Типы кодов и их поля

Загрузка файлов

Оформление

Ошибки

Частые вопросы

Первый код — за пять минут

API динамических
QR-кодов