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

Рекс.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].