Выгрузка заказов Shopify: принять состав и связи

Сначала определите границы приёмки

Рассматриваем результат уже разрешённой выгрузки через GraphQL Admin API, подготовленной интегратором. Это не инструкция по запуску запросов или выдаче доступа. Владелец задаёт назначение копии, интегратор объясняет состав, проверяющий сохраняет доказательства. Отдельно укажите, кто вправе принять исключение и кто будет использовать итоговый файл.

На 17 октября 2026 года актуальная стабильная версия API — 2026-10. Фактически использованную версию подтверждают по X-Shopify-API-Version, а не по имени локального файла. Версии Shopify.

Попросите карточку выгрузки: магазин, ID операции, точный исходный запрос, выбранные поля и связи, фильтры, смысл временного поля, включённые границы периода и часовой пояс. Добавьте время начала и завершения, имя полученного экземпляра и его контрольную сумму. Технические секреты в этот лист не включают.

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

Отделите записи файла от заказов

Bulk-запрос выполняется асинхронно и возвращает JSONL. Узлы выбранных связей становятся отдельными записями; дочерний узел содержит ссылку __parentId. Это добавляемое поле результата, его не выбирают как обычное поле схемы. Формат bulk-результата.

В справочнике bulkOperationRunQuery для 2026-10 значение groupObjects по умолчанию — false. Поэтому нельзя переносить соседство строк из сгруппированного примера на любой файл. Точная мутация.

Изменение значения по умолчанию связано с версией 2026-01 и отдельно отмечено в журнале изменений Shopify.

rootObjectCount учитывает корневые объекты, objectCount — все обработанные, включая вложенные. Это счётчики хода операции. Их смысл зависит от выбранной структуры. Поля BulkOperation.

Учебный состав: три заказа

В нашем условном запросе нужны только заказы и их непосредственная связь lineItems. Другие связи в модель не входят. Короткие обозначения ниже заменяют реальные ID; это не готовый API-ответ и не данные магазина. Каждый учебный заказ имеет заданный состав:

Контроль: 3 заказа, 1 + 2 + 3 = 6 позиций, 3 + 6 = 9 записей узлов. Количество товара: 2 + 1 + 4 + 1 + 2 + 2 = 12 единиц. Девять записей и двенадцать единиц не означают столько же заказов.

Для локального испытания перемешаем карточки: L4, O102, L1, O103, L6, L3, O101, L5, L2. Это специально изменённая учебная последовательность, а не обещание порядка реального экспорта. Проверяющий должен восстановить тот же перечень независимо от расположения карточек.

Позицию связывают с заказом по __parentId, а не по ближайшей строке. Для учебной L6 ожидается O103. Проверка проходит по всем ID и ожидаемым связям.

Ошибки, которые не видны по общему итогу

Заменим L6 второй копией L5 с тем же количеством 2. Сохранятся девять карточек и двенадцать единиц, но уникальных позиций останется пять. В журнале должны появиться две отдельные причины отказа: повтор L5 и отсутствие ожидаемой L6. Удаление дубля само по себе не возвращает потерянную запись.

Во втором испытании сохраним L6, но назначим ей O102. Общие числа не изменятся; распределение позиций станет 1 / 3 / 2 вместо 1 / 2 / 3. В третьем варианте укажем для L6 отсутствующий O999: возникает ссылка на отсутствующего родителя. Оба результата отклоняются.

Четвёртое повреждение проще: удалим L6 целиком. Получатся восемь карточек, пять позиций и десять единиц. Проверяющий фиксирует конкретную потерю, а не только разницу счётчика. Все четыре случая проверены локальной учебной программой; она не обращается к Shopify и не подтверждает работу производственного импортёра.

Для каждого расхождения сохраняйте исходный экземпляр, этап обработки и минимальный обезличенный фрагмент. Если ошибка появилась после сортировки или преобразования, не исправляйте исходный магазин ради совпадения повреждённой копии. Восстановление маршрута и повторная проверка должны иметь отдельного ответственного.

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

Уведомление finish бывает и при ошибке или отмене. Приёмка требует подтверждённого успешного завершения именно нужной операции. Пустой завершённый результат может иметь null вместо URL. Завершение и получение данных.

partialDataUrl относится к неполному результату неудачной операции. Такой файл оставляют для разбора, не принимают за полный. Обычная ссылка истекает через семь дней после завершения; частичная — после сбоя. Ссылки результата.

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

Отделите полноту файла от доступного охвата

По умолчанию Order охватывает последние 60 дней; более старое обязательство может не попасть в доступный набор. Ограничение Order. Действующий доступ к истории должен быть подтверждён для конкретного приложения. Условия доступа.

Неодобренные защищённые поля могут быть скрыты; GraphQL способен вернуть HTTP 200 вместе с ошибками. Пустоту такого поля нельзя автоматически считать отсутствием сведений у бизнеса. Защищённые данные.

Допустим, владельцу нужен ещё старый O104. Учебные O101–O103 могут быть проверены без ошибок, но требуемый набор из четырёх заказов ещё не принят. Запишите причину исключения и согласованный дальнейший план. Эта проверка не требует самостоятельно расширять разрешения; вопрос недоступного охвата передают ответственному.