Практичний довідник Qivo
Як працює API генерації QR-кодів
API допомагає створювати QR-коди автоматично — з вашого сайту, внутрішнього інструмента або скрипта. Розберімо шлях від даних до готового зображення.
Ваш застосунок передає дані й налаштування; Qivo повертає зображення статичного QR-коду. Секретний ключ залишається на вашому сервері.
Від ручного редактора до інтеграції
У редакторі людина заповнює поля й натискає завантаження. Через API ті самі дії виконує програма: наприклад, формує QR-код із посиланням на сторінку товару під час підготовки етикетки.
Виклик API не робить код динамічним. У зображенні записуються передані дані, а не проміжна адреса Qivo. Готовий файл можна зберегти й використовувати без повторних запитів до генератора.
З чого складається запит
GET-запит має адресу сервісу, параметри та секретний ключ. Параметр contentType визначає тип даних, format — PNG або SVG, а shape, border і center — оформлення. Для простого тексту потрібне поле data.
Значення параметрів потрібно кодувати для URL. Використовуйте стандартні засоби своєї мови: вони коректно передають пробіли, знак + у телефоні та # у кольорі. Невідповідні або відсутні обов’язкові поля спричинять відповідь із помилкою.
Чому ключ має бути на сервері
Ключ надає доступ до генерації. Якщо помістити його в JavaScript публічної сторінки, відвідувачі зможуть прочитати його. Виконуйте запити з власного сервера й беріть ключ зі змінної середовища.
Передавайте ключ у заголовку X-API-Key через HTTPS. Параметр key у посиланні також підтримується, але URL може залишитися в історії та журналах. Не включайте секретний ключ у зображення QR або публічні приклади.
Як обробити відповідь
Успішна відповідь містить саме зображення, а не JSON із посиланням на файл. Перевірте HTTP-статус перед збереженням. При помилці Qivo повертає JSON з поясненням; його не слід записувати як PNG.
Для друкованих матеріалів зручний SVG, а для звичних зображень — PNG. Не запускайте генерацію при кожному перегляді незмінної сторінки: збережіть готовий код і повторно використовуйте файл. Поважайте ліміт запитів і паузу Retry-After.
Що перевірити перед публікацією
API перевіряє вхідні параметри, але не декодує готове зображення. Це скорочує обробку, проте перевірка зчитування залишається на стороні вашого процесу. Випробуйте типові комбінації стилів і крайні обсяги даних.
Залишайте світле поле щонайменше в чотири клітинки, добрий контраст і достатній розмір. Після друку перевірте кінцевий макет телефоном. Технічні параметри та готові приклади PHP, JavaScript, Python і cURL наведені на сторінці API.
Джерела та додаткові матеріали
Підготовлено та підтримується Umind. Рекомендації слід перевіряти на вашому кінцевому макеті й пристроях.