Импорт файлов

Импорт файлов — способ передать данные без интеграции с API: выгрузка из 1С, Битрикса или таблица Excel загружается в кабинете. Каждая строка файла обрабатывается так же, как соответствующий метод API, поэтому проверки, отказы и правила идемпотентности — те же.

Когда использовать#

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

Как загрузить#

Проект → «Импорт».

1. Выберите шаблон и загрузите файл. У каждого шаблона на странице есть описание колонок и пример файла.
2. Проверьте сопоставление колонок. ДАРА сопоставляет колонки по заголовкам — подписи полей из таблиц ниже и привычные названия выгрузок 1С и Битрикса распознаются сами. Поправьте, что нужно: сопоставление сохраняется и предлагается при следующей загрузке этого шаблона.
3. Запустите проверку. ДАРА показывает первые 20 строк файла и проверяет первые 1000 строк: ошибки по строкам и колонкам, предупреждения, определённые кодировку и разделитель.
4. Запустите импорт. Он идёт в фоне, на странице виден прогресс: сколько строк обработано, принято и отклонено.
5. Заберите итог: счётчики и отчёт об ошибках в CSV.

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

Файлы#

• CSV — кодировка UTF-8 или Windows-1251, разделитель ;, , или табуляция. И то и другое определяется автоматически, BOM учитывается. Выгрузки 1С в Windows-1251 с точкой с запятой открываются как есть, перекодировать файл не нужно.
• XLSX — первый лист книги. Формулы берутся сохранённым значением: если файл сохранён без значений формул, такие ячейки считаются пустыми.
• .xls не принимается — пересохраните файл как .xlsx или CSV. Файл под паролем тоже не принимается.
• Первая непустая строка — заголовок. Колонок в заголовке не больше 200.
• Размер — до 100 МБ, до 1 000 000 строк в файле.

Кодировка определяется по всему файлу. Если начало файла выглядит как UTF-8, а дальше встречаются строки в Windows-1251 (так бывает у склеенных выгрузок), импорт останавливается до записи первой строки с кодом encoding_mismatch — выберите кодировку вручную на странице проверки и запустите снова. Отдельные нечитаемые строки кодировку не меняют: они отклоняются с кодом invalid_encoding.

Даты и время#

Принимаются:

• ГГГГ-ММ-ДД и ГГГГ-ММ-ДД ЧЧ:ММ[:СС], можно с Z или смещением;
• ДД.ММ.ГГГГ и Д.М.ГГГГ, со временем или без — формат 1С 14.09.2026 0:00:00 читается как есть;
• дата Excel — ячейка с форматом даты в XLSX.

Время без часового пояса в файле считается московским и переводится в UTC. Это отличие от API: там время без зоны отклоняется с кодом invalid_datetime. Дата без года (14.09), двузначный год и формат ММ/ДД/ГГГГ не распознаются — такая ячейка даёт invalid_date.

Значения в ячейках#

• Пустая ячейка — значение не передано. В каталоге это значит «поле пустое» (строка заменяет объект целиком), в профилях — «поле не меняется»: очистить поле профиля файлом нельзя, только методом API.
• Списки (интересы, авторы, несколько медиа) — в одной ячейке через вертикальную черту: велоспорт|походы.
• Да и нет — да, истина, true, 1, yes, y и нет, ложь, false, 0, no, n, регистр не важен.
• Числа — разделитель дробной части точка или запятая, пробелы и неразрывные пробелы внутри числа игнорируются: 1 234,50 — это тысяча двести тридцать четыре с половиной.
• Пробелы по краям ячейки отбрасываются, в том числе у идентификаторов: 1С и Excel часто дописывают их.
• Перечисления (тип объекта, статус заказа, пол) принимаются кодом или русским словом: video и видео, created и создан, female и женский.
• Любую несопоставленную колонку можно записать в свойства объекта или строки заказа (properties.<заголовок>) либо в атрибуты пользователя (attributes.<заголовок>). Колонки с персональными данными в атрибуты не предлагаются: ДАРА их не принимает.
• Относительные ссылки (/upload/iblock/… в выгрузках Битрикса) дополняются до абсолютных, если на странице проверки указан адрес сайта.

Шаблон «Каталог»#

Строка файла — объект; загрузка равна PUT /items/{id}: объект заменяется целиком, поля без колонок очищаются. Загруженные объекты встают в очередь анализа, как переданные по API, и учитываются в месячном объёме анализа.

У объектов типа text нужен заголовок, описание или текст; у video, audio и image — хотя бы одно медиа своего вида.

Пример: items.csv, items.xlsx.

Шаблон «Профили»#

Строка файла — пользователь; загрузка равна POST /users/profile: меняются только переданные поля.

Персональные данные — имя, телефон, email, адрес, паспорт, дата рождения — не принимаются: строка получает отказ pii_not_allowed. Подробно — Данные о пользователях.

Пример: profiles.csv, profiles.xlsx.

Шаблон «Заказы»#

Строка файла — строка заказа. Строки с одним номером собираются в заказ по всему файлу, поэтому порядок строк не важен, и заказ отправляется целиком, как POST /orders.

• Поля заказа — покупатель, дата, статус — берутся из первой строки заказа. Если в другой строке того же номера стоит другое непустое значение, весь заказ отклоняется с кодом order_conflict.
• Неразборчивые количество или цена («две», 1,2,3) отклоняют свою строку с кодом invalid_number — остальные строки заказа загружаются.
• Повторная загрузка заменяет состав заказа: новые строки добавляются, пропавшие отменяются.
• Если у проекта нет активного типа события с флагом «покупка», импорт заказов не запускается: код no_purchase_type.

Пример: orders.csv, orders.xlsx, выгрузка 1С в Windows-1251: orders-1c-cp1251.csv.

Номера документов 1С#

order_id в API — до 64 печатных символов ASCII, а номера документов 1С выглядят как ЦБ-000123 или ТД00-000045. Номер, в котором есть символы вне печатного ASCII, переводится в ключ заказа: транслитерация номера, знак ~ и восемь шестнадцатеричных знаков хеша исходного номера.

ЦБ-000123 → TSB-000123~0a191c24

Ключ получается одинаковым у CSV в Windows-1251, CSV в UTF-8 и XLSX, поэтому повторная загрузка того же файла в другом формате заказ не удваивает. Этот ключ и есть order_id заказа в API: GET-сверка, POST /orders и события покупок работают с ним. Номер из файла сохраняется рядом и виден в кабинете.

Транслитерация — как в загранпаспортах (ICAO Doc 9303), заглавными буквами:

Номера, повторяющиеся по годам. В 1С нумерация документов часто начинается заново каждый год, и ЦБ-000123 за 2025 и 2026 год — разные заказы. Отметьте на странице проверки «Номера документов повторяются по годам»: к ключу добавится год даты заказа (TSB-000123~0a191c24@2025). Без отметки такие строки соберутся в один заказ и, скорее всего, отклонятся с кодом order_conflict — проверка предупреждает об этом кодом order_id_repeats_by_year.

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

Шаблон «События»#

Строка файла — событие; загрузка равна POST /events.

• Без колонки идентификатора повтор события узнаётся по хешу строки: те же поля — то же событие, повторная загрузка файла счётчики не удваивает.
• Показы файлом не загружаются: строки типов с флагом «показ» отклоняются с кодом impression_not_importable. Дедупликация показов рассчитана на двое суток, и загрузка того же файла позже удвоила бы статистику.
• Без колонки даты строки записываются временем загрузки — проверка предупреждает об этом кодом no_occurred_at.
• События покупки, чьи заказы переданы шаблоном «Заказы» или методом заказов, отклоняются с кодом order_managed: один заказ — один способ.

Пример: events.csv, events.xlsx. В примере покупка ссылается на номер ЦБ-000301 — он не встречается в примере выгрузки 1С, поэтому оба примера можно загрузить в один проект.

Проверка и отчёт об ошибках#

Проверка разбирает первые 1000 строк файла и останавливается раньше, если результат перестаёт помещаться — по объёму (8 МБ) или по времени (17 секунд). Тогда появляется предупреждение check_partial: проверена часть строк. На странице показываются первые 200 ошибок и сводка по кодам; остальные ошибки видны в отчёте после импорта.

Отчёт — файл report.csv со страницы импорта: UTF-8 с BOM, разделитель ;, перевод строки CRLF, заголовок Строка;Колонка;Код;Ошибка. Он открывается в Excel двойным щелчком.

• «Строка» — номер строки файла, как его показывает Excel.
• «Колонка» — заголовок колонки; у XLSX перед заголовком стоит её буква. Пусто — ошибка относится ко всей строке.
• «Код» и «Ошибка» — код из таблиц ниже и его текст по-русски.
• Значений ячеек в отчёте нет: файл есть у вас, а в отчёте могли бы оказаться персональные данные.
• В отчёт попадает не больше 1 000 000 строк.

Коды: файл и проверка#

Такая ошибка останавливает импорт целиком: ни одна строка не записывается.

Коды: разбор строки#

Строки с кодом empty_profile считаются принятыми: это пометка, а не отказ.

Коды: отказ при записи#

Те же коды, что у методов API: Объекты, События и заказы, Данные о пользователях, Ошибки и лимиты.

Предупреждения проверки#

Не мешают запуску, но стоит прочитать.

Итог импорта#

Паузы#

Импорт уступает дорогу выдаче и анализу и на время встаёт на паузу; причина видна на странице импорта.

Повторная загрузка, сбой, отмена#

• Повторная загрузка не удваивает данные: объекты узнаются по идентификатору, заказы — по ключу заказа и товару, события — по идентификатору или хешу строки, профили заменяют переданные поля.
• Строки пишутся пачками по 500 строк или 8 МБ данных — что раньше. Если импорт прервался — сбой, перезапуск службы, отмена, — записанное остаётся, а «Продолжить» на странице импорта дочитывает файл с последней подтверждённой строки.
• «Продолжить» использует сохранённое сопоставление. Оно не меняется после первой записанной строки: иначе часть файла пришла бы по одним колонкам, а часть — по другим. Нужны другие колонки — загрузите файл заново.
• Отмена останавливает импорт на ближайшей пачке. Уже записанные строки остаются: отката событий и заказов нет.

Хранение#

• Файл и отчёт удаляются через 7 дней после загрузки. «Продолжить» срок не продлевает.
• Исходный файл удаляется сразу после успешного импорта; отчёт живёт до конца срока.
• После удаления файлов история загрузки остаётся, а «Продолжить» и отчёт — нет.
• Суммарный объём файлов импорта одного клиента — до 1 ГБ. Когда он исчерпан, новая загрузка не принимается: отмените незапущенные импорты или дождитесь удаления старых файлов.
• Если на сервере мало свободного места, загрузка временно отклоняется с просьбой повторить позже — импорт не занимает место, нужное базе данных.