Импорт товаров на сайт: как проверить данные, ошибки и повтор загрузки

Сначала определите, что именно меняет импорт

«Загрузить товары» может означать создание новых карточек, обновление остатков, перенос описаний или полную замену части каталога. У этих задач разные последствия. Файл с текущим остатком требует установки значения; файл с поступлением — отдельной операции увеличения. Повтор второй операции без защиты способен изменить результат ещё раз.

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

Укажите владельца каждого поля. Например, учётная система может отвечать за остаток, а редактор сайта — за описание и поисковые метаданные. Импорт, которому разрешили менять всё, способен затереть ручную работу корректными с точки зрения формата данными. Обсудите, кто разрешает рабочий запуск и кто разбирает отклонённые строки.

Не выбирайте платформу по одному обещанию импорта. Возможности встроенного инструмента, расширения и заказного обработчика отличаются. Сравнение платформ вынесено в материал WordPress или 1С-Битрикс; здесь задача уже другая — определить и проверить конкретное поведение загрузки.

Разделите ID товара, номер строки и ID запуска

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

Ключ храните в согласованном типе. В учебном наборе 0001 — строка, а не число 1. Если табличный редактор удалил ведущие нули до сохранения CSV, импортёр уже не получит исходное значение. Проверяйте сохранённый файл, а не только красивое отображение ячейки.

Ключи зависят от системы. Встроенный импорт WooCommerce документирует сопоставление обновлений по ID или SKU; Shopify описывает перезапись товаров с совпадающими handles. Это примеры разных контрактов, а не основание объявить один столбец универсальным. Перед работой откройте актуальную схему импортёра WooCommerce или документацию своего инструмента и сверяйте именно установленную реализацию.

Сопоставьте колонки с полями и владельцами данных

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

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

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

Проверяйте файл, строки и связи отдельными проходами

Сначала проверьте формат: кодировку, разделитель, заголовки, кавычки и число колонок. Расширение .csv не определяет все эти параметры. В нашем примере принят UTF-8 с допустимым BOM и разделитель ;. Это его явный контракт; файл с другим разделителем не будет автоматически угадываться.

Затем проверьте значения: обязательные поля, формат ключа, допустимые диапазоны и дубли внутри файла. Два появления одного SKU могут быть ошибкой, вариантом товара или последовательностью обновлений — это зависит от модели. Учебный импорт запрещает повтор SKU в одном пакете; существующий SKU в базе при этом разрешён для обновления. Эти ситуации нельзя смешивать.

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

Чтение CSV само по себе не проверяет бизнес-правила. Например, стандартный модуль Python csv в обычном режиме возвращает строки без автоматического преобразования типов. В нашем сценарии остаток проверяется отдельно. Значения -1, пустая строка и произвольный текст отклоняются; допустимый 0 сохраняется как ноль.

Не смешивайте пустое значение, отсутствие колонки и ноль

Для обновления эти состояния могут означать разные действия. Отсутствующая колонка способна означать «поле не участвует в загрузке», пустая ячейка — «очистить поле» либо ошибку, а ноль — конкретное числовое значение. Универсального поведения CSV здесь нет: оно определяется импортёром и режимом.

В документации Shopify о перезаписи через CSV отдельно описаны пустая необязательная колонка и отсутствующая колонка: в режиме перезаписи их последствия различаются. Не переносите это правило автоматически на другой импортёр. Используйте его как повод проверить поведение своего инструмента на двух отдельных файлах.

Не отдавайте файлу права на все поля карточки

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

В учебном сценарии все четыре колонки обязательны, пустые обязательные значения запрещены. Это упрощённая модель полной записи выбранных полей, а не универсальный частичный импорт. Если проекту нужны «не менять» и «очистить», их следует описать и проверить отдельно, не маскируя одним пустым значением.

Выберите полный отказ или частичное принятие пакета

При строгой политике ошибка любой строки отклоняет весь файл до изменения каталога. При частичном принятии корректные строки могут применяться, а остальные получают отдельный статус. Оба подхода возможны; выбор зависит от связности данных и способа исправления. Важно заранее определить последствия, а не обнаружить их по витрине.

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

В нашем примере выбран полный отказ. Предварительная проверка и пробный прогон не изменяют данные. Применение записей и отметка о завершённом пакете входят в одну транзакцию SQLite. Это свойство конкретной реализации; оно не распространяется автоматически на загрузку файлов, внешние запросы или задачи очереди.

Принимайте изображения, категории и варианты по своим правилам

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

Не объявляйте отсутствие изображения успешной обработкой, если оно обязательно для публикации. Согласуйте промежуточный статус карточки и возможность повторить только неудавшийся шаг. Встроенный CSV-инструмент WooCommerce имеет собственные правила для изображений и ограничение на изменение alt через этот импортёр; стороннее расширение может вести себя иначе.

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

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

Спроектируйте повтор до первой рабочей загрузки

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

В нашем сценарии ключ пакета зависит от байтов файла и версии контракта. Отметка о применении сохраняется вместе с изменениями товаров. Повтор точно такого пакета возвращает ALREADY_APPLIED. Это защита от повторного выполнения принятого задания; она не доказывает актуальность каталога после чужих правок.

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

Что делать, когда результат запуска неизвестен

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

Документация SQLite о транзакциях описывает начало, фиксацию и отмену транзакции, а также возможную занятость базы. Внешние операции требуют своей модели завершения. Сходный вопрос передачи одного обращения разобран в статье об интеграции сайта с CRM; пакет товаров дополнительно требует контроля каждой записи и общих итогов.

Рабочий пример: семь запусков CSV в SQLite

Мы выполнили сценарий со стандартной библиотекой Python и временной SQLite-базой. Исходно в ней две учебные позиции: 0001 с остатком 8 и 0099 с остатком 4. Вторую позицию входные файлы не содержат; по контракту она должна сохраниться. Все названия и остатки придуманы для проверки, это не ассортимент клиента.

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

Исправленный файл содержит три записи: обновление 0001 до 12, создание 0002 с допустимым нулём и создание 0003 с остатком 5. Пробный прогон показывает план: два создания и одно обновление. Он не записывает ни товары, ни отметку о завершённом пакете.

После каждого запуска соединение закрывалось и открывалось заново. Итоговые ключи — 0001, 0002, 0003, 0099: ведущие нули сохранены, отсутствовавшая в файле позиция не удалена. Сбой смоделирован обычным исключением до фиксации, а не отключением питания или падением процесса. Проверка показывает отмену нашей транзакции, но не испытание всех аварийных режимов SQLite.

Скачайте сценарий и учебные CSV, распакуйте архив и выполните python3 import-example.py. Нужен Python 3 со стандартным модулем SQLite; дополнительных пакетов нет. Отчёт появится в evidence/import-example-result.json. SHA256 файлов проверяется по приложенному реестру; сценарий не меняет исходные CSV, не отправляет сетевые запросы и работает с временной базой.

Пример не реализует очереди, конкурирующие запуски, варианты, загрузку медиа и политику нескольких поставщиков. Он не является готовым модулем для CMS. Для рабочего каталога потребуются его схема, права на изменение и протокол по реальным данным.

Как принять импорт у подрядчика

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

Отчёт «создано десять» не заменяет проверку десяти ожидаемых ключей. Аналогично, «ошибок нет» не означает, что источник имел право менять описание. Зафиксируйте неподдерживаемые сценарии и ответственного за исправление файла. Общая приёмка сайта описана в отдельной статье; протокол импорта является её конкретной частью.

Отделите тестовый прогон от разрешения на рабочий импорт

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

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

Для больших файлов проверьте ограничения и поведение конкретного обработчика. Не назначайте универсальный размер пакета или время импорта по маленькому примеру. Частичная обработка, очередь и один общий transaction требуют разных протоколов завершения. Перенос на рабочую систему принимается отдельной проверкой.

Что наблюдать после загрузки

После разрешённого запуска сравните фактические ключи, поля и статусы с отчётом. Затем проверьте витрину: видимость карточек, категории, варианты, изображения и ожидаемое поведение остатка. Отдельно подтвердите обновление внутреннего поиска и кешей, если они участвуют в проекте. Изменение базы не доказывает, что все последующие системы уже обновились.

Разделяйте завершение импорта, публикацию карточки, появление в поиске сайта и результат продаж. Это разные события с разными условиями. Число прочитанных строк не становится числом новых товаров, а новый товар не означает новую заявку.

Для обсуждения с Бадрик Лаб подготовьте пример файла без персональных данных, список изменяемых полей и ожидаемый результат. По ним определим, подходит ли штатный импортёр, нужна ли предварительная обработка или отдельная интеграция. Состав работ обсуждаем на странице интеграций сайта; правила загрузки согласуем до рабочего запуска.