API TradeSYNC

Адрес API — BASE_URL

Для всех запросов к API используйте:

https://online.tradesync.by/api/v1

BASE_URL — это общая начальная часть адреса всех методов API. К ней нужно дописать путь метода из таблицы. Например, для получения товаров полный адрес будет:

GET https://online.tradesync.by/api/v1/products?limit=100
Authorization: Bearer YOUR_API_TOKEN

Проверка подключения: https://online.tradesync.by/api/v1/health. Подразделения: https://online.tradesync.by/api/v1/stores.

Ниже запись {BASE_URL}/products означает: замените {BASE_URL} целиком, вместе с фигурными скобками, на адрес своего API без завершающего слеша. Не добавляйте /api/v1 повторно. YOUR_API_TOKEN замените выданным токеном.

Где запросить токен

Запросить токен можно через чат в личном кабинете.

Выданные ключи доступны в личном кабинете: Настройки → API. Ключ скрыт по умолчанию: его можно показать или скопировать отдельной кнопкой. Здесь же отображаются права, срок действия, последний запрос, индивидуальные лимиты и статистика авторизованных запросов и ошибок по дням, методам и ключам. Доступность вкладки на сервере аккаунта уточните у поддержки.

Период статистики — не более 366 дней. Статистика сохраняется после удаления ключа, если принадлежность запросов аккаунту известна. Просроченные и отозванные ключи нельзя использовать или раскрыть.

Укажите организацию и аккаунт TradeSYNC, назначение интеграции, нужные данные, необходимость создания записей и ожидаемую частоту запросов. Администратор создаст токен для вашего аккаунта и сообщит адрес API, права, срок действия и действующие лимиты.

Быстрый старт

API принимает HTTPS-запросы и возвращает JSON. Базовый путь — /api/v1 на сервере вашего аккаунта. Для основного сервера BASE_URL — https://online.tradesync.by/api/v1. Этот же адрес используется во всех примерах ниже.

GET {BASE_URL}/health
Authorization: Bearer YOUR_API_TOKEN

BASE_URL — полный адрес с окончанием /api/v1. YOUR_API_TOKEN замените выданным токеном. Пример ответа проверки:

{ "data": { "status": "ok", "accountId": 123 } }

Получение товаров:

GET {BASE_URL}/products?limit=100&offset=0&order=name
Authorization: Bearer YOUR_API_TOKEN

Для POST передавайте Content-Type: application/json и JSON-тело. Пример создания товара:

POST {BASE_URL}/products
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{ "name": "Кофе зерновой", "barcode": "4812345678901" }

Успех: HTTP 201 и { "data": { "id": 120 } }. Числа и названия в примерах условные.

Лимиты и пагинация

Секундный и минутный лимиты действуют одновременно. Это значения по умолчанию: администратор может изменить общие настройки или назначить токену индивидуальные ограничения. Уточняйте действующие значения при получении доступа.

При превышении лимита API возвращает HTTP 429 и код RATE_LIMITED. Подождите количество секунд из заголовка Retry-After, затем повторите запрос. Ограничивайте параллелизм и распределяйте загрузку во времени.

• limit — размер страницы, по умолчанию 100, минимум 1, максимум 1000.
• offset — число пропущенных записей, по умолчанию 0, максимум 100000.
• order=name или order=-id — сортировка справочников по поддерживаемому полю; минус означает убывание.
• search — поиск в поддерживающих его методах.

Документы и чеки сортируются по дате по убыванию с устойчивым порядком по ID. Позиции документов и чеков также имеют пагинацию limit/offset и объект meta. Только результат POST /discounts/evaluate возвращается массивом без meta.

Некорректные значения пагинации, массивы вместо одиночных query-параметров и неверные даты отклоняются с HTTP 400. Максимальный offset — 100000, длина search — 200 символов. Размер JSON-тела — не более 256 KiB.

Заголовки лимитера: X-RateLimit-Limit — секундный лимит; X-RateLimit-Remaining — оставшиеся запросы секундного окна; для повторной попытки после 429 ориентируйтесь на Retry-After.

Методы API v1

Все пути ниже дополняют BASE_URL. Вместо {id} передавайте ID записи. Все методы требуют API-токен.

Справочники и остатки

Параметр запроса store_id и поле ответа departmentId обозначают подразделение. В ответе подразделения: address — адрес, parentId — родитель, isActive — активность, isDefault — признак по умолчанию. В единицах измерения unitCode — целочисленный код или null, name — название; conversionFactor — коэффициент пересчёта.

GET /departments и GET /departments/{id} — альтернативные адреса /stores и /stores/{id} с теми же полями ответа.

Документы — чтение

Значения {type}:

• supply — приходные накладные.
• demand — расходные накладные (отпуск).
• salesorder — заказы покупателей.
• invoiceout — счета.
• move — перемещения.
• inventory — инвентаризации.
• repricing — переоценки.

Фильтры списка: from, to, store_id, agent_id, is_draft=true|false, search по номеру. Для перемещения store_id — подразделение-отправитель. Параметр agent_id применим к документам с контрагентом.

В заголовке issuedAt — дата, externalNumber — номер документа контрагента, lineCount — число строк, counterpartyId — контрагент. Состав позиции зависит от типа: у заказов есть orderedQuantity и issuedQuantity, у переоценок — старые и новые цены. Внутренние служебные поля и произвольные столбцы БД не возвращаются. Публичные методы создания и проведения документов не предусмотрены.

Даты фильтров: YYYY-MM-DD либо ISO 8601 с часовым поясом. Если to задан датой без времени, включается весь этот день; диапазон должен быть корректным и упорядоченным.

Поля позиций по типам документов

Каждая позиция содержит id, productId, productName и только перечисленные ниже бизнес-поля выбранного типа. Значения цен, сумм, процентов и количества могут быть числами либо десятичными строками. supplierId — ID поставщика; поля *Percent — проценты; *Price — цены; *Amount — суммы. recordedQuantity — учётный остаток инвентаризации, previous*/new* — значения до/после переоценки.

Чеки и отчёты

totalAmount — итог чека, discountAmount — сумма скидки. В позиции unitPrice и grossAmount — значения до скидки, netUnitPrice и netAmount — после неё. Для смен и отчёта доступны те же фильтры чеков. /checks/shifts группирует чеки по дню и подразделению, а не возвращает отдельные фискальные смены. Из агрегатов исключены отменённые, аннулированные и отложенные чеки; суммы возвратов вычитаются. receiptCount — число включённых чеков, в том числе возвратов.

Скидки

В ranges возвращаются id, minAmount, maxAmount, discountPercent, cardTypeId. Это диапазоны только выбранного типа карты. Пример расчёта корзины:

POST {BASE_URL}/discounts/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "store_id": 1,
  "discount_card_id": null,
  "positions": [{ "goods_id": 120, "quantity": 2, "price": 18.5 }]
}

Расчёт требует право read и возвращает массив строк, не создавая чек. Массив positions должен содержать от 1 до 1000 строк; товары, подразделение и карта должны принадлежать аккаунту ключа. Количество должно быть положительным, цена — неотрицательной. Неактивная или просроченная карта отклоняется. Для правил и карт с ограничением по подразделениям укажите store_id.

discountedQuantity — число единиц, к которым применяется скидка. netUnitPrice — цена этих единиц после скидки; остальные единицы учитываются по unitPrice. netAmount — итог всей строки, discountAmount — скидка по всей строке. Это важно для правила каждой N-й покупки: скидка не обязательно действует на всё количество. Цены и суммы расчёта округляются до двух знаков.

Формат ответов и ошибки

Публичные поля ответа имеют имена camelCase. Имена полей ответа и входных параметров могут отличаться: используйте параметры запроса и JSON-тела POST, указанные в описании соответствующего метода.

Успешное чтение возвращает HTTP 200. Объект находится в data, список — в массиве data. У списков с пагинацией есть meta:

{
  "data": [{ "id": 1, "name": "Основной склад", "isDefault": true,
    "address": "г. Минск", "isActive": true, "parentId": null }],
  "meta": { "total": 1, "limit": 100, "offset": 0 }
}

meta.total — количество записей с учётом фильтров, meta.limit — размер страницы, meta.offset — смещение. Пустой список возвращается как []. Незаполненные поля могут содержать null. Десятичные значения из БД могут приходить строками — учитывайте это при обработке цен и количества.

{ "error": { "code": "RATE_LIMITED", "message": "Превышен лимит запросов. Повторите позже." } }

Для POST-запросов на создание записи не повторяйте запрос автоматически после сетевого тайм-аута: сначала проверьте, не была ли запись создана, чтобы избежать дублей.

Обсудим вашу интеграцию

Напишите, какую систему хотите подключить и какие данные передавать. Поможем уточнить методы, доступ и подходящий режим обмена.

Написать в поддержку ↗

REST API v1 · описание обновлено 4 октября 2026 г.

Вернуться на главную