Перейти к содержимому
oqur

Управляйте кодами из своей системы.

Создавайте сотни QR-кодов одним запросом, обновляйте их назначения, загружайте отчёты о сканированиях в свою панель. Нужны только REST, JSON и API-ключ.

Черновик — эндпоинты будут определены в ходе разработки. На этой странице показана предлагаемая структура; работающего API пока нет. Адреса, названия полей, лимиты и форматы ответов могут измениться.

Базовый URL
https://api.oqur.io/v1
Формат
JSON, UTF-8, HTTPS
Аутентификация
API-ключ Bearer
Тарифы
Бизнес и Корпоративный

Начало работы

API oqur позволяет делать из вашего ПО то же, что вы делаете в панели: массово создавать QR, обновлять назначения, скачивать файлы для печати и получать отчёты о сканированиях. Каждый запрос идёт по HTTPS с телом в JSON.

  1. Создайте ключ

    Создайте ключ в разделе «API-ключи» меню «Настройки» в панели и выберите его области доступа. Когда API будет готов, он откроется на тарифах Бизнес и Корпоративный.

  2. Отправьте первый запрос

    Пример рядом выводит первый код вашего аккаунта. Если ответ 200, всё готово.

  3. Следите за лимитами

    Оставшееся число запросов есть в заголовках каждого ответа. Подробности — в разделе Лимиты запросов.

Правила

ТемаФорматОписание
Дата и время 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 — для людей; текст сообщения может меняться, ориентируйтесь на код.

Статусы

HTTPcodeОписание
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 будет готов, он откроется на тарифах Бизнес и Корпоративный. Об интеграциях для компаний можно поговорить с нашим отделом продаж.