Аутентификация и разрешения
Каждый запрос — с ключом в заголовке 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-адреса, если у сервера постоянный адрес, и задайте срок действия.
- Меняйте ключи: периодически — и сразу, если ключ мог утечь. Создайте новый, переведите на него программу, отзовите старый.