GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.
Как это работает
1
Запустите массовое создание
Отправьте строки через Создание из JSON или Создание из CSV-файла. API отвечает
202 с массовым созданием и его id.2
Отслеживайте прогресс
Вызывайте Получение массового создания каждые несколько секунд, пока
status не станет completed или failed.3
Скачайте архив
Когда
status равен completed, вызовите Скачивание архива, чтобы получить ZIP с изображениями QR-кодов.- Лимит. До 100 строк в одном массовом создании.
- По одному. В рабочем пространстве одновременно выполняется только одно массовое создание. Если запустить новое, пока идёт текущее, вернётся текущее.
- Идемпотентность. Каждому запросу нужен
idempotencyKey. Повтор запроса с тем же ключом и тем же телом возвращает уже запущенное массовое создание. Тот же ключ с другим телом возвращает422. - Строки. Каждой строке нужны
nameиurl. См. Строки. - Тариф. Массовое создание недоступно на тарифе Single QR: запрос возвращает
403 exceeded_limit.
Строки
- Название. Становится названием QR-кода. Пробелы по краям обрезаются, длина ограничивается 40 символами. Повторяющиеся названия (без учёта регистра) получают номер:
Menu,Menu 2,Menu 3. - URL. Становится адресом назначения. Это должен быть адрес
httpилиhttpsс реальным доменом, напримерexample.com/menu, без пробелов. К URL без схемы добавляетсяhttps://. - Пустые строки. Строки без названия и без URL пропускаются. Строка, в которой есть только одно из них, отклоняется.
website с короткой ссылкой. См. Типы QR-кодов.
Заголовки
string
обязательно
Bearer и ваш API-ключ. См. Аутентификация.string
application/json для Создания из JSON, multipart/form-data для Создания из CSV-файла.Объект массового создания
string
ID массового создания, например
cm2k7x9qb0003ax8eb4f6gh2t.string
queued, processing, packaging или completed. Неудавшееся или отменённое массовое создание проходит через rollingBack к failed.string
Имя исходного файла.
integer
Число строк.
integer
Сколько QR-кодов уже создано.
integer
Сколько изображений QR-кодов уже отрисовано.
integer
Общий прогресс, от 0 до 100. Создание занимает до 40, отрисовка — до 90, упаковка — 95, а
completed — 100.boolean
true, если выполняющееся массовое создание не продвигалось 2 минуты. Продолжайте опрос: Получение массового создания перезапускает зависшее массовое создание.object | null
Когда
status равен failed: code и message. У отменённого массового создания код cancelled_by_user. Неудавшееся массовое создание откатывается, поэтому ни один из его QR-кодов не сохраняется.string | null
Путь для Скачивания архива, когда
status равен completed.string
Дата запуска, ISO 8601.
string
Дата последнего обновления, ISO 8601.
string | null
Дата завершения, ISO 8601.
string | null
Дата сбоя, ISO 8601.
Текущее массовое создание
GET /api/v1/bulk-qr-creations
Возвращает массовое создание, которое ещё выполняется в вашем рабочем пространстве. Если ничего не выполняется, возвращает последнее завершённое (completed или failed), пока его не скроют: это происходит при скачивании архива или закрытии в панели управления. Иначе возвращает null. Используйте этот запрос, чтобы продолжить отслеживание после перезапуска.
Создание из JSON
POST /api/v1/bulk-qr-creations
Запускает массовое создание из списка строк. Отвечает 202 Accepted. Массовое создание выполняется в фоне.
object[]
обязательно
QR-коды для создания, до 100. Каждая строка —
{ "name": "...", "url": "..." }, других полей она не принимает. См. Строки.object
обязательно
Дизайн для всех QR-кодов:
styles, frameOptions и logoOptions, все необязательны. Для дизайна по умолчанию передайте {}. Другие поля отклоняются. См. Оформление.string
обязательно
Имя, которое отображается в панели управления и используется для архива, от 1 до 255 символов.
string
обязательно
Ваш собственный ключ для этого массового создания, от 8 до 100 символов.
Создание из CSV-файла
POST /api/v1/bulk-qr-creations/csv
То же, что Создание из JSON, но строки передаются CSV-файлом в multipart/form-data. Отвечает 202 Accepted.
Файл должен быть в формате .csv и весить не больше 1 000 000 байт. Строка заголовков должна быть точно name,url, а за ней — до 100 строк данных. См. Формат CSV.
file
обязательно
CSV-файл.
string
обязательно
Объект дизайна, сериализованный в JSON, например
{"styles":{"dotsOptions":{"type":"rounded"}}}. Для дизайна по умолчанию передайте {}.string
обязательно
Ваш собственный ключ для этого массового создания, от 8 до 100 символов.
string
Имя, которое отображается в панели управления и используется для архива, до 255 символов. По умолчанию — имя загруженного файла.
Получение массового создания
GET /api/v1/bulk-qr-creations/{id}
Возвращает статус и прогресс массового создания. Опрашивайте его, пока status равен queued, processing или packaging. downloadUrl появляется, когда архив готов.
string
обязательно
ID массового создания. Возьмите его из ответа на запуск или на запрос текущего массового создания.
Отмена массового создания
DELETE /api/v1/bulk-qr-creations/{id}
Останавливает выполняющееся массовое создание и удаляет уже созданные им QR-коды. Откат выполняется во время запроса, поэтому в ответе обычно status равен failed, а error.code — cancelled_by_user. Отмена массового создания, которое уже завершилось сбоем, возвращает его без изменений.
string
обязательно
ID массового создания.
Скачивание архива
GET /api/v1/bulk-qr-creations/{id}/download
Возвращает ZIP-архив с одним JPEG размером 1024 px на каждый QR-код, названным по его строке: 001-Menu.jpg, 002-Wine list.jpg и так далее. Архив называется по sourceFilename. Доступен, когда status равен completed. Скачивание скрывает массовое создание, поэтому Текущее массовое создание перестаёт его возвращать.
string
обязательно
ID массового создания.
Частые проблемы
422 с "contains an invalid HTTP(S) URL"
422 с "contains an invalid HTTP(S) URL"
Сообщение называет строку. Каждый URL должен быть адресом
http или https с реальным доменом, например example.com/menu. Исправьте строку и отправьте запрос снова.422 "CSV headers must be exactly: name,url."
422 "CSV headers must be exactly: name,url."
Первая строка CSV должна быть
name,url — именно в таком порядке, в нижнем регистре и без других столбцов.422 "This idempotencyKey was already used with a different request body."
422 "This idempotencyKey was already used with a different request body."
Ключ нельзя использовать повторно для другого набора строк. Передайте новый
idempotencyKey.409 "The bulk QR archive is not ready for download."
409 "The bulk QR archive is not ready for download."
Массовое создание ещё не завершено. Продолжайте опрос, пока
status не станет completed.400 "Cannot cancel a finished bulk QR creation."
400 "Cannot cancel a finished bulk QR creation."
Массовое создание уже завершено, поэтому откатить его нельзя.
403 exceeded_limit
403 exceeded_limit
Ваше рабочее пространство на тарифе Single QR, который не включает массовое создание. Перейдите на другой тариф.
Вернулось старое массовое создание вместо нового
Вернулось старое массовое создание вместо нового
В вашем рабочем пространстве ещё выполняется другое массовое создание, или вы повторно использовали
idempotencyKey. Дождитесь его завершения или используйте новый ключ.