Синхронизация и события

При интеграции важно вовремя узнавать о новых заказах, сменах статусов, возвратах и поставках. Для этого есть два механизма, и они дополняют друг друга:

• поллинг — вы сами периодически опрашиваете REST-методы с фильтрами по времени и статусу;
• вебхуки (события) — Lamoda сама шлёт HTTP-запрос на ваш URL, когда что-то меняется.

Синхронизацию лучше строить на поллинге, а вебхуки использовать для быстрой реакции. Даже когда вебхуки настроены, регулярный поллинг всё равно нужен для сверки: доставка событий не гарантирована.

Как устроена синхронизация

Основной подход — инкрементальная синхронизация: вы храните время последней удачной синхронизации, на каждой итерации запрашиваете только то, что изменилось с этого момента, и сдвигаете отметку вперёд.

Важно понимать, по какому полю считается «дельта» — то есть что именно попадает в «изменившееся». Спросить «что нового с момента T» можно только по заказам — по дате обновления. У отгрузок, возвратов и заявок на вывоз фильтры по времени привязаны к бизнес-датам (планируемая дата поставки, дата возврата, дата заявки), а не к моменту изменения записи. Поэтому их синхронизируют иначе: опрашивают по статусу за скользящее окно дат и сверяют с сохранённым состоянием.

Порядок работы

1. Инкрементальный поллинг заказов

Основной цикл синхронизации держится на заказах — только по ним доступна дельта изменений.

• GET /v2/orders — запрашивайте с updatedAtFrom = время последней синхронизации (дата-время в формате RFC 3339, UTC) и фильтром statusGroup (например, AWAITING_SHIPMENT — рабочая очередь FBS). Новую отметку берите как максимальный updatedAt из ответа и добавляйте небольшое перекрытие (несколько минут), чтобы не терять события на границе. Пагинация — через page/limit, общее число страниц приходит в meta.totalPages.

2. Отгрузки (FBS), поставки (FBO), возвраты — по статусу и диапазону дат

У этих ресурсов дельты по изменению нет: опрашивайте их по статусу за скользящее окно дат и сверяйте с тем, что уже сохранили. Названия фильтров в разных доменах не совпадают — сверяйтесь с описанием конкретного метода.

• GET /v2/fbs/shipments, GET /v2/fbo/shipments — фильтр from/to = планируемая дата поставки, плюс status.
• GET /v2/fbs/return-boxes (createdFrom/createdTo), GET /v2/fbs/return-items (returnDateFrom/returnDateTo, status).
• GET /v2/fbs/pickup-requests (date/dateFrom/dateTo, statuses).

3. История статусов — чтобы не пропустить промежуточные переходы

Поллинг и вебхуки показывают текущее состояние. Но между двумя опросами объект может пройти сразу несколько статусов — например, заказ успел смениться Confirmed → Shipped → Delivered, а вы увидите только Delivered. Если вам важна не только последняя точка, но и весь путь (когда и через какие статусы объект прошёл), запросите историю статусов: она возвращает все переходы по порядку, с отметками времени.

Это нужно, например, чтобы восстановить хронологию для аналитики или свериться, когда именно произошёл нужный переход. История доступна для заказов, поставок FBO и возвратов FBS:

• заказ — GET /v2/orders/{orderId}/status-history;
• поставка FBO — GET /v2/fbo/shipments/{shipmentId}/status-history;
• возвратный короб FBS — GET /v2/fbs/return-boxes/{id}/status-history;
• возвратный товар FBS — GET /v2/fbs/return-items/{itemId}/status-history.

4. Вебхуки — для быстрого получения событий

Событие — это POST-запрос от Lamoda на ваш URL при смене статуса заказа, товара или поставки. Тело приходит в формате JSON: { type, trackingId, data }.

Вебхуки не заменяют поллинг, а дополняют его — ускоряют реакцию. Как их подключить, какие бывают типы событий и как выглядит тело — в статьях «Настройка вебхуков», «Типы событий» и «Примеры событий» этого раздела. Если ваш сервис был недоступен и пропустил события, их можно запросить заново — см. «Переотправка нотификаций».

5. Идемпотентность и ежедневная сверка

Одно и то же изменение может прийти дважды — и вебхуком, и поллингом. Обрабатывайте состояние по ключу «id заказа + статус», чтобы повторная обработка была безопасной. Раз в день делайте полный проход по активным statusGroup — так вы поймаете то, что не дошло вебхуками.

Что синхронизировать: FBS и FBO

• FBS: поллинг заказов и отслеживание их статусов; логистика — отгрузки, вывоз, возвраты; остатки держите в актуальном состоянии через POST /v2/fbs/stocks. Типичные события: statusChanged, itemStatusChanged.
• FBO: поллинг заказов для отслеживания; логистика — поставки; остатки GET /v2/fbo/stocks ведёт Lamoda, вы их только читаете; возвратов через API нет. Типичное событие: fulfilmentShipmentStatusChanged.

Особенности

• Дельта по изменению есть только у заказов (updatedAtFrom). У остальных ресурсов фильтр по времени — это бизнес-дата, а не факт изменения записи.
• Фильтр from/to у отгрузок — это планируемая дата поставки, а не время изменения.
• Неизвестный query-параметр молча игнорируется — метод не вернёт 400, поэтому сверяйте имена фильтров с описанием.
• Предельный размер страницы зависит от метода: у заказов и отгрузок — 1000, у номенклатур и цен — 25.

См. также

• Настройка вебхуков
• Типы событий
• Примеры событий
• Переотправка нотификаций