API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.
Як це працює
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. Дочекайтеся його завершення або використайте новий ключ.