Получение только изменившихся данных

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

При чтении по номерам страниц (page) приложение может пропустить записи. Если во время обхода объект обновят или удалят, состав страниц изменится: запись может переместиться на уже прочитанную страницу и не попасть в следующие ответы.

Для последовательного чтения изменившихся записей используются параметры updated_since и from_id. В справочнике они указаны у следующих списков:

GET /admin/products.json
GET /admin/orders.json — чтение, создание и фильтрация описаны в заказах и клиентах
GET /admin/clients.json
GET /admin/collections.json
GET /admin/discount_codes.json
GET /admin/bonus_system_transactions.json

updated_since задаёт время последнего изменения в UTC или с указанием смещения часового пояса. API возвращает объекты, у которых updated_at больше либо равен этому времени. При передаче в URL кодируйте пробелы и знак + в смещении. Например, полночь 4 сентября 2017 года по Москве записывается так:

2017-09-04 00:00:00 +03:00

в запросе:

updated_since=2017-09-04+00%3A00%3A00+%2B03%3A00

При заданном updated_since записи сортируются по возрастанию updated_at, затем по id. Чтобы продолжить чтение, снова запрашивайте первую страницу с новыми значениями фильтра. Не увеличивайте page.

Действие from_id зависит от ресурса. Ниже описаны различия для товаров и коллекций.

Товары

В списке товаров from_id действует только вместе с updated_since. Если передать только from_id, он не ограничит список: товар с указанным идентификатором также может попасть в ответ.

Если передать оба параметра, from_id указывает последний уже обработанный товар. API исключает его и предшествующие записи. В ответ входят товары с более поздним updated_at, а также товары с таким же updated_at, но большим id. Это позволяет последовательно обработать товары, обновлённые одновременно, даже если их тысячи.

Алгоритм:

Запросите группу товаров с сохранёнными updated_since и from_id. Количество записей задайте параметром per_page.
Если массив пуст, сохраните текущее значение updated_since и завершите обход до следующего запуска.
Обработайте полученные товары. Для следующего запроса возьмите у последнего товара updated_at как новое значение updated_since, а id — как новое значение from_id.
Повторяйте запросы, пока не получите пустой массив.

Для товаров API использует per_page не меньше 10. Если передать меньшее значение, размер страницы будет равен 10.

Удалённые товары помечаются archived: true.

deleted=true — только такие товары.
with_deleted=true — и текущие, и удалённые. В этом режиме deleted не действует.

Коллекции

В GET /admin/collections.json параметр updated_since ограничивает список по времени изменения, включая записи с указанным временем. Результат сортируется по updated_at, затем по id.

Параметр from_id не меняет состав и порядок списка коллекций, поэтому алгоритм для товаров здесь неприменим. Для следующего запроса изменяйте updated_since. Учитывайте, что записи с граничным временем могут прийти повторно. Подробнее о списке коллекций — в разделе «Каталог».