> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Вступ до API

> Керуйте QR-кодами, шаблонами, аналітикою та звітами зі свого коду.

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

API GetQR — це REST API для того, що ви робите в панелі керування: створення й оновлення QR-кодів, завантаження їхніх зображень, читання аналітики сканувань і експорт звітів. Автентифікуйтеся API-ключем свого облікового запису та викликайте версіоновані ендпоінти під `/api/v1`.

## Що можна робити

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)
>
> Створюйте, переглядайте, оновлюйте, призупиняйте, дублюйте, видаляйте й завантажуйте QR-коди.

> [card] [Аналітика](https://docs.getqr.com/ua/api/endpoints/analytics.md)
>
> Загальна кількість сканувань і розбивки для одного QR-коду або всього робочого простору.

> [card] [Звіти](https://docs.getqr.com/ua/api/endpoints/reports.md)
>
> Експортуйте разовий звіт або заплануйте регулярні звіти електронною поштою.

> [card] [Шаблони](https://docs.getqr.com/ua/api/endpoints/templates.md)
>
> Зберігайте дизайни й застосовуйте їх до нових QR-кодів.

> [card] [Масове створення QR-кодів](https://docs.getqr.com/ua/api/endpoints/bulk-qr-creations.md)
>
> Створюйте до 100 QR-кодів за раз із JSON або CSV-файлу.

> [card] [Файли](https://docs.getqr.com/ua/api/endpoints/files.md)
>
> Завантажуйте PDF, зображення, відео й логотипи для своїх QR-кодів.

> [card] [Перевірка стану](https://docs.getqr.com/ua/api/endpoints/health.md)
>
> Перевірте, чи працює API. API-ключ не потрібен.

## Посібники

> [card] [Дані QR-коду за типами](https://docs.getqr.com/ua/api/guides/qr-types.md)
>
> Формат даних для кожного з 16 типів QR-кодів.

> [card] [Оформлення](https://docs.getqr.com/ua/api/guides/customization.md)
>
> Стилі точок, кути, кольори, рамки й логотипи.

> [card] [Правила доступу](https://docs.getqr.com/ua/api/guides/access-rules.md)
>
> Розклад, ліміт сканувань, паролі, призупинення й видалення.

## Базовий URL

Усі ендпоінти розташовані під одним базовим URL:

```text theme={null}
https://getqr.com/api/v1
```

## Версіонування

Версія API входить до шляху: кожен ендпоінт розташований під `/api/v1/`.

* Несумісні зміни виходять під новим префіксом версії, наприклад `/api/v2/`, а `/api/v1/` продовжує працювати.
* Сумісні доповнення, як-от нові необов'язкові поля чи нові ендпоінти, можуть з'являтися і в v1. Ігноруйте поля відповіді, яких ваш код не знає.

## Швидкий старт

**1. Отримайте API-ключ**

Згенеруйте або покажіть ключ у налаштуваннях облікового запису. Див. [Автентифікація](https://docs.getqr.com/ua/api/authentication.md).

**2. Перевірте, чи доступний API**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

Відповідь: `{ "status": "ok", "version": "v1" }`.

**3. Створіть перший QR-код**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API відповідає `201` з новим QR-кодом, зокрема з його `id` і `shortLink`.

**4. Завантажте зображення**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## Запити й відповіді

* **Формат.** Надсилайте тіло запиту в JSON із `Content-Type: application/json`. Виняток — завантаження CSV для [масового створення](https://docs.getqr.com/ua/api/endpoints/bulk-qr-creations.md), яке використовує `multipart/form-data`.
* **Відповіді.** Відповіді надходять у JSON. Завантаження, як-от зображення QR-кодів і ZIP-архіви масового створення, повертають сам файл.
* **Дати.** Дати — це рядки ISO 8601 в UTC, наприклад `2026-08-01T10:00:00.000Z`.
* **Параметри запиту.** Булеві параметри приймають рядки `true` або `false`.
* **Часткові оновлення.** Ендпоінти `PATCH` змінюють лише поля, які ви надіслали.
* **Секрети.** Відповіді ніколи не містять паролів чи внутрішніх ідентифікаторів. Для QR-коду із захистом паролем повертається лише `passwordProtected: true`.
* **Робочий простір.** Кожен запит виконується в робочому просторі, до якого належить ваш API-ключ. ID робочого простору передавати не потрібно. Див. [Доступ і ролі](https://docs.getqr.com/ua/api/authentication.md#доступ-і-ролі).
* **Помилки.** Невдалі запити повертають об'єкт `error` зі стабільним `code`. Див. [Помилки](https://docs.getqr.com/ua/api/errors.md).

## Пагінація

Ендпоінти списків (QR-коди, шаблони й заплановані звіти) приймають два параметри запиту:

| Параметр | Опис |
| - | - |
| `page` | Сторінка, яку потрібно повернути. За замовчуванням `1`. |
| `pageSize` | Кількість результатів на сторінці, до `100`. За замовчуванням `100`. |

Вони відповідають масивом `data` та об'єктом `pagination`:

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| Поле | Опис |
| - | - |
| `page` | Сторінка, яку ви отримали. |
| `pageSize` | Розмір сторінки, яку ви отримали. |
| `total` | Кількість результатів на всіх сторінках. |
| `hasMore` | `true`, поки є наступна сторінка. |

Запитуйте наступну сторінку, поки `hasMore` дорівнює `true`. `pageSize` понад `100` повертає [`422`](https://docs.getqr.com/ua/api/errors#помилки-валідації).

## Ідемпотентність

Через мережеву помилку ви можете не знати, чи пройшов запит. Щоб безпечно повторити [Створення QR-коду](https://docs.getqr.com/ua/api/endpoints/qr-codes.md#створення-qr-коду), надішліть заголовок `Idempotency-Key` з унікальним значенням на ваш вибір:

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* Повторний запит із тим самим ключем протягом 24 годин повертає початкову відповідь, а не створює другий QR-код.
* Заголовок відповіді `x-idempotent-replay` дорівнює `true` для повторно відтвореної відповіді й `false` для нової.
* Якщо перший запит із цим ключем ще виконується, API відповідає `409 conflict`. Повторіть запит, коли він завершиться.
* Повторне використання ключа з іншим тілом запиту повертає `422 unprocessable_entity`.
* Без цього заголовка ідентичне тіло запиту, надіслане протягом 30 секунд, вважається дублікатом.

Масове створення натомість приймає поле `idempotencyKey` у тілі запиту. Див. [Масове створення QR-кодів](https://docs.getqr.com/ua/api/endpoints/bulk-qr-creations.md).

## Обмеження частоти запитів

Кожен API-ключ може надсилати до 600 запитів за хвилину. Див. [Обмеження частоти запитів](https://docs.getqr.com/ua/api/rate-limits.md).

## Незабаром

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

## Що далі

> [card] [Автентифікація](https://docs.getqr.com/ua/api/authentication.md)

> [card] [QR-коди](https://docs.getqr.com/ua/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.