Ку-Ку Код

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

Один POST-запрос принимает список строк и параметры листа, в ответ приходит готовый файл: PDF с сеткой кодов, векторные листы SVG или архив с кодами поштучно. Регистрации, ключей и оплаты нет. Генерация общая с формой на главной: при одинаковых параметрах файл получается тот же.

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

Адрес один: https://qqkod.ru/api/v1/sheets, метод POST. Тело в формате JSON. При успехе в ответ приходит сам файл, ошибки приходят в JSON с кодом и пояснением на русском. Первый пример собирает лист A4 с 3 кодами в 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 массив строк или строка обязательное Список кодов. Одна строка это один код, формат как в поле списка формы: у ссылок, телефонов, email и EAN-13 подпись после пробела, у текста, SMS, DataMatrix и Code128 после «|», у Wi-Fi подпись это третья часть строки, у визитки пятая, части разделяются знаком «;».
content_type строка url Тип содержимого: url, text, phone, sms, wifi, vcard, email, ean13, datamatrix, code128, payment.
url_template строка нет Шаблон адреса с {value}: строка списка подставляется на место метки. Работает только при content_type равном url.
datamatrix_gs1 логическое false Режим GS1 DataMatrix: FNC1 в начале, <GS> в строке становится разделителем. Читается только при content_type равном datamatrix. Принимает true и false, а также 1 и 0.
payment_name строка нет Получатель платежа, от 1 до 160 символов. Обязательное при content_type равном payment.
payment_account строка нет Расчетный счет получателя, ровно 20 цифр. Обязательное при content_type равном payment.
payment_bank строка нет Название банка получателя, от 1 до 45 символов. Обязательное при content_type равном payment.
payment_bic строка нет БИК банка, ровно 9 цифр. Обязательное при content_type равном payment.
payment_corr строка нет Корреспондентский счет банка, от 1 до 20 цифр; если его нет, ставьте 0. Обязательное при content_type равном payment.
payment_inn строка нет ИНН получателя, 10 или 12 цифр. Только при content_type равном payment.
payment_kpp строка нет КПП получателя, ровно 9 цифр. Только при content_type равном payment.
payment_purpose строка Оплата[ за {period}][, л/с {account}][, {name}] Шаблон назначения платежа, до 210 символов. Метки {sum}, {account}, {name}, {period} берутся из строки списка, часть в квадратных скобках пропадает, если метка внутри пуста. Только при content_type равном payment.
output строка svg Формат ответа: pdf, svg, svg_files, png.
qr_size_cm число 2 Сторона кода в сантиметрах, от 1 до 15. У ean13 это ширина штрих-кода: по умолчанию 3,7, от 2,9 до 7,5. У datamatrix сторона как у QR, у code128 ширина от 3 до 13, по умолчанию 5.
margin_edge число 1.7 Отступ по краям листа в сантиметрах, от 0 до 9.
margin_between число 0.6 Промежуток между соседними кодами в сантиметрах, от 0,1 до 5.
frame_margin число 0.3 Отступ от кода до рамки в сантиметрах, от 0,1 до 10.
border_width число 0.2 Толщина рамки в миллиметрах, от 0 до 2. Ноль убирает рамку совсем.
border_radius число 0.8 Скругление углов рамки в миллиметрах, от 0 до 5.
frame_mode строка code Где рамка: code (вокруг кода), code_label (вокруг кода и подписи, подпись внутри рамки цветом кода), none (без рамки, отступ рамки остается полем вокруг кода).
cut_marks логическое false Метки реза: короткие штрихи по углам каждой ячейки в промежутках между кодами и в полях листа. Принимает true и false, а также 1 и 0. Рисуются при промежутке между кодами от 0,5 см и поле листа от 0,25 см, иначе лист выходит без меток.
qr_color строка #000000 Цвет кода в HEX. Код должен быть заметно темнее фона, иначе запрос вернет ошибку контраста.
bg_color строка #ffffff Цвет фона в HEX.
bg_transparent логическое false Прозрачный фон вместо цвета. Принимает true и false, а также 1 и 0.
page_format строка a4 Формат листа: a4, a3, a5, a6, letter.
page_orientation строка portrait Ориентация листа: portrait, landscape.

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

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

  • 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 приходит та же подсказка, что показывает форма на сайте. Построчные ошибки списка приходят под ключом urls: имя поля запроса тут другое.

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 строк, список целиком до 256 КБ; ссылка до 2048 байт, у остальных типов свои потолки: текст до 500 символов, текст SMS до 160, имя сети Wi-Fi до 32 байт;
  • тело запроса не больше 2 МБ;
  • с одного IP проходит 10 запросов в минуту и 300 за календарные сутки по UTC, при превышении вернется 429 с заголовком Retry-After.

Лимиты одинаковые для всех. Если их не хватает, напишите на info@qqkod.ru, обсудим.

Условия

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