Перейти до основного вмісту

Рекс.API

API для розробників: Рекс.Селлер у ваших програмах

REST API і вебхуки Рекс.Селлер. Приймайте замовлення з власного сайту, передавайте продажі й оплати в 1С чи BAS, оновлюйте залишки зі складських скриптів, будуйте сценарії в Make, Zapier чи n8n.

На всіх тарифах · JSON через HTTPS · опис OpenAPI 3.1

GET /me
curl https://api.reks.com.ua/v1/me \
  -H "Authorization: Bearer $REKS_API_KEY"
  • Ваш сайтЗамовлення з кошика одразу в Рекс.Селлер — з резервом товару й клієнтом за телефоном.
  • 1С / BASПродажі, оплати й залишки — у вашу облікову програму без вивантажень руками.
  • Складські скриптиЗалишки й посилки — з терміналу збору даних чи власної програми складу.
  • Make, Zapier, n8nHTTP-запити й вебхуки: повідомлення в Telegram, таблиці, свої сценарії без коду.

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

Перше замовлення через API за 5 хвилин

  1. 1

    Створіть ключ

    У кабінеті: Налаштування → API → Створити ключ. Назвіть його, наприклад «Сайт», і виберіть дозволи — для цього прикладу orders:write. Ключ rks_live_… показується один раз: збережіть його в змінних оточення сервера.

    Відкрити налаштування API
  2. 2

    Перевірте ключ

    GET /me відповідає, до якої компанії належить ключ, які в нього дозволи й від чийого імені він працює.

    curl
    curl https://api.reks.com.ua/v1/me \
      -H "Authorization: Bearer $REKS_API_KEY"
  3. 3

    Створіть замовлення

    Товар резервується одразу, клієнт знаходиться або створюється за телефоном, ціни — з магазину. Заголовок Idempotency-Key гарантує, що повтор запиту не створить друге замовлення.

    POST /orders
    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 '{
        "externalId": "site-10045",
        "customer": { "phone": "+380671234567", "name": "Олена Коваль" },
        "items": [{ "sku": "TEA-001", "qty": 2 }],
        "comment": "Подзвонити перед відправкою"
      }'
    Відповідь
    HTTP/1.1 201 Created
    X-Request-Id: 01a1dccb-76b1-7001-8d2f-f4a5f479cebd
    
    {
      "id": "01936f62-3f4a-7b5c-8d6e-7f8a9b0c1d2e",
      "number": "00045",
      "status": "ready",
      "paymentStatus": "unpaid",
      "source": "api",
      "externalId": "site-10045",
      "currency": "UAH",
      "total": "560.00",
      "items": [ … ],
      "createdAt": "2026-11-15T09:30:00.000Z",
      "updatedAt": "2026-11-15T09:30:00.000Z",
      …
    }
  4. 4

    Слухайте order.created

    Додайте адресу свого сервера в Налаштування → API → Вебхуки і виберіть події. Рекс.Селлер надсилатиме підписаний POST про кожне нове замовлення — з сайту, маркетплейсу чи створене менеджером.

    Як перевірити підпис
    order.created → https://your-site.example/webhooks/reks
    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"
      }
    }

Автентифікація та дозволи

Кожен запит — із ключем у заголовку 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

Бачити собівартість, прибуток і націнку. Без нього ці поля — null

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). Дані не перекладаються.
JSON
{
  "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. Записуйте його в лог: за ним підтримка знайде ваш запит за секунди.

Помилки
СтатусКодЩо сталося
400VALIDATION_FAILED

Неправильні поля запиту — див. details

400IDEMPOTENCY_KEY_INVALID

Idempotency-Key довший за 255 символів або з недопустимими символами

401API_KEY_MISSING

Немає заголовка Authorization: Bearer …

401API_KEY_INVALID

Такого ключа немає — перевірте, чи скопійовано його повністю

401API_KEY_REVOKED

Ключ відкликано

401API_KEY_EXPIRED

Минув строк дії ключа

401API_KEY_OWNER_INACTIVE

Творець ключа більше не має доступу до компанії

403API_SCOPE_MISSING

У ключа немає потрібного дозволу

403PERMISSION_DENIED

Роль творця ключа більше не дає цього права

403API_KEY_IP_NOT_ALLOWED

Запит з адреси, якої немає серед дозволених

403API_KEY_NO_SHOPS

У ключа не лишилося доступних магазинів

404NOT_FOUND

Немає такого запису, або він у магазині, якого ключ не бачить (ORDER_NOT_FOUND, PRODUCT_NOT_FOUND…)

409INSUFFICIENT_STOCK

Не вистачає товару на складі

409IDEMPOTENCY_IN_PROGRESS

Запит із цим Idempotency-Key ще виконується

409IDEMPOTENCY_ANSWER_NOT_KEPT

Запит із цим Idempotency-Key уже виконано, але відповідь не збережено (дуже велика або вичерпано добовий обсяг збережених відповідей) — прочитайте ресурс окремим запитом

422IDEMPOTENCY_KEY_REUSED

Цей Idempotency-Key уже використано з іншим тілом запиту

429RATE_LIMITED

Перевищено ліміт запитів — зачекайте Retry-After секунд

429COMPANY_THROTTLED

Платформа тимчасово обмежила запити компанії — зачекайте Retry-After секунд

429API_AUTH_THROTTLED

Забагато запитів з неправильним ключем з однієї адреси

500INTERNAL_ERROR

Збій на нашому боці. Повторіть пізніше; якщо повторюється — напишіть у підтримку з X-Request-Id

У VALIDATION_FAILED поле details перелічує неправильні поля:

400 VALIDATION_FAILED
{
  "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
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). Відповідь:

GET /orders?page=1&pageSize=50
{
  "items": [ … ],
  "page": 1,
  "pageSize": 50,
  "total": 132,
  "hasMore": true
}

Синхронізація. Щоб забирати лише змінене, сортуйте sort=updatedAt:asc і передавайте updatedSince — момент найпізнішої зміни, яку ви вже бачили. Межа включна, тож той самий запис може прийти двічі: оновлюйте за id, а не додавайте.

sync.mjs
// 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 — збіг між двома програмами нічого не зламає.
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

v1,<base64> — HMAC-SHA256. Підписів може бути кілька через пробіл: підходить будь-який

Перевірка підпису

Підпис — за специфікацією 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);

Доставка й повтори

  • Відповідайте 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.version OpenAPI-документа.

Журнал змін

  1. 15 листопада 2026

    Перша публічна версія Рекс.API: ключі з дозволами, REST-запити (усі — у довіднику) і вебхуки з підписом.

Безпека

  • Ключ — лише на сервері. Не вставляйте його в код сайту, мобільного застосунку чи розширення браузера: звідти його легко дістати. Тому API навмисно не відповідає на запити з браузера (CORS).
  • Зберігайте ключ у змінних оточення чи сховищі секретів, а не в репозиторії.
  • Мінімум дозволів. Ключу сайту, який лише створює замовлення, не потрібні запис у каталог чи прибуток.
  • Окремий ключ для кожної програми. Тоді відкликання одного не зупинить інші, а в журналі запитів видно, хто що робив.
  • Обмежте IP-адреси, якщо в сервера постійна адреса, і задайте строк дії.
  • Замінюйте ключі: періодично — і одразу, якщо ключ міг витекти. Створіть новий, переведіть на нього програму, відкличте старий.

Готові підключити свою програму?

Ключ створюється за хвилину на будь-якому тарифі. Питання щодо API — пишіть на [email protected].