QR-коди - GetQR Docs

API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

QR-код у GetQR — це зображення плюс коротке посилання, через яке він спрацьовує. Під час створення QR-коду створюється і його коротке посилання, тож пізніше можна змінити адресу призначення без повторного друку коду.

Метод	Шлях	Опис
`GET`	`/api/v1/qrs`	Список QR-кодів
`POST`	`/api/v1/qrs`	Створення QR-коду
`GET`	`/api/v1/qrs/{qrId}`	Отримання QR-коду
`PATCH`	`/api/v1/qrs/{qrId}`	Оновлення QR-коду
`PUT`	`/api/v1/qrs/{qrId}`	Встановлення стану паузи
`POST`	`/api/v1/qrs/{qrId}/pause`	Призупинення QR-коду
`POST`	`/api/v1/qrs/{qrId}/activate`	Відновлення QR-коду
`POST`	`/api/v1/qrs/{qrId}/duplicate`	Дублювання QR-коду
`DELETE`	`/api/v1/qrs/{qrId}`	Видалення QR-коду
`GET`	`/api/v1/qrs/{qrId}/download`	Завантаження зображення QR-коду

Дані QR-коду за типами

Формат data для кожного з 16 типів.

Оформлення

Стилі точок, кольори, рамки й логотипи.

Правила доступу

Розклад, ліміт сканувань і пароль.

Статистику сканувань QR-коду див. у розділі Аналітика.

Об’єкт QR-коду

Кожен ендпоінт QR-кодів відповідає цим об’єктом, крім Видалення і Завантаження. Список повертає масив таких об’єктів.

string

Унікальний ID QR-коду, наприклад qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Тип QR-коду, наприклад website. Усі 16 значень див. у розділі Дані QR-коду за типами.

string | null

Назва QR-коду, що відображається в панелі керування.

string | null

Довільна нотатка про QR-код.

string

Збережені дані. Для wifi, vcard, social, multilink, event і sms це дані, які ви надіслали. Для всіх інших типів це коротке посилання, тож адресу призначення читайте з url.

boolean

true, якщо QR-код призупинено.

boolean

true для статичного QR-коду, створеного в панелі керування, який не має короткого посилання. API завжди створює динамічні QR-коди.

string | null

Повне коротке посилання, наприклад https://getqr.sh/x7Kd2p1.

string | null

Домен короткого посилання.

string | null

Slug короткого посилання.

boolean

true, якщо slug вибрали вручну, а не згенерували.

string | null

Адреса призначення, на яку перенаправляє коротке посилання.

string | null

Адреса призначення для відвідувачів з iOS — для QR-кодів app.

string | null

Адреса призначення для відвідувачів з Android — для QR-кодів app.

integer

Загальна кількість сканувань.

object

Правила доступу. Сам пароль ніколи не повертається. Див. Правила доступу.

Показати properties

boolean

Чи мають відвідувачі вводити пароль.

string | null

Запланований початок, ISO 8601.

string | null

Запланований кінець, ISO 8601.

integer | null

Максимальна кількість сканувань.

string

Лише для читання. custom — дизайн, який API може повністю редагувати. branded і ai — дизайн Branded або AI, створений у панелі керування. API не може редагувати його зображення, але зберігає його, коли ви змінюєте інші поля.

object

Збережений дизайн: styles, frameOptions і logoOptions, кожне з яких — об’єкт або null. Вони мають ту саму структуру, що й поля запиту, тож їх можна надіслати назад. Див. Оформлення.

object | null

Файл QR-коду pdf, image або video: id, name і size у байтах.

string | null

Лише для читання. Назва QR-коду app, створеного в панелі керування, що відображається.

object | null

Лише для читання. QR-код pdf із кількома файлами, створений у панелі керування: title, layout і files.

object | null

Лише для читання. QR-код image із кількома зображеннями, створений у панелі керування: title, layout і files.

string

Дата створення, ISO 8601.

string

Дата останнього оновлення, ISO 8601.

Секрети й внутрішні ID (password, userId, workspaceId, projectId) ніколи не повертаються.

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}

Список QR-кодів

GET /api/v1/qrs Повертає QR-коди вашого робочого простору посторінково.

integer

за замовчуванням:"1"

Сторінка, яку потрібно повернути, 1 або більше.

integer

за замовчуванням:"100"

Кількість QR-кодів на сторінці, від 1 до 100. Більше значення відхиляється.

string

Шукає за назвою QR-коду. Запити довші за 2 символи також шукають у збереженому data. Для типів-посилань збереженим data є коротке посилання, тож за URL призначення шукати не можна.

string

за замовчуванням:"createdAt"

Поле для сортування: createdAt, updatedAt, clicks (загальна кількість сканувань), lastClicked (останнє сканування) або type. type завжди сортує за спаданням і ігнорує sortOrder.

string

за замовчуванням:"desc"

Напрямок сортування: asc або desc.

boolean

за замовчуванням:"false"

Включати призупинені QR-коди.

boolean

за замовчуванням:"false"

Повертати лише призупинені QR-коди. Має пріоритет над showArchived.

Булеві параметри приймають рядки true або false. Запитуйте наступну сторінку, поки pagination.hasMore дорівнює true. Див. Пагінація.

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

Створення QR-коду

POST /api/v1/qrs Створює QR-код разом із його коротким посиланням. Відповідає 201 Created з новим QR-кодом.

string

Ваш власний токен для повторних спроб. Повторний запит із тим самим ключем протягом 24 годин повертає початкову відповідь, а не створює другий QR-код. Див. Повтори й дублікати.

string

обов'язково

Що кодує QR-код. Також визначає формат, у якому має бути data. Одне з: website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

обов'язково

Дані типу, які перевіряються відповідно до qrType. Порожній рядок пропускає перевірку. Формат кожного типу описано в розділі Дані QR-коду за типами.

object

Коротке посилання, через яке спрацьовує QR-код. Необов’язкове: якщо його не передати, link.url набуває значення data.

Показати properties

string

Адреса призначення, на яку перенаправляє коротке посилання. Якщо пропущено або порожньо, за замовчуванням — data. Якщо надіслано обидва і вони різні, перевагу має link.url. QR-коди vcard, social, multilink і event завжди ведуть на свою розміщену сторінку, а QR-коди pdf, image і video з fileId — на файл. Допустимі схеми: http:, https:, wifi:, mailto:, sms:, begin:.

string

Домен короткого посилання. Це має бути активний домен вашого робочого простору: інший домен отримує 403, а домен, який ще не активний, — 422. За замовчуванням — домен робочого простору за замовчуванням.

string

Slug короткого посилання, від 3 до 15 символів, зберігається в нижньому регістрі. Недопустимий slug отримує 422, а зайнятий — 409. Якщо його не передати, генерується випадковий slug із 7 символів.

string | null

URL призначення для відвідувачів з iOS — для QR-кодів app.

string | null

URL призначення для відвідувачів з Android — для QR-кодів app.

string | null

Заголовок попереднього перегляду посилання (og:title), зберігається в короткому посиланні. Відрізняється від власного title QR-коду. Поки ніде не відображається.

string | null

Опис попереднього перегляду посилання (og:description), зберігається в короткому посиланні. Поки ніде не відображається.

—

У цьому API недоступні: надсилання будь-якого з них повертає 422. Щоб зупинити QR-код у заданий час, використовуйте access.pauseAt.

string

Назва QR-коду, що відображається в панелі керування. Пробіли на краях обрізаються, від 1 до 40 символів. Якщо не передати, QR-код буде без назви.

string

Довільна нотатка про QR-код. До 280 символів.

string

Файл QR-коду pdf, image або video, завантажений з відповідним target. Для vcard, social і multilink — необов’язкове зображення профілю, завантажене з target logo. event теж його приймає, але сторінка події бере обкладинку з data.fileId. Інші типи отримують 422. Спершу завантажте файл через Файли. Див. Файли в QR-кодах.

string

Шаблон, дизайн якого застосовується до нового QR-коду. Надіслані поля дизайну накладаються поверх нього. Шаблон із дизайном Branded або AI отримує 422 (art_template_unsupported). Невідомий шаблон або шаблон з іншого робочого простору отримує 404.

object

Форми й кольори точок і кутів. Див. Оформлення.

object

Рамка навколо QR-коду та її текст із закликом до дії. Див. Оформлення.

object

Логотип у центрі: запропонований логотип або ваш власний файл, завантажений з target logo. Невідомий файл, незавершене завантаження або файл з іншим target відхиляються. Див. Оформлення.

object

Розклад, ліміт сканувань і захист паролем. Див. Правила доступу.

Показати properties

string | null

Запланований початок, ISO 8601.

string | null

Запланований кінець, ISO 8601.

integer | null

Максимальна кількість сканувань, додатне ціле число.

string | null

Пароль, який мають ввести відвідувачі. Його надсилання вмикає захист.

boolean

Вимикає або знову вмикає захист, зберігаючи збережений пароль.

boolean

Чи призупинено QR-код. true створює його призупиненим: під час сканування показується сторінка паузи, а не адреса призначення.

Невідомі поля відкидаються без помилки. Див. Не підтримується через API.

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}

Повтори й дублікати

З ключем. Із заголовком Idempotency-Key відповідь відтворюється протягом 24 годин.
Без ключа. Ідентичне тіло, надіслане протягом 30 секунд, вважається дублікатом.
Повторне відтворення. Повторно відтворена відповідь повертається як збережена, з x-idempotent-replay: true. Для нового QR-коду повертається false.
Запит виконується. Другий запит, поки перший ще виконується, отримує 409 conflict.
Збої. Невдале створення одразу звільняє ключ, тож можна повторити запит із тим самим ключем.
Без гарантій. Якщо захист від дублікатів недоступний, створення виконуються без нього.

Див. також Ідемпотентність.

Отримання QR-коду

GET /api/v1/qrs/{qrId} Повертає QR-код з його коротким посиланням, правилами доступу, дизайном і, для типів на основі файлів, його файлом.

string

обов'язково

ID QR-коду з відповіді списку або створення.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

Відповідь — повний об’єкт QR-коду.

Оновлення QR-коду

PATCH /api/v1/qrs/{qrId} Змінює вміст, адресу призначення, дизайн або правила доступу QR-коду. Надсилайте лише поля, які хочете змінити. Відповідає оновленим QR-кодом.

string

обов'язково

ID QR-коду.

Тіло приймає ті самі поля, що й Створення QR-коду, усі необов’язкові, з такими відмінностями:

templateId. Не приймається.
link. Частковий. Якщо пропустити link.url, поточна адреса призначення зберігається. link.domain і link.key отримують 422: коротке посилання — це те, що кодує надрукований код, тож щоб використати інше, створіть новий QR-код.
data. Перевіряється відповідно до підсумкового типу, лише якщо змінюється data або qrType. Зміну qrType без відповідного data буде відхилено. Див. Зміна типу.
Дизайн. styles, frameOptions і logoOptions об’єднуються зі збереженим дизайном, тож частковий об’єкт змінює лише те, що в ньому вказано. Вибір іншого логотипа замінює його, але зберігає розмір.
access. Кожен ключ застосовується, якщо він присутній. null очищає правило. Правила доступу передаються в access: надсилання їх у link повертає 422.
archived. Призупиняє або відновлює QR-код разом із його коротким посиланням, як Призупинення і Відновлення.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

Що можна змінити після друку для кожного типу, описано в розділі Дані QR-коду за типами.

Встановлення стану паузи

PUT /api/v1/qrs/{qrId} Безпосередньо задає стан паузи. Призупинення і Відновлення роблять те саме й зрозуміліші в коді.

string

обов'язково

ID QR-коду.

boolean

обов'язково

true, щоб призупинити QR-код, false, щоб відновити його.

curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Призупинення QR-коду

POST /api/v1/qrs/{qrId}/pause Зупиняє перенаправлення QR-коду на адресу призначення: під час сканування натомість показується сторінка паузи. Надрукований код і його коротке посилання лишаються дійсними. Без тіла запиту.

string

обов'язково

ID QR-коду.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Відновлення QR-коду

POST /api/v1/qrs/{qrId}/activate Призупинений QR-код знову перенаправляє на адресу призначення. Розклад і ліміт сканувань, якщо їх задано, і далі діють. Без тіла запиту.

string

обов'язково

ID QR-коду.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

Дублювання QR-коду

POST /api/v1/qrs/{qrId}/duplicate Створює копію з тим самим вмістом і дизайном. Без тіла запиту. Відповідає 201 Created з новим QR-кодом.

string

обов'язково

ID QR-коду, який потрібно скопіювати.

Коротке посилання. Копія отримує власне коротке посилання з випадковим slug на домені робочого простору за замовчуванням, а не на домені оригіналу. Її сканування рахуються окремо.
Назва. До назви додається суфікс (Copy). Результат не перевищує 40 символів: довга назва спершу скорочується. QR-код без назви лишається без назви.
Не копіюються. Правила доступу (пароль, розклад, ліміт сканувань) і стан паузи. Копія завжди активна.
Файли. Файли PDF і зображень, зокрема файли наборів і галерей, копіюються, тож копія володіє ними сама. Відеофайли й файли дизайну, як-от логотипи, спільні з оригіналом.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}

Видалення QR-коду

DELETE /api/v1/qrs/{qrId} Видаляє QR-код і його коротке посилання. Відповідає ID видаленого коду.

Видалення остаточне. Надрукований код і його коротке посилання перестають працювати, а історія сканувань стає недоступною. Якщо QR-код може знадобитися знову, краще призупиніть його.

string

обов'язково

ID QR-коду.

string

ID видаленого QR-коду.

boolean

Завжди true.

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }

Завантаження зображення QR-коду

GET /api/v1/qrs/{qrId}/download Рендерить QR-код з його дизайном і повертає файл.

string

обов'язково

ID QR-коду для рендерингу з відповіді списку або створення.

string

за замовчуванням:"jpg"

Формат файлу: jpg, png, svg, pdf (сторінка A4) або eps. Дизайн Branded або AI завантажується лише у форматі jpg, png або pdf.

integer

за замовчуванням:"1024"

Розмір зображення в пікселях: 1024, 2048 або 4096. svg і pdf його ігнорують. Дизайн Branded або AI завантажується лише в розмірі 1024.

`format`	`Content-Type`	Назва файлу
`jpg`	`image/jpeg`	`<title>-<resolution>px.jpg`
`png`	`image/png`	`<title>-<resolution>px.png`
`svg`	`image/svg+xml`	`<title>.svg`
`pdf`	`application/pdf`	`<title>.pdf`
`eps`	`application/postscript`	`<title>-<resolution>px.eps`

Тіло. Тіло відповіді — це файл. Запропонована назва файлу міститься в заголовку Content-Disposition; вона формується з назви QR-коду або має вигляд qr-code для QR-коду без назви.
Кешування. Відповіді містять ETag і Cache-Control: private, max-age=3600, must-revalidate. Надішліть ETag назад в If-None-Match, щоб отримати 304 Not Modified, якщо QR-код не змінився.
Помилки. Непідтримуваний формат або розмір отримує 400 bad_request. Повідомлення про помилку вказує причину: qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported або qr_download_art_resolution_unsupported.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>

Правила доступу

Надішліть об’єкт access під час створення або оновлення, щоб запланувати початок і кінець, обмежити кількість сканувань або вимагати пароль. Пропущені правила не змінюються, а null очищає правило. Повний опис поведінки з прикладами див. у розділі Правила доступу.

Об’єкти дизайну

styles, frameOptions і logoOptions задають форми точок і кутів, кольори, рамку й логотип. Вони працюють однаково для QR-кодів, шаблонів і масового створення. Невідомі форми, рамки чи логотипи відхиляються. Усі допустимі значення й готовий приклад див. у розділі Оформлення.

Поширені проблеми

422 під час задання пароля, розкладу або ліміту сканувань

Надсилайте правило в access, а не в link.

422 під час зміни link.domain або link.key

Коротке посилання не можна змінити після створення, бо його кодує надрукований код. Натомість створіть новий QR-код.

422 "Expected … for qrType"

data не відповідає формату qrType. Перевірте тип у розділі Дані QR-коду за типами.

409 conflict під час створення QR-коду

Ідентичне створення ще виконується, або link.key зайнятий. Повторіть запит, коли перший завершиться. З Idempotency-Key повторний запит поверне початковий QR-код.

Завантажується JPEG, а не PNG

Параметри називаються format і resolution, а format за замовчуванням — jpg. Надішліть format=png.

404 для QR-коду, який я бачу в панелі керування

Кожен запит виконується в робочому просторі вашого API-ключа. Перевірте, що QR-код належить саме йому. Див. Автентифікація.

Дані QR-коду за типами

Оформлення

Правила доступу

​Об’єкт QR-коду

​Список QR-кодів

​Створення QR-коду

​Повтори й дублікати

​Отримання QR-коду

​Оновлення QR-коду

​Встановлення стану паузи

​Призупинення QR-коду

​Відновлення QR-коду

​Дублювання QR-коду

​Видалення QR-коду

​Завантаження зображення QR-коду

​Правила доступу

​Об’єкти дизайну

​Поширені проблеми

​Що далі

Дані QR-коду за типами

Оформлення

Правила доступу

Аналітика

Об’єкт QR-коду

Список QR-кодів

Створення QR-коду

Повтори й дублікати

Отримання QR-коду

Оновлення QR-коду

Встановлення стану паузи

Призупинення QR-коду

Відновлення QR-коду

Дублювання QR-коду

Видалення QR-коду

Завантаження зображення QR-коду

Правила доступу

Об’єкти дизайну

Поширені проблеми

Що далі