Authentication and scopes
Every request carries the key in the Authorization: Bearer rks_live_… header. There is no other way: keys in the query string or in cookies are not accepted. The API lives at https://api.reks.com.ua/v1, HTTPS only.
What a key can do
- A key belongs to one company and acts for the member who created it.
- It can do only what both the key's scopes and that member's current role allow. Take a permission away from the role and the key loses it at once, even if the scope is on the key (
403 PERMISSION_DENIED). - A key sees its creator's shops — or only the ones picked for it.
- When the member is disabled or removed from the company, their keys stop working (
401 API_KEY_OWNER_INACTIVE). - A write scope includes read:
orders:writealso grantsorders:read. - A key's scopes and shops can't be changed after it is created. Need something else — create a new key and revoke the old one once you have switched.
Scopes
| Area | Scope | What it allows | Role permissions |
|---|---|---|---|
| Orders | orders:read | Read orders | orders.read |
orders:write | Create and edit orders, cancel them, move them between stages, mark them shipped and delivered | orders.create, orders.update | |
orders:payments | Add and delete order payments | orders.payments | |
| Customers | customers:read | Read customers | customers.read |
customers:write | Create and edit customers | customers.create, customers.update | |
| Catalog | catalog:read | Read products, variants and categories | catalog.read |
catalog:write | Create and edit products | catalog.create, catalog.update | |
| Inventory | inventory:read | Read stock per warehouse | inventory.read |
inventory:write | Change stock | inventory.adjust | |
| Shipments | shipments:read | Read parcels and their statuses | shipments.read |
| Purchases | purchases:read | Read purchases | purchases.read |
purchases:write | Create and edit purchases | purchases.create, purchases.update | |
| Suppliers | suppliers:read | Read suppliers | suppliers.read |
suppliers:write | Create and edit suppliers | suppliers.create, suppliers.update | |
| Profit | profit:read | See cost, profit and markup. Without it these fields are | reports.profit |
| Webhooks | webhooks:manage | Manage webhooks through the API | settings.api |
You can give a key only the scopes your own role has. Reference data — shops, warehouses, stages, payment methods, tags, custom fields, currencies — is readable by any key.
IP addresses, expiry, revoking
- Allowed addresses. List IPs or CIDR ranges (
203.0.113.7,203.0.113.0/24, IPv6) — from anywhere else the key gets403 API_KEY_IP_NOT_ALLOWED. The list can be changed at any time. - Expiry. The key works through the given date (Kyiv time), then
401 API_KEY_EXPIRED. - Revoking. «Revoke» in Settings → API switches the key off immediately (
401 API_KEY_REVOKED). The same page shows when and from which address the key was last used, and a 30-day request log.
Formats
- JSON and camelCase:
paymentStatus,createdAt. Request bodies useContent-Type: application/json, UTF-8. - Identifiers are UUIDs.
- Money and quantities are strings with a decimal point:
"1250.00","1.5"— no kopiyky lost to floating-point rounding. In requests you may send a number too (1250); it is read exactly as written. - Dates are
YYYY-MM-DDin Kyiv time (orderDate). Instants are ISO-8601 in UTC (2026-11-15T09:30:00.000Z). - An empty value is `null`: the field never disappears from a response.
- New fields may appear in responses at any time — skip what you don't know and don't validate responses against a closed schema.
- The language of error messages follows
Accept-Language(uk,en,ru). Data is not translated.
{
"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" }
}Errors
An error is a 4xx or 5xx HTTP status with JSON of one shape. Branch on code — it is stable. message is written for people and may change.
HTTP/1.1 403 Forbidden
X-Request-Id: 01a1dccb-76b1-7001-8d2f-f4a5f479cebd
{
"statusCode": 403,
"code": "API_SCOPE_MISSING",
"message": "API-ключу бракує дозволу orders:write"
}Every response has an X-Request-Id header. Log it: with it, support finds your request in seconds.
| Status | Code | What happened |
|---|---|---|
| 400 | VALIDATION_FAILED | Invalid request fields — see |
| 400 | IDEMPOTENCY_KEY_INVALID |
|
| 401 | API_KEY_MISSING | No |
| 401 | API_KEY_INVALID | There is no such key — check that it was copied in full |
| 401 | API_KEY_REVOKED | The key was revoked |
| 401 | API_KEY_EXPIRED | The key has expired |
| 401 | API_KEY_OWNER_INACTIVE | The key's creator no longer has access to the company |
| 403 | API_SCOPE_MISSING | The key lacks the required scope |
| 403 | PERMISSION_DENIED | The creator's role no longer grants this permission |
| 403 | API_KEY_IP_NOT_ALLOWED | The request came from an address that isn't allowed |
| 403 | API_KEY_NO_SHOPS | The key has no shops left it may use |
| 404 | NOT_FOUND | No such record, or it is in a shop the key can't see ( |
| 409 | INSUFFICIENT_STOCK | Not enough stock in the warehouse |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with this |
| 409 | IDEMPOTENCY_ANSWER_NOT_KEPT | The request with this |
| 422 | IDEMPOTENCY_KEY_REUSED | This |
| 429 | RATE_LIMITED | Rate limit exceeded — wait |
| 429 | COMPANY_THROTTLED | The platform temporarily limited the company's requests — wait |
| 429 | API_AUTH_THROTTLED | Too many requests with a wrong key from one address |
| 500 | INTERNAL_ERROR | Something failed on our side. Retry later; if it keeps happening, write to support with the |
For VALIDATION_FAILED, details lists the invalid fields:
{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "Перевірте правильність заповнення полів",
"details": [{ "path": "items.0.qty", "code": "invalid_type", "message": "…" }]
}Rate limits
Limits are counted per minute: 120 requests per key and 240 per company — all its keys together. They are the same on every plan.
Every response to a request with a valid key shows the state of its limit:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests per minute this key may make |
X-RateLimit-Remaining | How many are left in the current minute |
X-RateLimit-Reset | Seconds until a new minute starts |
Retry-After | In a 429 response: how many seconds to wait |
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- Over the limit you get
429 RATE_LIMITED. WaitRetry-Afterseconds and retry. - For big exports, take pages of 100 and
updatedSinceinstead of the whole list every time. - Subscribe to webhooks instead of polling often.
Pagination and sync
Lists come in pages: page (from 1) and pageSize (up to 100, 50 by default). The response:
{
"items": [ … ],
"page": 1,
"pageSize": 50,
"total": 132,
"hasMore": true
}Sync. To fetch only what changed, sort with sort=updatedAt:asc and pass updatedSince — the latest change you have already seen. The bound is inclusive, so the same record may come twice: update by id, don't append.
// 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
Networks fail: a request may arrive while its response doesn't. So that a retry doesn't create a second order, send an Idempotency-Key header with POST requests that create something (they have this parameter in the reference).
- The key is any unique string of up to 255 visible ASCII characters: a UUID or the order number on your site.
- A retry with the same key and the same body within 24 hours returns the first response with the
Idempotent-Replayed: trueheader. - The same key with a different body —
422 IDEMPOTENCY_KEY_REUSED. - The first request is still running —
409 IDEMPOTENCY_IN_PROGRESS: wait a second and retry. - Only successful responses are remembered: after an error, fix the request and send it with the same key.
- Each API key has its own
Idempotency-Keys — a clash between two programs breaks nothing.
# 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: trueWebhooks
A webhook is a POST request from Рекс.Селлер to your server as soon as something changes. No need to poll the API every minute.
Addresses are added in Settings → API → Webhooks (or through the API with the webhooks:manage scope) — up to 10 per company. Pick the events for each. The whsec_… signing secret is shown once.
Events
| Event | When | Access needed |
|---|---|---|
order.created | A new order — from any channel | orders:read |
order.updated | An order was changed | orders:read |
order.status_changed | The status changed: shipped, delivered, cancelled… | orders:read |
order.stage_changed | The order moved to another stage | orders:read |
order.deleted | An order was deleted | orders:read |
customer.created | A new customer | customers:read |
customer.updated | A customer was changed | customers:read |
customer.deleted | A customer was deleted | customers:read |
product.created | A new product | catalog:read |
product.updated | A product was changed | catalog:read |
product.deleted | A product was deleted | catalog:read |
stock.changed | A product's stock changed | inventory:read |
shipment.updated | A parcel's status changed | shipments:read |
purchase.updated | A purchase was changed | purchases:read |
An address gets only the events whose data its creator can see: order events need permission to read orders, and so on.
What arrives
The body is thin: the event id, type, createdAt, companyId and data — the record's id and what changed. Fetch the full data with a GET: that way you always see the current state, even if events arrive out of order. A test ping event arrives when you test the address in the settings.
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"
}
}Headers
| Header | Meaning |
|---|---|
webhook-id | The event id, the same in every retry. Your key for dropping duplicates |
webhook-timestamp | When it was sent, Unix seconds |
webhook-signature |
|
Verifying the signature
Signatures follow the Standard Webhooks spec: HMAC-SHA256 of the string <webhook-id>.<webhook-timestamp>.<body>, keyed with the part of the secret after whsec_, base64-decoded. Compute it over the raw request body, before parsing the JSON. Compare signatures in constant time and reject requests with an old webhook-timestamp (over 5 minutes). Instead of the code below you can use a ready Standard Webhooks library for your language.
// 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 "", 204Delivery and retries
- Answer 2xx within 10 seconds and process the event after answering (a queue, a background job). Redirects are not followed.
- No answer or not 2xx — we retry after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h.
- After 30 failed deliveries in a row the address is switched off. Turn it back on, see the delivery log and redeliver in Settings → API → Webhooks.
- One event may arrive more than once — drop duplicates by
webhook-id. - Event order is not guaranteed: rely on the record's
updatedAt. - You can replace the secret with a new one if it may have leaked. The old one stops working at once, so while switching verify with both secrets.
Versioning
- The current version is v1, it is in the address:
https://api.reks.com.ua/v1. - Within v1, changes are only additive: new resources, fields, parameters, events, enum values. Your code should quietly skip what it doesn't know.
- Changes that could break an integration (renames, removals, another field type) ship only in a new version —
/v2. We will announce it in advance, and v1 will keep working. - The document version is in
info.versionof the OpenAPI document.
Changelog
- 15 November 2026
The first public version of Рекс.API: scoped keys, REST endpoints (all of them in the reference) and signed webhooks.
Security
- Keys stay on the server. Don't put a key into website code, a mobile app or a browser extension: it is easy to extract from there. That's why the API deliberately doesn't answer browser requests (CORS).
- Keep keys in environment variables or a secret store, not in the repository.
- Least scopes. A website key that only creates orders needs neither catalog write access nor profit.
- One key per program. Revoking one then doesn't stop the others, and the request log shows who did what.
- Restrict IP addresses if your server has a fixed address, and set an expiry date.
- Rotate keys: from time to time — and at once if a key may have leaked. Create a new one, switch the program to it, revoke the old one.