Автентифікація та дозволи
Кожен запит — із ключем у заголовку Authorization: Bearer rks_live_…. Інших способів немає: ключ у рядку запиту чи в cookie не приймається. Адреса API — https://api.reks.com.ua/v1, лише HTTPS.
Що може ключ
- Ключ належить одній компанії і працює від імені учасника, який його створив.
- Можна лише те, що дозволяють і дозволи ключа, і поточна роль цього учасника. Заберете в ролі право — ключ втратить його одразу, навіть якщо дозвіл на ключі є (
403 PERMISSION_DENIED). - Ключ бачить магазини свого творця — або лише вибрані з них.
- Учасника вимкнули чи прибрали з компанії — його ключі перестають працювати (
401 API_KEY_OWNER_INACTIVE). - Дозвіл на запис включає читання:
orders:writeдає йorders:read. - Дозволи й магазини ключа після створення не змінюються. Потрібно інакше — створіть новий ключ, а старий відкличте, коли перейдете на новий.
Дозволи
| Розділ | Дозвіл | Що дає | Права ролі |
|---|---|---|---|
| Замовлення | orders:read | Читати замовлення | orders.read |
orders:write | Створювати й змінювати замовлення, скасовувати, переводити між етапами, відмічати відправку й доставку | orders.create, orders.update | |
orders:payments | Додавати й видаляти оплати замовлень | orders.payments | |
| Клієнти | customers:read | Читати клієнтів | customers.read |
customers:write | Створювати й змінювати клієнтів | customers.create, customers.update | |
| Каталог | catalog:read | Читати товари, варіанти й категорії | catalog.read |
catalog:write | Створювати й змінювати товари | catalog.create, catalog.update | |
| Склад | inventory:read | Читати залишки по складах | inventory.read |
inventory:write | Змінювати залишки | inventory.adjust | |
| Посилки | shipments:read | Читати посилки та їхні статуси | shipments.read |
| Закупівлі | purchases:read | Читати закупівлі | purchases.read |
purchases:write | Створювати й змінювати закупівлі | purchases.create, purchases.update | |
| Постачальники | suppliers:read | Читати постачальників | suppliers.read |
suppliers:write | Створювати й змінювати постачальників | suppliers.create, suppliers.update | |
| Прибуток | profit:read | Бачити собівартість, прибуток і націнку. Без нього ці поля — | reports.profit |
| Вебхуки | webhooks:manage | Керувати вебхуками через API | settings.api |
Ключу можна дати лише ті дозволи, які є у вашій ролі. Довідкові дані — магазини, склади, етапи, способи оплати, мітки, додаткові поля, валюти — доступні будь-якому ключу.
IP-адреси, строк дії, відкликання
- Дозволені адреси. Вкажіть IP чи діапазони CIDR (
203.0.113.7,203.0.113.0/24, IPv6) — з інших адрес ключ отримає403 API_KEY_IP_NOT_ALLOWED. Список можна змінити будь-коли. - Строк дії. Ключ працює до вказаної дати включно (за київським часом), далі —
401 API_KEY_EXPIRED. - Відкликання. «Відкликати» в «Налаштування → API» вимикає ключ одразу (
401 API_KEY_REVOKED). Там само видно, коли й з якої адреси ключем користувалися востаннє, і журнал запитів за 30 днів.
Формати
- JSON і camelCase:
paymentStatus,createdAt. Тіло запиту — зContent-Type: application/json, у UTF-8. - Ідентифікатори — UUID.
- Гроші й кількості — рядки з десятковою крапкою:
"1250.00","1.5". Так копійки не губляться на округленні дробових чисел. У запитах можна надсилати й число (1250) — його прочитаємо точно так, як написано. - Дати —
YYYY-MM-DDза київським часом (orderDate). Моменти часу — ISO-8601 в UTC (2026-11-15T09:30:00.000Z). - Порожнє значення — `null`: поле не зникає з відповіді.
- Нові поля можуть з’явитися у відповідях будь-коли — пропускайте те, чого не знаєте, і не перевіряйте відповідь як закриту схему.
- Мова повідомлень про помилки — за
Accept-Language(uk,en,ru). Дані не перекладаються.
{
"total": "1250.00",
"items": [{ "qty": "1.5", "unitPrice": "833.33" }],
"orderDate": "2026-11-15",
"createdAt": "2026-11-15T09:30:00.000Z",
"trackingNumber": null,
"customFields": { "color": "red" }
}Помилки
Помилка — це HTTP-статус 4xx чи 5xx і JSON однакової форми. Розгалужуйтеся за code — він стабільний. message написано для людей, він може змінюватися.
HTTP/1.1 403 Forbidden
X-Request-Id: 01a1dccb-76b1-7001-8d2f-f4a5f479cebd
{
"statusCode": 403,
"code": "API_SCOPE_MISSING",
"message": "API-ключу бракує дозволу orders:write"
}Кожна відповідь має заголовок X-Request-Id. Записуйте його в лог: за ним підтримка знайде ваш запит за секунди.
| Статус | Код | Що сталося |
|---|---|---|
| 400 | VALIDATION_FAILED | Неправильні поля запиту — див. |
| 400 | IDEMPOTENCY_KEY_INVALID |
|
| 401 | API_KEY_MISSING | Немає заголовка |
| 401 | API_KEY_INVALID | Такого ключа немає — перевірте, чи скопійовано його повністю |
| 401 | API_KEY_REVOKED | Ключ відкликано |
| 401 | API_KEY_EXPIRED | Минув строк дії ключа |
| 401 | API_KEY_OWNER_INACTIVE | Творець ключа більше не має доступу до компанії |
| 403 | API_SCOPE_MISSING | У ключа немає потрібного дозволу |
| 403 | PERMISSION_DENIED | Роль творця ключа більше не дає цього права |
| 403 | API_KEY_IP_NOT_ALLOWED | Запит з адреси, якої немає серед дозволених |
| 403 | API_KEY_NO_SHOPS | У ключа не лишилося доступних магазинів |
| 404 | NOT_FOUND | Немає такого запису, або він у магазині, якого ключ не бачить ( |
| 409 | INSUFFICIENT_STOCK | Не вистачає товару на складі |
| 409 | IDEMPOTENCY_IN_PROGRESS | Запит із цим |
| 409 | IDEMPOTENCY_ANSWER_NOT_KEPT | Запит із цим |
| 422 | IDEMPOTENCY_KEY_REUSED | Цей |
| 429 | RATE_LIMITED | Перевищено ліміт запитів — зачекайте |
| 429 | COMPANY_THROTTLED | Платформа тимчасово обмежила запити компанії — зачекайте |
| 429 | API_AUTH_THROTTLED | Забагато запитів з неправильним ключем з однієї адреси |
| 500 | INTERNAL_ERROR | Збій на нашому боці. Повторіть пізніше; якщо повторюється — напишіть у підтримку з |
У VALIDATION_FAILED поле details перелічує неправильні поля:
{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "Перевірте правильність заповнення полів",
"details": [{ "path": "items.0.qty", "code": "invalid_type", "message": "…" }]
}Ліміти
Ліміти рахуються щохвилини: 120 запитів на ключ і 240 на компанію — усі її ключі разом. На всіх тарифах однакові.
Кожна відповідь на запит із дійсним ключем показує стан його ліміту:
| Заголовок | Значення |
|---|---|
X-RateLimit-Limit | Скільки запитів на хвилину можна цьому ключу |
X-RateLimit-Remaining | Скільки лишилося в поточній хвилині |
X-RateLimit-Reset | Через скільки секунд почнеться нова хвилина |
Retry-After | У відповіді 429: скільки секунд почекати |
HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
HTTP/1.1 429 Too Many Requests
Retry-After: 42- Перевищили — отримаєте
429 RATE_LIMITED. ЗачекайтеRetry-Afterсекунд і повторіть. - Для великих вивантажень беріть сторінки по 100 і
updatedSince, а не весь список щоразу. - Замість частого опитування підпишіться на вебхуки.
Пагінація та синхронізація
Списки віддаються сторінками: page (з 1) і pageSize (до 100, за замовчуванням 50). Відповідь:
{
"items": [ … ],
"page": 1,
"pageSize": 50,
"total": 132,
"hasMore": true
}Синхронізація. Щоб забирати лише змінене, сортуйте sort=updatedAt:asc і передавайте updatedSince — момент найпізнішої зміни, яку ви вже бачили. Межа включна, тож той самий запис може прийти двічі: оновлюйте за id, а не додавайте.
// Incremental sync: everything that changed since the last run.
const BASE = 'https://api.reks.com.ua/v1';
let since = await loadCursor(); // e.g. '2026-11-01T00:00:00.000Z' — kept in your DB
let page = 1;
while (true) {
const qs = new URLSearchParams({ sort: 'updatedAt:asc', updatedSince: since, page: String(page), pageSize: '100' });
const res = await fetch(`${BASE}/orders?${qs}`, {
headers: { Authorization: `Bearer ${process.env.REKS_API_KEY}` },
});
if (res.status === 429) { await sleep(Number(res.headers.get('Retry-After') ?? 5) * 1000); continue; }
if (!res.ok) throw new Error(`${res.status} ${res.headers.get('X-Request-Id')}: ${await res.text()}`);
const { items, hasMore } = await res.json();
for (const order of items) await upsertOrder(order); // by order.id — the same order may come twice
if (!hasMore) break;
// move the cursor, not the page: rows changed meanwhile can't slip between pages
const last = items[items.length - 1].updatedAt;
if (last === since) page++; // a whole page with one updatedAt — step over it
else { since = last; page = 1; }
}
await saveCursor(since); // the next run starts here (inclusive: upserts make repeats harmless)Ідемпотентність
Мережа рветься: запит міг дійти, а відповідь — ні. Щоб повтор не створив друге замовлення, надсилайте заголовок Idempotency-Key у POST-запитах, які щось створюють (у довіднику в них є цей параметр).
- Ключ — будь-який унікальний рядок до 255 видимих ASCII-символів: UUID чи номер замовлення на вашому сайті.
- Повтор із тим самим ключем і тим самим тілом протягом 24 годин поверне першу відповідь із заголовком
Idempotent-Replayed: true. - Той самий ключ з іншим тілом —
422 IDEMPOTENCY_KEY_REUSED. - Перший запит ще виконується —
409 IDEMPOTENCY_IN_PROGRESS: зачекайте секунду й повторіть. - Запам’ятовуються лише успішні відповіді: після помилки виправте запит і надішліть його з тим самим ключем.
- У кожного API-ключа свої
Idempotency-Key— збіг між двома програмами нічого не зламає.
# the first call creates the order
curl https://api.reks.com.ua/v1/orders -H "Authorization: Bearer $REKS_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: site-order-10045" -d @order.json
# HTTP/1.1 201 Created
# the network dropped — the same call again: the same order, not a second one
curl https://api.reks.com.ua/v1/orders -H "Authorization: Bearer $REKS_API_KEY" \
-H "Content-Type: application/json" -H "Idempotency-Key: site-order-10045" -d @order.json
# HTTP/1.1 201 Created
# Idempotent-Replayed: trueВебхуки
Вебхук — це POST-запит від Рекс.Селлер на ваш сервер, щойно щось змінилося. Не треба опитувати API щохвилини.
Адреси додаються в Налаштування → API → Вебхуки (або через API з дозволом webhooks:manage) — до 10 на компанію. Для кожної виберіть події. Секрет підпису whsec_… показується один раз.
Події
| Подія | Коли | Потрібен доступ |
|---|---|---|
order.created | Нове замовлення — з будь-якого каналу | orders:read |
order.updated | Замовлення змінено | orders:read |
order.status_changed | Змінився статус: відправлено, доставлено, скасовано… | orders:read |
order.stage_changed | Замовлення перейшло на інший етап | orders:read |
order.deleted | Замовлення видалено | orders:read |
customer.created | Новий клієнт | customers:read |
customer.updated | Клієнта змінено | customers:read |
customer.deleted | Клієнта видалено | customers:read |
product.created | Новий товар | catalog:read |
product.updated | Товар змінено | catalog:read |
product.deleted | Товар видалено | catalog:read |
stock.changed | Змінився залишок товару | inventory:read |
shipment.updated | Змінився статус посилки | shipments:read |
purchase.updated | Закупівлю змінено | purchases:read |
Адреса отримує лише ті події, дані яких бачить її творець: для подій замовлень потрібне право читати замовлення і так далі.
Що приходить
Тіло легке: id події, type, createdAt, companyId і data — id запису та що змінилося. Повні дані беріть запитом GET: так ви бачите актуальний стан, навіть якщо події прийшли не по черзі. Тестова подія ping приходить, коли ви перевіряєте адресу в налаштуваннях.
POST /webhooks/reks HTTP/1.1
Content-Type: application/json
User-Agent: RexSeller-Webhooks/1.0
webhook-id: 01936f70-4a5b-7c6d-8e7f-9a0b1c2d3e4f
webhook-timestamp: 1794735000
webhook-signature: v1,p1CdDDZcgvpZT/1cAxfg5Q4c/BKebz/fggch9JHMQMo=
{
"id": "01936f70-4a5b-7c6d-8e7f-9a0b1c2d3e4f",
"type": "order.created",
"createdAt": "2026-11-15T09:30:00.000Z",
"companyId": "01936f5e-8a3b-7c4d-9e2f-1a2b3c4d5e6f",
"data": {
"id": "01936f62-3f4a-7b5c-8d6e-7f8a9b0c1d2e",
"number": "00045",
"shopId": "01936f5f-0c1d-7e2f-8a3b-4c5d6e7f8a9b",
"status": "ready",
"paymentStatus": "unpaid",
"shipmentStatus": "not_shipped",
"stageId": "01936f63-4a5b-7c6d-8e7f-9a0b1c2d3e4f",
"externalId": "site-10045"
}
}Заголовки
| Заголовок | Значення |
|---|---|
webhook-id | Id події, однаковий у всіх повторних спробах. Ваш ключ для відсіювання дублікатів |
webhook-timestamp | Коли надіслано, секунди Unix |
webhook-signature |
|
Перевірка підпису
Підпис — за специфікацією Standard Webhooks: HMAC-SHA256 від рядка <webhook-id>.<webhook-timestamp>.<тіло>, ключ — частина секрету після whsec_, декодована з base64. Рахуйте від сирого тіла запиту, до розбору JSON. Порівнюйте підписи порівнянням зі сталим часом і відкидайте запити зі старим webhook-timestamp (понад 5 хвилин). Замість коду нижче можна взяти готову бібліотеку Standard Webhooks для вашої мови.
// Node.js 18+ with Express. The signature covers the RAW body: read it before any JSON parser.
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.REKS_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_S = 300;
function verifyReksWebhook(rawBody, headers) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_S) return false; // replay
const key = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest();
return signatures.split(' ').some((part) => {
const [version, signature] = part.split(',');
if (version !== 'v1' || !signature) return false;
const given = Buffer.from(signature, 'base64');
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}
// your own storage / queue — here in memory
const handled = new Set();
const alreadyHandled = (id) => handled.has(id) || !handled.add(id);
const queue = { push: (event) => setImmediate(() => console.log('reks event', event.type, event.data.id)) };
const app = express();
app.post('/webhooks/reks', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyReksWebhook(req.body, req.headers)) return res.status(401).end();
const event = JSON.parse(req.body.toString('utf8'));
res.status(204).end(); // answer at once, work afterwards
if (alreadyHandled(event.id)) return; // a retry repeats the same webhook-id
queue.push(event); // e.g. GET /orders/{event.data.id} and update your system
});
app.listen(3000);<?php
// PHP 7.3+. The signature covers the RAW body: read php://input, not $_POST.
const TOLERANCE_S = 300;
function verify_reks_webhook(string $body, array $headers, string $secret): bool
{
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
$signatures = $headers['webhook-signature'] ?? '';
if ($id === '' || $timestamp === '' || $signatures === '') return false;
if (abs(time() - (int) $timestamp) > TOLERANCE_S) return false; // replay
$key = base64_decode(preg_replace('/^whsec_/', '', $secret));
$expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$body", $key, true));
foreach (explode(' ', $signatures) as $part) {
[$version, $signature] = array_pad(explode(',', $part, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $signature)) return true;
}
return false;
}
$body = file_get_contents('php://input');
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
if (!verify_reks_webhook($body, $headers, getenv('REKS_WEBHOOK_SECRET'))) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// $event['id'] is the webhook-id: skip it if you have it already, save the event, process it later
http_response_code(204);# Python 3.9+ with Flask. The signature covers the RAW body: request.get_data(), not the parsed JSON.
import base64, hashlib, hmac, os, time
from flask import Flask, request
SECRET = os.environ["REKS_WEBHOOK_SECRET"] # whsec_…
TOLERANCE_S = 300
def verify_reks_webhook(body: bytes, headers) -> bool:
msg_id = headers.get("webhook-id", "")
timestamp = headers.get("webhook-timestamp", "")
signatures = headers.get("webhook-signature", "")
if not (msg_id and timestamp and signatures):
return False
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_S:
return False # replay
key = base64.b64decode(SECRET.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
for part in signatures.split(" "):
version, _, signature = part.partition(",")
if version == "v1" and hmac.compare_digest(signature, expected):
return True
return False
app = Flask(__name__)
@app.post("/webhooks/reks")
def reks_webhook():
body = request.get_data()
if not verify_reks_webhook(body, request.headers):
return "", 401
event = request.get_json()
# event["id"] is the webhook-id: skip it if you have it already, queue the work, answer at once
return "", 204Доставка й повтори
- Відповідайте 2xx протягом 10 секунд, а подію обробляйте вже після відповіді (черга, фонова задача). Переадресації не виконуються.
- Не відповіли або відповіли не 2xx — повторимо через 1 хв, 5 хв, 30 хв, 2 год, 6 год, 12 год, 24 год.
- Після 30 невдалих доставок поспіль адресу буде вимкнено. Увімкнути її знову, переглянути журнал доставок і надіслати доставку повторно можна в «Налаштування → API → Вебхуки».
- Одна подія може прийти більше одного разу — відсіюйте дублікати за
webhook-id. - Порядок подій не гарантовано: орієнтуйтеся на
updatedAtзапису. - Секрет можна замінити на новий, якщо він міг потрапити в чужі руки. Старий перестає діяти одразу, тож на час заміни перевіряйте підпис обома секретами.
Версіонування
- Поточна версія — v1, вона в адресі:
https://api.reks.com.ua/v1. - У межах v1 зміни лише додаються: нові ресурси, поля, параметри, події, значення переліків. Ваш код має спокійно пропускати незнайоме.
- Зміни, що можуть зламати інтеграцію (перейменування, видалення, інший тип поля), вийдуть лише в новій версії —
/v2. Про неї попередимо заздалегідь, а v1 працюватиме далі. - Версія опису — у полі
info.versionOpenAPI-документа.
Журнал змін
- 15 листопада 2026
Перша публічна версія Рекс.API: ключі з дозволами, REST-запити (усі — у довіднику) і вебхуки з підписом.
Безпека
- Ключ — лише на сервері. Не вставляйте його в код сайту, мобільного застосунку чи розширення браузера: звідти його легко дістати. Тому API навмисно не відповідає на запити з браузера (CORS).
- Зберігайте ключ у змінних оточення чи сховищі секретів, а не в репозиторії.
- Мінімум дозволів. Ключу сайту, який лише створює замовлення, не потрібні запис у каталог чи прибуток.
- Окремий ключ для кожної програми. Тоді відкликання одного не зупинить інші, а в журналі запитів видно, хто що робив.
- Обмежте IP-адреси, якщо в сервера постійна адреса, і задайте строк дії.
- Замінюйте ключі: періодично — і одразу, якщо ключ міг витекти. Створіть новий, переведіть на нього програму, відкличте старий.