Синхронизация

Заказы, товары и клиенты хранят updatedAt: время последнего изменения. Любая правка записи его сдвигает, будь то статус, оплата, позиции заказа или контакты. На этом строится инкрементальная выгрузка.

Первая выгрузкаCopy Anchor Link

Заберите всё, листая страницы курсором:

curl "https://refsales.ru/api/v1/orders?order=updatedAt:asc&limit=100&with=items" \
  -H "Authorization: Bearer rsk_live_xxx"

Запомните updatedAt последней записи на последней странице. Это ваша точка отсчёта.

Следующие запускиCopy Anchor Link

Запрашивайте записи, изменённые после точки отсчёта:

curl -g "https://refsales.ru/api/v1/orders?order=updatedAt:asc&filter[updatedAt][from]=2026-09-27T18:25:00.418265%2B00:00&limit=100" \
  -H "Authorization: Bearer rsk_live_xxx"

updatedAt приходит в виде 2026-09-27T18:30:00.418265+00:00. Точку отсчёта передавайте в том же формате, закодировав + как %2B, как в примере. Незакодированный плюс API тоже поймёт. Кроме полной даты со временем фильтр принимает дату без времени (2026-09-27), неверная дата вернёт 400.

Фильтр включает границу, поэтому последняя запись прошлого запуска придёт снова. Сверяйте по id и обновляйте её, а не создавайте заново.

После прохода по всем страницам сдвиньте точку отсчёта на updatedAt последней полученной записи минус 5 минут.

Запас нужен потому, что updatedAt фиксирует момент, когда началась правка, а не когда она сохранилась. Правка, которая длилась дольше обычного, может сохраниться уже после вашего запроса с более ранним updatedAt. Без запаса такую запись следующий запуск пропустит. Повторы из этого окна сверяйте по id, как и границу.

ПравилаCopy Anchor Link

• Сортируйте по updatedAt:asc. При desc запись, изменённая во время обхода, может уехать на уже пройденную страницу.
• Курсор привязан к сортировке. Курсор из выдачи createdAt с updatedAt не сработает, API вернёт 400.
• Не опрашивайте чаще раза в минуту: лимит 7 запросов в секунду на ключ делится между всеми вашими процессами.
• Удалённые записи в выдачу не попадают, и инкрементальная выгрузка про удаление не сообщает. Это касается заказов, товаров и клиентов. Раз в сутки делайте полную сверку по id и удаляйте у себя то, чего в API больше нет.

Те же параметры работают для /api/v1/products и /api/v1/customers.

Выгрузка каталога в РефсейлсCopy Anchor Link

Обратное направление, из вашей системы в Рефсейлс, строится на внешних ID. Сначала выгрузите категории, потом товары:

1. PUT /api/v1/references/categories/external/{externalId} для каждой категории. Родителя укажите в parentExternalId, поэтому родителей отправляйте раньше детей.
2. PUT /api/v1/products/external/{externalId} для каждого товара, категорию передайте в categoryExternalId.

Оба метода создают запись при первом вызове и меняют при следующих, так что повтор после сбоя безопасен. Чтобы обновить только остатки, отправляйте { "stockQuantity": 12 }: остальные поля не изменятся.

Если магазин параллельно грузит тот же каталог YML-фидом, фид при следующем импорте перезапишет товары с совпадающим externalId. Выберите один источник.