Управляйте кодами из своей системы.
Создавайте сотни QR-кодов одним запросом, обновляйте их назначения, загружайте отчёты о сканированиях в свою панель. Нужны только REST, JSON и API-ключ.
Черновик — эндпоинты будут определены в ходе разработки. На этой странице показана предлагаемая структура; работающего API пока нет. Адреса, названия полей, лимиты и форматы ответов могут измениться.
- Базовый URL
https://api.oqur.io/v1- Формат
- JSON, UTF-8, HTTPS
- Аутентификация
- API-ключ Bearer
- Тарифы
- Бизнес и Корпоративный
Начало работы
API oqur позволяет делать из вашего ПО то же, что вы делаете в панели: массово создавать QR, обновлять назначения, скачивать файлы для печати и получать отчёты о сканированиях. Каждый запрос идёт по HTTPS с телом в JSON.
Создайте ключ
Создайте ключ в разделе «API-ключи» меню «Настройки» в панели и выберите его области доступа. Когда API будет готов, он откроется на тарифах Бизнес и Корпоративный.
Отправьте первый запрос
Пример рядом выводит первый код вашего аккаунта. Если ответ 200, всё готово.
Следите за лимитами
Оставшееся число запросов есть в заголовках каждого ответа. Подробности — в разделе Лимиты запросов.
Правила
| Тема | Формат | Описание |
|---|---|---|
| Дата и время | ISO 8601 |
Всегда возвращаются в UTC: 2026-09-30T09:12:44Z. В отчётах можно выбрать нужный часовой пояс. |
| Идентификаторы | string |
Текст с префиксом: QR-коды начинаются с qr_, папки — с fld_, запросы — с req_. |
| Пагинация | integer |
Через page и per_page. Не больше 100 записей на странице. |
| Версия | v1 |
Версия указана в адресе. Несовместимые изменения выходят только с новой версией. |
curl "https://api.oqur.io/v1/qr-codes?per_page=1" \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Accept: application/json"
<?php
// composer require guzzlehttp/guzzle
use GuzzleHttp\Client;
$oqur = new Client([
'base_uri' => 'https://api.oqur.io/v1/',
'headers' => [
'Authorization' => 'Bearer ' . getenv('OQUR_API_KEY'),
'Accept' => 'application/json',
],
]);
$res = $oqur->get('qr-codes', ['query' => ['per_page' => 1]]);
$body = json_decode($res->getBody(), true);
// Node 18+ или другие среды вне браузера
const oqur = (path, init = {}) =>
fetch(`https://api.oqur.io/v1${path}`, {
...init,
headers: {
Authorization: `Bearer ${process.env.OQUR_API_KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
...init.headers,
},
}).then((r) => r.json());
const body = await oqur('/qr-codes?per_page=1');
Ответ 200 ПРИМЕР
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "menu",
"name": "Kafe Rıhtım · Карточка на стол",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"created_at": "2026-09-12T08:30:00Z"
}
],
"meta": { "page": 1, "per_page": 1, "total": 42 }
}
Аутентификация
Добавляйте API-ключ к каждому запросу в заголовке Authorization. Запросы без ключа или с недействительным ключом возвращают 401; ключи без нужных прав возвращают 403.
- Используйте ключ только на стороне сервера; не встраивайте его в браузер или мобильное приложение.
- Создавайте отдельный ключ для каждой интеграции. Если один утечёт, вы отзовёте только его.
- Давайте ключу только нужные области:
qr:read,qr:write,analytics:read,folders:write.
Заголовки
| Заголовок | Тип | Описание |
|---|---|---|
Authorizationобязательно |
string |
Bearer, а затем ваш API-ключ. |
Content-Type |
string |
application/json в запросах с телом. |
Accept |
string |
application/json. |
Idempotency-Key |
string |
Уникальное значение для безопасного повтора запросов на создание. Запрос с тем же ключом в течение 24 часов возвращает первый ответ. |
Заголовки запросаПРИМЕР
Authorization: Bearer oqur_live_8f3kQ2…
Content-Type: application/json
Accept: application/json
Ответ 401 ПРИМЕР
{
"error": {
"code": "unauthenticated",
"message": "API-ключ отсутствует или недействителен.",
"request_id": "req_5nT2pW"
}
}
Лимиты запросов
Каждый API-ключ может отправлять 60 запросов в минуту; на тарифе Корпоративный лимит настраивается под ваши задачи. Массовые эндпоинты обрабатывают 100 элементов за запрос, поэтому можно создавать или менять до 6000 кодов в минуту.
Заголовки ответа
| Заголовок | Тип | Описание |
|---|---|---|
X-RateLimit-Limit |
integer |
Общее число ваших запросов в минуту. |
X-RateLimit-Remaining |
integer |
Сколько запросов осталось в эту минуту. |
X-RateLimit-Reset |
integer |
Когда лимит обнулится, в виде Unix-времени. |
Retry-After |
integer |
Только в ответе 429: сколько секунд подождать. |
Получив 429, подождите Retry-After и повторите. При повторяющихся ошибках надёжнее всего удваивать ожидание на каждой попытке.
Ответ 429 ПРИМЕР
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790759580
Retry-After: 18
{
"error": {
"code": "rate_limited",
"message": "Лимит запросов на эту минуту исчерпан. Повторите через 18 секунд.",
"request_id": "req_9kP1sV"
}
}
QR-коды
Создание и изменение кодов, получение файлов для печати. Смена назначения динамического кода не меняет его короткую ссылку: напечатанный код остаётся прежним.
Массовое создание
POST
/qr-codes/bulk
Создаёт до 100 QR-кодов одним запросом. Каждый элемент проверяется отдельно; если хотя бы один недействителен, ничего не создаётся, а ошибки возвращаются в порядке элементов.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:write
Заголовки
| Заголовок | Тип | Описание |
|---|---|---|
Idempotency-Key |
string |
Уникальное значение для безопасной повторной отправки запроса. |
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
itemsобязательно |
array |
Коды для создания. От 1 до 100 элементов. |
items[].typeобязательно |
string |
Тип QR: один из 24 типов, например url, pdf, menu, vcard-plus, wifi. |
items[].targetобязательно |
object |
Назначение, зависящее от типа. Поле url для типа url, поле file_url для типа pdf. |
items[].name |
string |
Название, видимое в панели. Не больше 120 символов. |
items[].folder_id |
string |
Папка, в которую добавить код. |
items[].design |
object |
Цвет, узор, углы, логотип и рамка. Если не указано, используется шаблон аккаунта по умолчанию. |
Типы линии Q5 (wifi, text, vcard, email, sms, whatsapp) создаются статическими и не расходуют квоту динамических кодов.
Коды статусов
- 201 Коды созданы.
- 401 API-ключ отсутствует или недействителен.
- 403 Ваш тариф не позволяет использовать API или столько динамических кодов.
- 422 Один или несколько элементов недействительны; подробности — в массиве details.
- 429 Вы достигли лимита запросов; подождите Retry-After.
curl -X POST https://api.oqur.io/v1/qr-codes/bulk \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: campaign-september-01" \
-d '{
"items": [
{
"type": "url",
"name": "Плакат · Кадыкёй",
"target": { "url": "https://cafename.com/campaign" },
"folder_id": "fld_91xQ"
},
{
"type": "pdf",
"name": "Katalog 2026",
"target": { "file_url": "https://kafeadi.com/katalog.pdf" }
}
]
}'
<?php
// $oqur: клиент из раздела «Начало работы»
$res = $oqur->post('qr-codes/bulk', [
'headers' => ['Idempotency-Key' => 'campaign-september-01'],
'json' => [
'items' => [
[
'type' => 'url',
'name' => 'Плакат · Кадыкёй',
'target' => ['url' => 'https://cafename.com/campaign'],
'folder_id' => 'fld_91xQ',
],
[
'type' => 'pdf',
'name' => 'Katalog 2026',
'target' => ['file_url' => 'https://kafeadi.com/katalog.pdf'],
],
],
],
]);
// oqur(): помощник из раздела «Начало работы»
const { data } = await oqur('/qr-codes/bulk', {
method: 'POST',
headers: { 'Idempotency-Key': 'campaign-september-01' },
body: JSON.stringify({
items: [
{
type: 'url',
name: 'Плакат · Кадыкёй',
target: { url: 'https://cafename.com/campaign' },
folder_id: 'fld_91xQ',
},
{
type: 'pdf',
name: 'Katalog 2026',
target: { file_url: 'https://kafeadi.com/katalog.pdf' },
},
],
}),
});
Ответ 201 ПРИМЕР
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "Плакат · Кадыкёй",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"folder_id": "fld_91xQ",
"created_at": "2026-09-30T09:12:44Z"
},
{
"id": "qr_8Lr3nY",
"type": "pdf",
"name": "Katalog 2026",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/8Lr3nQ",
"folder_id": null,
"created_at": "2026-09-30T09:12:44Z"
}
],
"meta": { "created": 2 }
}
Массовое обновление
PATCH
/qr-codes/bulk
Обновляет до 100 кодов одним запросом. Меняются только переданные поля; короткая ссылка и напечатанный код остаются прежними.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:write
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
itemsобязательно |
array |
Коды для обновления. От 1 до 100 элементов. |
items[].idобязательно |
string |
Идентификатор кода. |
items[].target |
object |
Новое назначение. Следующие сканирования сразу идут туда. |
items[].status |
string |
active или paused. Сканирующие приостановленный код видят простую страницу «временно закрыто». |
items[].name |
string |
Новое название. |
items[].folder_id |
string |
Папка, в которую переместить; null — убрать из папки. |
items[].design |
object |
Поля дизайна. Переданные вложенные поля объединяются. |
Коды статусов
- 200 Коды обновлены.
- 401 API-ключ отсутствует или недействителен.
- 404 Код из списка не найден или не ваш.
- 422 Элемент недействителен; ни один код не обновлён.
- 429 Вы достигли лимита запросов.
curl -X PATCH https://api.oqur.io/v1/qr-codes/bulk \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"items": [
{ "id": "qr_7Kq2mX", "target": { "url": "https://kafeadi.com/ekim" } },
{ "id": "qr_8Lr3nY", "status": "paused" }
]
}'
<?php
$res = $oqur->patch('qr-codes/bulk', [
'json' => [
'items' => [
['id' => 'qr_7Kq2mX', 'target' => ['url' => 'https://kafeadi.com/ekim']],
['id' => 'qr_8Lr3nY', 'status' => 'paused'],
],
],
]);
const { data } = await oqur('/qr-codes/bulk', {
method: 'PATCH',
body: JSON.stringify({
items: [
{ id: 'qr_7Kq2mX', target: { url: 'https://kafeadi.com/ekim' } },
{ id: 'qr_8Lr3nY', status: 'paused' },
],
}),
});
Ответ 200 ПРИМЕР
{
"data": [
{ "id": "qr_7Kq2mX", "status": "active", "updated_at": "2026-09-30T10:04:12Z" },
{ "id": "qr_8Lr3nY", "status": "paused", "updated_at": "2026-09-30T10:04:12Z" }
],
"meta": { "updated": 2 }
}
Список
GET
/qr-codes
Возвращает коды вашего аккаунта постранично. По умолчанию сначала новые.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:read
Параметры запроса
| Поле | Тип | Описание |
|---|---|---|
page |
integer |
Номер страницы. По умолчанию 1. |
per_page |
integer |
Записей на странице. По умолчанию 25, не больше 100. |
folder_id |
string |
Только коды из этой папки. |
type |
string |
Фильтр по типу, например menu. |
status |
string |
draft, scheduled, active или paused. |
search |
string |
Ищет по названию или короткой ссылке. |
sort |
string |
created_at, name или scans_total. Для обратного порядка поставьте минус впереди: -scans_total. |
Коды статусов
- 200 Список получен; если результатов нет, data — пустой массив.
- 401 API-ключ отсутствует или недействителен.
- 422 Недопустимое значение фильтра или сортировки.
curl -G https://api.oqur.io/v1/qr-codes \
-H "Authorization: Bearer $OQUR_API_KEY" \
-d folder_id=fld_91xQ \
-d status=active \
-d sort=-scans_total \
-d per_page=25
<?php
$res = $oqur->get('qr-codes', ['query' => [
'folder_id' => 'fld_91xQ',
'status' => 'active',
'sort' => '-scans_total',
'per_page' => 25,
]]);
const params = new URLSearchParams({
folder_id: 'fld_91xQ',
status: 'active',
sort: '-scans_total',
per_page: '25',
});
const { data, meta } = await oqur(`/qr-codes?${params}`);
Ответ 200 ПРИМЕР
{
"data": [
{
"id": "qr_7Kq2mX",
"type": "url",
"name": "Плакат · Кадыкёй",
"status": "active",
"short_url": "https://oqur.io/d/7Kq2xP",
"scans_total": 312,
"created_at": "2026-09-12T08:30:00Z"
}
],
"meta": { "page": 1, "per_page": 25, "total": 1 },
"links": { "next": null, "prev": null }
}
Получение
GET
/qr-codes/{id}
Возвращает все поля одного кода: назначение, дизайн, статус и общее число сканирований.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:read
Параметры пути
| Поле | Тип | Описание |
|---|---|---|
idобязательно |
string |
Идентификатор кода, например qr_7Kq2mX. |
Коды статусов
- 200 Код найден.
- 401 API-ключ отсутствует или недействителен.
- 404 Код не существует или не ваш.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->get('qr-codes/qr_7Kq2mX');
$code = json_decode($res->getBody(), true)['data'];
const { data: code } = await oqur('/qr-codes/qr_7Kq2mX');
Ответ 200 ПРИМЕР
{
"data": {
"id": "qr_7Kq2mX",
"type": "url",
"name": "Плакат · Кадыкёй",
"status": "active",
"dynamic": true,
"short_url": "https://oqur.io/d/7Kq2xP",
"target": { "url": "https://cafename.com/campaign" },
"folder_id": "fld_91xQ",
"design": {
"foreground": "#0B1F3A",
"background": "#FFFFFF",
"dots": "rounded",
"corners": "square",
"logo_url": null,
"frame": { "style": "bottom", "text": "Beni tara" },
"error_correction": "M"
},
"scans_total": 312,
"created_at": "2026-09-12T08:30:00Z",
"updated_at": "2026-09-28T17:02:10Z"
}
}
Обновление
PATCH
/qr-codes/{id}
Обновляет один код. Смена назначения не меняет код: напечатанный QR остаётся прежним, следующие сканирования идут на новое назначение.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:write
Параметры пути
| Поле | Тип | Описание |
|---|---|---|
idобязательно |
string |
Идентификатор кода. |
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
target |
object |
Новое назначение. У статических кодов изменить нельзя. |
status |
string |
active или paused. |
name |
string |
Новое название. |
folder_id |
string |
Папка, в которую переместить; null — убрать из папки. |
design |
object |
Поля дизайна. Переданные вложенные поля объединяются. |
Коды статусов
- 200 Код обновлён.
- 401 API-ключ отсутствует или недействителен.
- 404 Код не существует или не ваш.
- 422 Недопустимое поле; например, назначение статического кода изменить нельзя.
curl -X PATCH https://api.oqur.io/v1/qr-codes/qr_7Kq2mX \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "target": { "url": "https://kafeadi.com/kis-menusu" } }'
<?php
$res = $oqur->patch('qr-codes/qr_7Kq2mX', [
'json' => ['target' => ['url' => 'https://kafeadi.com/kis-menusu']],
]);
const { data } = await oqur('/qr-codes/qr_7Kq2mX', {
method: 'PATCH',
body: JSON.stringify({ target: { url: 'https://kafeadi.com/kis-menusu' } }),
});
Ответ 200 ПРИМЕР
{
"data": {
"id": "qr_7Kq2mX",
"status": "active",
"short_url": "https://oqur.io/d/7Kq2xP",
"target": { "url": "https://kafeadi.com/kis-menusu" },
"updated_at": "2026-09-30T10:15:03Z"
}
}
Копирование
POST
/qr-codes/{id}/duplicate
Копирует код вместе с дизайном и назначением. Копия получает новую короткую ссылку и ноль сканирований; самый быстрый способ повторить один дизайн для филиалов.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:write
Параметры пути
| Поле | Тип | Описание |
|---|---|---|
idобязательно |
string |
Идентификатор кода для копирования. |
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
name |
string |
Название копии. Если не указано, к исходному названию добавляется «(копия)». |
folder_id |
string |
Папка для копии. По умолчанию — папка исходного кода. |
Коды статусов
- 201 Копия создана.
- 401 API-ключ отсутствует или недействителен.
- 403 Достигнут лимит динамических кодов.
- 404 Код не существует или не ваш.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/duplicate \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Плакат · Бешикташ" }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/duplicate', [
'json' => ['name' => 'Плакат · Бешикташ'],
]);
const { data: copy } = await oqur('/qr-codes/qr_7Kq2mX/duplicate', {
method: 'POST',
body: JSON.stringify({ name: 'Плакат · Бешикташ' }),
});
Ответ 201 ПРИМЕР
{
"data": {
"id": "qr_9Ms4pZ",
"type": "url",
"name": "Плакат · Бешикташ",
"status": "active",
"short_url": "https://oqur.io/d/9Ms4pR",
"scans_total": 0,
"created_at": "2026-09-30T10:20:31Z"
}
}
Создание изображения
POST
/qr-codes/{id}/image
Создаёт готовое к печати изображение кода и возвращает временную ссылку для скачивания. Можно передать настройки только для этого изображения, не меняя сохранённый дизайн.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:read
Параметры пути
| Поле | Тип | Описание |
|---|---|---|
idобязательно |
string |
Идентификатор кода. |
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
formatобязательно |
string |
png, svg, pdf или eps. |
size |
integer |
Для PNG — длина стороны в пикселях. От 256 до 4096; по умолчанию 1024. |
margin |
integer |
Тихая зона в модулях. По умолчанию 4; меньше не рекомендуется. |
design |
object |
Временные настройки дизайна только для этого изображения. |
Ссылка для скачивания действует 1 час. Если хотите хранить файл на своём сервере, используйте эндпоинт «Получение изображения».
Коды статусов
- 200 Изображение готово.
- 401 API-ключ отсутствует или недействителен.
- 404 Код не существует или не ваш.
- 422 Неподдерживаемый формат или размер.
curl -X POST https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "format": "svg", "margin": 4 }'
<?php
$res = $oqur->post('qr-codes/qr_7Kq2mX/image', [
'json' => ['format' => 'svg', 'margin' => 4],
]);
$url = json_decode($res->getBody(), true)['data']['url'];
const { data } = await oqur('/qr-codes/qr_7Kq2mX/image', {
method: 'POST',
body: JSON.stringify({ format: 'svg', margin: 4 }),
});
console.log(data.url); // действует 1 час
Ответ 200 ПРИМЕР
{
"data": {
"format": "svg",
"url": "https://cdn.oqur.io/r/qr_7Kq2mX.svg?sig=Vb8f2…",
"expires_at": "2026-09-30T11:12:44Z"
}
}
Получение изображения
GET
/qr-codes/{id}/image.{format}
Возвращает изображение прямо в виде файла. Ответ — сам файл, а не JSON; удобно хранить на своём сервере или добавить в процесс печати.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:read
Параметры пути
| Поле | Тип | Описание |
|---|---|---|
idобязательно |
string |
Идентификатор кода. |
formatобязательно |
string |
png, svg, pdf или eps. |
Параметры запроса
| Поле | Тип | Описание |
|---|---|---|
size |
integer |
Для PNG — длина стороны в пикселях. По умолчанию 1024. |
margin |
integer |
Тихая зона в модулях. По умолчанию 4. |
Коды статусов
- 200 Файл получен.
- 401 API-ключ отсутствует или недействителен.
- 404 Код не существует или не ваш.
- 422 Неподдерживаемый формат или размер.
curl https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048 \
-H "Authorization: Bearer $OQUR_API_KEY" \
-o masa-karti.png
<?php
$oqur->get('qr-codes/qr_7Kq2mX/image.png', [
'query' => ['size' => 2048],
'sink' => __DIR__ . '/masa-karti.png',
]);
import { writeFile } from 'node:fs/promises';
const res = await fetch('https://api.oqur.io/v1/qr-codes/qr_7Kq2mX/image.png?size=2048', {
headers: { Authorization: `Bearer ${process.env.OQUR_API_KEY}` },
});
await writeFile('masa-karti.png', Buffer.from(await res.arrayBuffer()));
Ответ 200 ПРИМЕР
HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 48213
Content-Disposition: attachment; filename="qr_7Kq2mX.png"
Cache-Control: private, max-age=300
(ikili PNG verisi)
Массовое удаление
DELETE
/qr-codes?ids=…
Перемещает до 100 кодов в корзину. Коды из корзины можно вернуть в панели в течение 30 дней; сканирующие динамический код из корзины видят страницу «этот код не используется». Если нужно только остановить код, установите статус paused.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:write
Параметры запроса
| Поле | Тип | Описание |
|---|---|---|
idsобязательно |
string |
Идентификаторы кодов через запятую, не больше 100. |
Коды статусов
- 200 Коды перемещены в корзину.
- 401 API-ключ отсутствует или недействителен.
- 404 Код из списка не найден; ни один код не удалён.
- 422 Список идентификаторов пуст или длиннее 100.
curl -X DELETE "https://api.oqur.io/v1/qr-codes?ids=qr_7Kq2mX,qr_8Lr3nY,qr_9Ms4pZ" \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->delete('qr-codes', ['query' => [
'ids' => implode(',', ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ']),
]]);
const ids = ['qr_7Kq2mX', 'qr_8Lr3nY', 'qr_9Ms4pZ'].join(',');
const { meta } = await oqur(`/qr-codes?ids=${ids}`, { method: 'DELETE' });
Ответ 200 ПРИМЕР
{
"meta": { "deleted": 3 }
}
Аналитика
Загружайте данные о сканированиях в свои отчёты. В отчётах нет персональных данных: IP-адрес, идентификатор устройства и точное местоположение не возвращаются.
Отчёт аналитики
GET
/analytics/scans
Возвращает итоги, временной ряд и разбивку для выбранных кодов и диапазона дат. Даты и время группируются в нужном вам часовом поясе.
Аутентификация: ApiKeyAuth (Bearer)Область: analytics:read
Параметры запроса
| Поле | Тип | Описание |
|---|---|---|
fromобязательно |
date |
Дата начала, YYYY-MM-DD. |
toобязательно |
date |
Дата окончания включительно. Диапазон — не больше 366 дней. |
qr_ids |
string |
Идентификаторы кодов через запятую. Если не указано — все коды. |
timezone |
string |
Часовой пояс IANA, например Europe/Moscow. По умолчанию — часовой пояс рабочего пространства. |
group_by |
string |
hour, day, week или month. По умолчанию day. |
breakdown |
string |
country, city, device, os или browser. |
Коды статусов
- 200 Отчёт получен.
- 401 API-ключ отсутствует или недействителен.
- 422 Диапазон дат недействителен или больше 366 дней.
- 429 Вы достигли лимита запросов.
curl -G https://api.oqur.io/v1/analytics/scans \
-H "Authorization: Bearer $OQUR_API_KEY" \
-d from=2026-09-01 \
-d to=2026-09-07 \
-d timezone=Europe/Istanbul \
-d group_by=day \
-d breakdown=device
<?php
$res = $oqur->get('analytics/scans', ['query' => [
'from' => '2026-09-01',
'to' => '2026-09-07',
'timezone' => 'Europe/Istanbul',
'group_by' => 'day',
'breakdown' => 'device',
]]);
const params = new URLSearchParams({
from: '2026-09-01',
to: '2026-09-07',
timezone: 'Europe/Istanbul',
group_by: 'day',
breakdown: 'device',
});
const { data: report } = await oqur(`/analytics/scans?${params}`);
Ответ 200 ПРИМЕР
{
"data": {
"range": { "from": "2026-09-01", "to": "2026-09-07", "timezone": "Europe/Istanbul" },
"totals": { "scans": 1840, "unique_scans": 1312 },
"series": [
{ "period": "2026-09-01", "scans": 212, "unique_scans": 160 },
{ "period": "2026-09-02", "scans": 247, "unique_scans": 181 }
],
"breakdown": {
"by": "device",
"items": [
{ "key": "ios", "scans": 1011 },
{ "key": "android", "scans": 783 },
{ "key": "desktop", "scans": 46 }
]
}
}
}
Папки
Группируйте коды по филиалам, кампаниям или клиентам. Каждый в команде видит все папки; что он может делать, решает его роль.
Создание папки
POST
/folders
Создаёт новую папку для группировки кодов.
Аутентификация: ApiKeyAuth (Bearer)Область: folders:write
Тело запроса
| Поле | Тип | Описание |
|---|---|---|
nameобязательно |
string |
Название папки, от 1 до 80 символов. Должно быть уникальным в вашем аккаунте. |
Коды статусов
- 201 Папка создана.
- 401 API-ключ отсутствует или недействителен.
- 409 Папка с таким названием уже есть.
- 422 Название пустое или длиннее 80 символов.
curl -X POST https://api.oqur.io/v1/folders \
-H "Authorization: Bearer $OQUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Филиал в Кадыкёе" }'
<?php
$res = $oqur->post('folders', ['json' => ['name' => 'Филиал в Кадыкёе']]);
const { data: folder } = await oqur('/folders', {
method: 'POST',
body: JSON.stringify({ name: 'Филиал в Кадыкёе' }),
});
Ответ 201 ПРИМЕР
{
"data": {
"id": "fld_91xQ",
"name": "Филиал в Кадыкёе",
"qr_count": 0,
"created_at": "2026-09-30T10:31:08Z"
}
}
Список папок
GET
/folders
Возвращает папки вашего аккаунта и число кодов в каждой.
Аутентификация: ApiKeyAuth (Bearer)Область: qr:read
Параметры запроса
| Поле | Тип | Описание |
|---|---|---|
page |
integer |
Номер страницы. По умолчанию 1. |
per_page |
integer |
Записей на странице. По умолчанию 25, не больше 100. |
Коды статусов
- 200 Список получен.
- 401 API-ключ отсутствует или недействителен.
curl https://api.oqur.io/v1/folders \
-H "Authorization: Bearer $OQUR_API_KEY"
<?php
$res = $oqur->get('folders');
$folders = json_decode($res->getBody(), true)['data'];
const { data: folders } = await oqur('/folders');
Ответ 200 ПРИМЕР
{
"data": [
{ "id": "fld_91xQ", "name": "Филиал в Кадыкёе", "qr_count": 14 },
{ "id": "fld_22bR", "name": "Упаковка · Сентябрь", "qr_count": 120 }
],
"meta": { "page": 1, "per_page": 25, "total": 2 }
}
Коды ошибок
Ошибки всегда возвращаются одинаково: HTTP-код статуса и объект error. Поле code — для вашего ПО, поле message — для людей; текст сообщения может меняться, ориентируйтесь на код.
Статусы
| HTTP | code | Описание |
|---|---|---|
400 |
bad_request |
Не удалось прочитать тело запроса. Убедитесь, что JSON корректен, и проверьте заголовок Content-Type. |
401 |
unauthenticated |
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization. |
403 |
forbidden |
Ваш тариф или ключ не позволяет это сделать; например, достигнут лимит динамических кодов. |
404 |
not_found |
Запись не существует или не принадлежит вашему аккаунту. |
409 |
conflict |
Запись с таким названием уже есть, или Idempotency-Key повторно использован с другим телом. |
422 |
validation_failed |
Поле недействительно. Какое поле отклонено и почему — в массиве details. |
429 |
rate_limited |
Вы достигли лимита запросов. Подождите Retry-After. |
500 |
server_error |
У нас что-то пошло не так. Попробуйте снова; если ошибка повторяется, напишите нам и укажите request_id. |
Ответ 422 ПРИМЕР
{
"error": {
"code": "validation_failed",
"message": "2 элемента не прошли проверку.",
"details": [
{ "field": "items.0.target.url", "message": "Должен быть корректный веб-адрес." },
{ "field": "items.3.type", "message": "Bilinmeyen QR tipi: menu2." }
],
"request_id": "req_3hV8qL"
}
}
Что-то не так?
Напишите нам и укажите значение request_id; мы найдём ваш запрос и разберёмся.
Техническая поддержкаСначала попробуйте в панели, затем автоматизируйте.
Когда API будет готов, он откроется на тарифах Бизнес и Корпоративный. Об интеграциях для компаний можно поговорить с нашим отделом продаж.