API генератора QR-кодов

Быстрый старт

Эндпоинт один: POST https://qqkod.ru/api/v1/sheets, тело запроса в формате JSON. Успешный ответ сразу отдает файл, ошибки приходят в JSON с кодом и пояснением на русском. Пример: лист A4 с тремя кодами в PDF.

curl -X POST https://qqkod.ru/api/v1/sheets \
  -H "Content-Type: application/json" \
  -d '{"lines": ["https://example.com/1 Стол 1", "https://example.com/2 Стол 2", "https://example.com/3 Стол 3"], "output": "pdf"}' \
  -o qqkod.pdf

Второй пример: коды поштучно в PNG по шаблону ссылки. В поле lines только артикулы, а адрес собирается шаблоном с {value}.

curl -X POST https://qqkod.ru/api/v1/sheets \
  -H "Content-Type: application/json" \
  -d '{"lines": ["A-101", "A-102", "A-103"], "url_template": "https://example.com/item/{value}", "output": "png"}' \
  -o qqkod-png.zip

Параметры

Обязательное поле одно: lines, массив строк или строка с переносами. Каждая строка устроена как строка списка в форме: значение кода, затем через пробел необязательная подпись, которая будет напечатана под кодом. Остальные поля опциональны и совпадают с настройками формы.

Поле	Тип	По умолчанию	Описание
lines	массив строк или строка	обязательное	Список кодов. Одна строка это один код: значение, дальше через пробел необязательная подпись.
content_type	строка	url	Тип содержимого: url, text, phone, sms, wifi, vcard, email, ean13.
url_template	строка	нет	Шаблон адреса с {value}: строка списка подставляется на место метки. Работает только при content_type равном url.
output	строка	svg	Формат ответа: pdf, svg, svg_files, png.
qr_size_cm	число	2	Сторона кода в сантиметрах, от 1 до 15. У ean13 это ширина штрих-кода: по умолчанию 3.7, от 2.9 до 7.5.
margin_edge	число	1.7	Поле от края листа в сантиметрах, от 0 до 9.
margin_between	число	0.6	Промежуток между соседними кодами в сантиметрах, от 0.1 до 5.
frame_margin	число	0.3	Отступ от кода до рамки в сантиметрах, от 0 до 10.
border_width	число	0.2	Толщина рамки в миллиметрах, от 0 до 2. Ноль убирает рамку совсем.
border_radius	число	0.8	Скругление углов рамки в миллиметрах, от 0 до 5.
qr_color	строка	#000000	Цвет кода в HEX. Код должен быть заметно темнее фона, иначе запрос вернет ошибку контраста.
bg_color	строка	#ffffff	Цвет фона в HEX.
bg_transparent	логическое	false	Прозрачный фон вместо цвета. Принимает true и false, а также 1 и 0.
page_format	строка	a4	Формат листа: a4, a3, letter.
page_orientation	строка	portrait	Ориентация листа: portrait, landscape.

Типы содержимого те же, что на сайте: url, text, phone, sms, wifi, vcard, email и ean13. Формат строк для каждого типа совпадает с формой, подробности и примеры есть в базе знаний.

Форматы ответа

• pdf: один документ со всеми листами, готов к печати.
• svg: листы с сеткой кодов. Один лист приходит файлом qqkod.svg, несколько собираются в архив qqkod.zip.
• svg_files: каждый код отдельным векторным файлом. Один код приходит файлом, несколько собираются в архив qqkod-svg.zip.
• png: каждый код отдельной картинкой. Один код приходит файлом, несколько собираются в архив qqkod-png.zip.

В успешном ответе есть служебные заголовки X-QQkod-Total-Sheets, X-QQkod-Grid, X-QQkod-Per-Sheet и X-QQkod-Items: по ним видно раскладку тиража без разбора файла.

Ошибки

Ошибки приходят в JSON: поле ok равно false, в error.code машиночитаемый код, в error.message пояснение, в error.fields построчные ошибки списка и полей. При типовых проблемах списка в error.hint лежит диагноз с советом, тот же, что показывает форма на сайте.

HTTP	Код	Когда
404	NOT_FOUND	Путь внутри /api/v1/ не равен /api/v1/sheets.
405	METHOD_NOT_ALLOWED	Метод запроса не POST.
415	UNSUPPORTED_MEDIA_TYPE	Заголовок Content-Type без application/json.
413	PAYLOAD_TOO_LARGE	Тело запроса больше 2 МБ.
400	BAD_JSON	Тело не разобралось как JSON или верхний уровень не объект.
422	VALIDATION_ERROR	Неизвестное поле, ошибка в параметре или в строках списка.
413	BATCH_LIMIT_EXCEEDED	Список длиннее лимита: 1500 строк или 256 КБ.
429	RATE_LIMITED	Превышен лимит запросов с одного IP, в ответе есть Retry-After.
500	INTERNAL_ERROR	Все прочее.

Лимиты

• до 1500 строк в одном запросе, строка до 2048 символов, список целиком до 256 КБ;
• тело запроса до 2 МБ;
• 10 запросов в минуту и 300 в сутки с одного IP, при превышении вернется 429 с заголовком Retry-After.

Лимиты общие для всех и подобраны так, чтобы их не замечать при штатной работе. Если вашей задаче тесно в этих рамках, напишите нам на info@qqkod.ru: обсудим.

Честные условия

API бесплатный, без регистрации, ключей и водяных знаков. Сгенерированные файлы не хранятся: временный файл удаляется сразу после отдачи ответа. Содержимое кодов в логи не пишется. Логотип в центре кода и живое превью пока доступны только в форме на сайте. Спецификация в формате OpenAPI: /api/openapi.json.