SelSup Developers

Сквозной сценарий · Руководства

Заказы и инкрементальная синхронизация

Создание заказа интернет-магазина, защита от дубликатов, постраничная выгрузка и получение изменившихся заказов.

4 разделовПрактическое руководство
→

Надёжная интеграция разделяет первоначальную загрузку, поток изменений и сверку. externalOrderId связывает заказ SelSup с заказом вашей системы.

Интернет-магазины, OMS и службы доставки

01

Создать заказ интернет-магазина

До создания заказа сопоставьте товары сайта с productId SelSup. Не ищите товар по изменяемому названию во время оформления заказа.

Передавайте внешний номер в externalOrderId и проверяйте его в своей базе до повтора. organizationId особенно важен для аккаунтов с несколькими организациями.

Для каждой позиции укажите productId, quantity и цену, соответствующую логике вашего канала продаж.

!
Повтор POST

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

Розничный заказ · JSON
{
  "type": "RETAIL",
  "organizationId": 1,
  "externalOrderId": "SHOP-12345",
  "products": [
    {
      "productId": 1422585,
      "quantity": 2,
      "price": 1000
    }
  ]
}

Связанные методы API

POST/api/order/Создать заказGET/api/product/findСопоставить товары

02

Первоначальная выгрузка заказов

Выбирайте заказы страницами с фиксированным limit. count=true используйте только при необходимости показать прогресс или проверить итоговое количество.

Сохраняйте id SelSup и externalOrderId. Перед переходом к следующей странице фиксируйте полученные данные одной транзакцией или атомарным пакетом.

  1. 1

    Зафиксируйте границу выгрузки

    Сохраните время начала, чтобы изменения во время полной выборки затем попали в инкрементальный проход.

  2. 2

    Пройдите все страницы

    Не запускайте несколько страниц одного диапазона параллельно, если сортировка и данные могут изменяться.

  3. 3

    Запустите проход изменений

    После полной загрузки запросите заказы, изменённые начиная с сохранённой границы с небольшим перекрытием.

Связанные методы API

GET/api/order/findНайти заказы

03

Получать изменения без пропусков

Используйте фильтр по modifiedDate, если он присутствует в актуальном контракте метода поиска. Храните курсор только после успешной обработки всей страницы.

Делайте перекрытие временного окна, например несколько минут, и дедуплицируйте по id и modifiedDate. Это защищает от задержек записи и разницы часов между системами.

Обновляйте заказ целиком: могут измениться статус, адрес, состав позиций, маркировка или связанные данные.

i
Время

Храните курсор в UTC в точном формате API. Не округляйте секунды и не используйте локальное время сервера без часового пояса.

Выборка изменений · HTTP
GET /api/order/find?modifiedDate=2026-08-09T10:00:00Z&page=1&limit=100
Authorization: YOUR_API_TOKEN

Связанные методы API

GET/api/order/findИнкрементальный поискGET/api/order/{orderId}Получить заказ по ID

04

Обрабатывать ошибки и расхождения

  1. 1

    Валидируйте до отправки

    Проверяйте организацию, тип заказа, склад, маркетплейс, количество и цену каждой позиции.

  2. 2

    Разделяйте временные и постоянные ошибки

    Ошибка в данных требует исправления, а сетевой сбой — контролируемого повтора после проверки результата.

  3. 3

    Выполняйте сверку

    Периодически сравнивайте статусы и состав заказов за перекрывающийся период, независимо от основного потока изменений.

!
Код ошибки, а не текст

Ветвите обработку по полю error. localMessage локализован для пользователя токена и может меняться.